Introduction

This article provides step-by-step instructions on how to set up multiple client connections and bridge queues to obtain optimal message throughput using WebSphere MQ Everyplace Gateway V2. MQe_Script commands are also provided to create these objects (although they can also be created using other WebSphere MQ Everyplace tools or administration messages).

It does not provide instructions or code on how to create the necessary WebSphere MQ objects, so you should consult the user documentation provided with WebSphere MQ or the example supplied with the MQe_Script supportPac.

This article requires that you have knowledge of WebSphere MQ Everyplace and WebSphere MQ.

Back to top

Performance concerns

When using WebSphere MQ Everyplace, you can create a gateway to let messages flow to WebSphere MQ. You will need to create certain WebSphere MQ Everyplace objects to configure the gateway. These objects include a bridge, queue manager proxy, client connection, bridge queue, and optionally a transmission queue listener if messages are also to be sent from WebSphere MQ back to WebSphere MQ Everyplace.

In a standard configuration, a single-client connection is created along with a single bridge queue. This is sufficient to start sending messages from WebSphere MQ Everyplace to WebSphere MQ.

If there are multiple clients (large number) connecting to the gateway, the number of messages sent per second through to WebSphere MQ decreases.

Gateway configuration

As Figure 1 shows, if there are multiple clients connecting to the gateway queue manager through the communications listener, a bottleneck can be created by the bridge queue. To alleviate this problem, you can create multiple bridge queues, client connections, server connection channels, and sync queues.

Care needs to be taken when deciding the number of bridge queues to create as there is a point at which the performance of the gateway decreases with an increased number of bridge queues.

Back to top

Performance increase

By creating a WebSphere MQ Everyplace network that uses multiple bridge queues, the number of messages per second that can be sent through the gateway could be dramatically increased.

The number of messages sent through the gateway is not only dependent upon the configuration of your gateway but on other issues such as the type of messages being sent, network configuration, and hardware.

In one test scenario, it was found that when approximately 1,350 clients were connecting to a gateway the increase in the number of messages being sent per second between a single bridge queue and 10 bridge queues was 34 fold. This rose to an 86 fold increase when comparing a single bridge queue to 50 bridge queues but comparing a single bridge queue to 1,350 bridge queues the increase dropped back to 34 fold.

Please observe that this increase is only related to messages being sent to WebSphere MQ Everyplace and not messages received from WebSphere MQ Everyplace.

Back to top

Finding and creating the optimal configuration

To find the optimal configuration for your setup, you need to create the WebSphere MQ Everyplace objects and perform tests to measure the throughput of messages. This empirical testing should ideally take place on a similar network to the production network, using production type message data.

Use the SupportPac MQe_Script to create tests that are both easy to configure and repeatable. This SupportPac is a command line based tool for creating and administering WebSphere MQ Everyplace resources. MQe_Script embeds a scripting language called TCL that you can use to write intelligent scripts that add logic and control. You can download this SupportPac from the Business Integration SupportPacs Web site. To access the download from this site, select the WebSphere MQ Everyplace product from the list box.

Using MQe_Script, you can write scripts that create all the necessary objects on the gateway, and optionally the clients. Parameters can be passed into a script in such a way that the script takes in the number of required bridge queues. As a result, the bridge queues and all the other relevant WebSphere MQ Everyplace objects are created.

By using this method to create WebSphere MQ Everyplace configurations, you can quickly and easily experiment with the number of bridge queues required to achieve the desired throughput. Once you write the script, no extra programming is required.

MQe_Script can even be used to modify any existing configurations that may exist.

Although MQe_Script does not modify WebSphere MQ objects, these can be created using MQSC commands. MQe_Script does come with an example MQSC script showing how to create the WebSphere MQ objects necessary to communicate with a WebSphere MQ Everyplace gateway.

Setting up the gateway

This is what is required to set up the gateway:

1. The gateway requires a single instance of a bridge object and a single instance of a WebSphere MQ queue manager proxy object.
2. Next, you need to create the client connection objects. How many client connection objects you need to create will depend on how many bridge queues are required.
3. Finally, you need to create the bridge queues with each one using a different client connection.

Setting up the clients

Each client must have a remote queue definition to the WebSphere MQ queue. If multiple bridge queues are being used on the gateway, an alias is needed on the remote queue definition so that any application putting messages via a client gets the correct path to the WebSphere MQ queue. This also helps as applications do not have to be aware of the clients putting to different queues.

For example, if 3 clients existed each putting to separate bridge queues, b1, b2, and b3, all remote queue definitions could have an alias of b. Any application putting to the clients can then simply put to queue b. This allows changes in the underlying network without having to make any changes to the application.

To utilize all the bridge queues created on the gateway, and therefore achieve optimal message throughput, the bridge queues should be equally divided among all the clients. Therefore, if there are 50 bridge queues and 5,000 clients, 100 clients should create a remote queue definition to bridgeq1, another 100 should create a remote queue definition to bridgeq2 and so on.

Steps to create the gateway

The basic steps and code snippets to create a gateway are defined below. The MQe_Script commands used in this section are provided as a full script later in this document along with any undefined variables.

1. Create a queue manager.
   
   

   To create a basic queue manager, provide a name and disk location. The disk location is where the registry will be saved to and any messages for queues. See the code example in Listing 1 below.

   Listing 1. Code snippet creates a queue manager

   mqe_script_qm -create -qmname $GATEWAYQM -qmpath $PATH

   
   
2. Start the queue manager

   The command used here does not specify a queue manager name to load. This is because if used directly after a create command, the queue manager details are cached. For more information on how to load a previously created queue manager, please see the documentation accompanying MQe_Script. See the code example in Listing 2 below.

   Listing 2. Code snippet starts the queue manager

   mqe_script_qm —load

   
   
3. Create a listener.

   The listener must be given a name and a port to listen on. Optionally, the type of adapter can be specified if it is something other than the default (TCPIP HTTP). See the code example in Listing 3 below.

   Listing 3. Code snippet creates a listener

   mqe_script_listen -create -listenname $LISTENER -port $GATEWAYPORT

   
   
4. Start the listener.

   By default, listeners are not started after they are created. Once the queue manager has been stopped and restarted, however, the listener will then start automatically. See the code example in Listing 4 below.

   Listing 4. Code starts the listener

   mqe_script_listen —start -listenname $LISTENER

   
   
5. Create a bridge.

   An arbitrary name is needed for the bridge object. This acts as the parent for all the other bridge related objects. See the code example in Listing 5 below.

   Listing 5. Code snippet creates a bridge

   mqe_script_bridge -create -bridgename $BRIDGE

   
   
6. Create a queue manager proxy.

   The queue manager proxy must be associated with the bridge object previously created. It must also be named according to the name of the WebSphere MQ queue manager with which the connection will take place. Finally, the IP address or hostname of the machine on which the WebSphere MQ queue manager is defined is required. See the code example in Listing 6 below.

   Listing 6. Code snippet creates a queue manager proxy

   mqe_script_mqproxy -create -proxyname $PROXY -bridgename $BRIDGE -hostname $ADDRESS

   
   
7. Create a connection definition to the WebSphere MQ queue manager.

   A special MQ connection must be created to define the WebSphere MQ queue manager. This needs to have the same name as the WebSphere MQ queue manager. See the code example in Listing 7 below.

   Listing 7. Creates a connection definition to the WebSphere MQ queue manager

   mqe_script_condef -create -cdname $PROXY -type mq

   
   
8. Optionally, to receive messages back from WebSphere MQ, create multiple transmission queue listeners.

   If a transmission queue listener is required, it must be associated with the client connection channel, queue manager proxy, and bridge objects previously created. It must have the same name as the transmission queue on the WebSphere MQ queue manager. See the code example in Listing 8 below.

   Listing 8. Creates multiple transmission queue listeners

   mqe_script_mqlisten -create -listenname $LISTEN -clientconnname $CC$j -proxyname $PROXY -bridgename $BRIDGE

   
   
9. Create multiple bridge queues.

   A name must be provided for the bridge queue. Under normal circumstances, the bridge queue names reflect the name of the WebSphere MQ destination queue. An alternative way of linking the bridge queue to the WebSphere MQ queue is to use an additional parameter, the MQ Queue Name, which allows the name of the bridge queue to be something different. It is this latter approach than needs to be taken when defining multiple bridge queues. Each bridge queue must be associated with an individual client connection. In other words, there is a one-to-one relationship. The bridge queue also needs to be associated with the bridge and the queue manager proxy, thus, linking the bridge queue to a specific WebSphere MQ queue manager, queue, and connection. See the code example in Listing 9 below.

   Listing 9. Creates multiple bridge queues

   mqe_script_bridgeq -create -qname $BRIDGEQ$j -bridgename $BRIDGE -destination $PROXY -mqqname $REALBRIDGEQ -clientconnname $CC$j

   
   
10. Start the bridge.

    Starting the bridge will by default start all the child objects too. If you have created transmission queue listeners and your WebSphere MQ queue manager is not contactable, this may result in the transmission queue listener failing to start. This is something to watch out for as the command may come back as successful even if all the child objects were not started. On the other hand, an error may be thrown and you may wish to ignore it and carry on with the script. Each of the child objects can be started individually if preferred. See the code example in Listing 10 below.

    Listing 10. Code snippet starts the bridge

    mqe_script_bridge -start -bridgename $BRIDGE

    
    

Steps to create the client

The basic steps to create a client are defined below. The MQe_Script commands to accompany these are provided later in this document along with any undefined variables.

1. Create a queue manager.

   Provide a name and disk location. See the code example in Listing 11 below.

   Listing 11. Code snippet creates a queue manager

   mqe_script_qm —create —qmname $CLIENT —qmpath $PATH

   
   
2. Start the queue manager.

   See the code example in Listing 12 below.

   Listing 12. Code snippet starts the queue manager

   mqe_script_qm —load

   
   
3. Create a connection definition to the gateway queue manager.

   The connection definition must have the same name as the gateway queue manager. Define the port on which the gateway is listening and if the gateway is listening on an adapter other than the default this must also be defined. See the code example in Listing 13 below.

   Listing 13. Code snippet creates a connection definition to the gateway queue manager

   mqe_script_condef —create —cdname $GATEWAYQM —port $PORT —address $ADDRESS

   
   
4. Create a via connection definition to the WebSphere MQ queue manager.

   The client must know about the WebSphere MQ queue manager in order to put messages to its queues. A via connection can be created where the name of the connection is the WebSphere MQ queue manager name and the via name is the gateway queue manager. See the code example in Listing 14 below.

   Listing 14. Code snipped creates a via connection definition to the WebSphere MQ queue manager

   mqe_script_condef —create —cdname $MQNAME —viaqmname $GATEWAYQM

   
   
5. Create a remote queue definition to the bridge queue and add an alias.

   The name of the remote queue definition must match one of the bridge queues defined on the gateway. The queue manager name of the WebSphere MQ queue manager must also be defined.

   To use multiple bridge queues where the bridge queue name is not the same as the real WebSphere MQ queue name, aliases must be used. An application cannot use a bridge queue name on the gateway as the queue name of the WebSphere MQ queue because that queue does not exist on the WebSphere MQ queue manager.

   Also, the remote definition of the queue can not be called the real WebSphere MQ queue name as that reference does not exist on the gateway queue manager. It is therefore useful to add the actual name of the WebSphere MQ queue as an alias to the remote queue definition so that applications know exactly where the message should be sent to. See the code example in Listing 15 below.

   Listing 15. Creates a remote queue definition to bridge the queue and add an alias

   mqe_script_sproxyq —create —qname $BRIDGEQ$BRIDGEQNUM —destination $MQNAME —alias $REALBRIDGENAME

   
   

   When using MQe_Script, the alias can be added at the time of creation or as an update in a later stage if the remote queue definition already exists.

6. Test the connection by sending a message from the client to the WebSphere MQ queue manager.

   For applications to make the same call, independent of which client they are putting messages to, the message can be put using the alias of the remote queue definition. See the code example in Listing 16 below.

   Listing 16. Code snippet tests the connection

   mqe_script_msg —put —qname $REALBRIDGENAME —qmname $MQNAME

   
   

Back to top

Tips on writing a script

When writing a script, it is often easier to define a set of variables at the beginning of the script. This makes any changes to the naming conventions or number of WebSphere MQ Everyplace objects easier to manage.

In TCL, variables are defined using the set command and referenced using a $ in front of the variable name.

It is also useful to define variables in capital letters so that they can easily be identified within a script. See the code example in Listing 17 below.

set PATH "C:\\MQeScript\\gateway"

When calling MQe_Script commands, they can be defined on their own or TCL control structures can be added to provide feedback on the success of the command and potentially exit the script if errors occur.

One method of checking the success of a command is to use an if / else block with a catch command. See the code example in 18 below.

if { [catch {mqe_script_qm -create 
   -qmname $GATEWAYQM -qmpath $PATH} error] } {
		puts "An error occurred creating queue manager";
		puts "The reason was: $error"
		exit
} else {
	puts "Queue manager created"
}

As the code snippet in Listing 19 shows, the puts command is used to print text to the screen and the exit command stops the execution of the script. If any errors are thrown, the error text is saved in the variable named 'error' and can then be accessed.

If a script is being written to create a number of bridge objects defined by a variable, the creation of those objects can be placed inside a loop. The easiest method of creating multiple objects is to have a standard name for each of the objects then add a number to each of them so they are unique. See the code example in Listing 19 below.

for {set j 1} {$j <= $QNUM} {incr j} {

	#create all the client connections

mqe_script_mqconn -create -clientconnname $CC$j 
-proxyname $PROXY -bridgename $BRIDGE -syncqname $SYNCQ$j -port $PORT

}

Listing 20 shows how names can be created using a loop variable. $CC is already defined as a client connection name prefix and $SYNCQ as a sync queue name prefix.

The code snippet in Listing 20 also introduces the use of the # to define a comment.

To supply MQe_Script with a script file, it must be saved with a tcl extension and the command to supply a script is the source command. See the code example in Listing 20 below.

source {C:\MQeScript\gatewayscript.tcl}

For more information on TCL and writing scripts, refer to the documentation accompanying MQe_Script.

Sample script to create a gateway

You can use the sample script below to create a gateway.

set PATH "C:\\MQeScript\\gateway"
set ADDRESS 127.0.0.1
set GATEWAYQM gatewayqm
set LISTENER listener
set GATEWAYPORT 1881
set PROXY QM_jane
set BRIDGE bridge
set REALBRIDGEQ mqlocalq
set CC FOR.GATEWAYQM.
set LISTEN togateway
set BRIDGEQ bridgeq
set SYNCQ SYNC.QUEUE.
set PORT 1414
set QNUM 50 

#create the gateway queue manager

if { [catch {mqe_script_qm -create -qmname 
   $GATEWAYQM -qmpath $PATH} error] } {
		puts "An error occurred creating queue manager";
		puts "The reason was: $error"
		exit
} else {
	puts "Queue manager created"
}

#load the queue manager

if { [catch {mqe_script_qm -load} error] } {
		puts "An error occurred loading queue manager";
		puts "The reason was: $error"
		exit
} else {
	puts "Queue manager loaded"
} 

#create the listener

if { [catch {mqe_script_listen -create -listenname 
   $LISTENER -port $GATEWAYPORT} error] } {
		puts "An error occurred creating a listener";
		puts "The reason was: $error"
		exit
} else {
	puts "Listener created"
} 

#create a bridge

if { [catch {mqe_script_bridge -create -bridgename $BRIDGE} error] } {
		puts "An error occurred creating bridge";
		puts "The reason was: $error"
		exit
} else {
	puts "Bridge created"
}

#create a mq proxy

if { [catch {mqe_script_mqproxy -create -proxyname 
   $PROXY -bridgename $BRIDGE -hostname $ADDRESS} error] } {
		puts "An error occurred creating proxy";
		puts "The reason was: $error"
		exit
} else {
	puts "MQ queue manager proxy created"
}

#create a connection to the WebSphere MQ queue manager

if { [catch {mqe_script_condef -create -cdname 
   $PROXY -type mq} error] } {
		puts "An error occurred creating connection 
		for the MQ queue manager";
		puts "The reason was: $error"
		exit
} else {
	puts "Connection to MQ queue manager created"
}

#create the client connections, listeners and bridge queues


for {set j 1} {$j <= $QNUM} {incr j} {

	#create all the client connections

	if { [catch {mqe_script_mqconn -create -clientconnname 
	   $CC$j -proxyname $PROXY 
	   -bridgename $BRIDGE -syncqname $SYNCQ$j -port $PORT} error] } {
		puts "An error occurred creating client connection $CC$j";
		puts "The reason was: $error"
		exit
	} else {
		puts "client connection created"
	} 

	#create all the listeners on the new client connections
		
	if { [catch {mqe_script_mqlisten -create -listenname 
	   $LISTEN -clientconnname $CC$j 
	   -proxyname $PROXY -bridgename $BRIDGE} error] } {
		puts "An error occurred creating listener 
		   $LISTEN on client connection $CC$j";
		puts "The reason was: $error"
		exit
	} else {
		puts "listener created"
	}  

	#create all the bridge queues

	if { [catch {mqe_script_bridgeq -create -qname 
	   $BRIDGEQ$j -bridgename $BRIDGE
	    -destination $PROXY -mqqname 
	    $REALBRIDGEQ -clientconnname $CC$j} error] } {
		puts "An error occurred creating bridge queue $BRIDGEQ ";
		puts "The reason was: $error"
		exit
	} else {
		puts "bridge queue created"
	} 	
}

# We've finished the script... lets close the queue manager

if { [catch {mqe_script_qm -unload} error] } {
	puts "Failed to stop the queue manager"
	puts "The reason was: $error"
	exit
} else {
	puts "Queue manager stopped"
}
puts "CreateGatewayQM script completed successfully"
exit 0

Sample script to create a client

This script only shows the basic MQe_Script commands to save duplication. Control structures could be placed around the commands or they could be run as is. For this script to run successfully, the queue manager created by the gateway script must be running as must the WebSphere MQ queue manager.

set CLIENT client1
set PATH "C:\\MQeScript\\client"
set ADDRESS 127.0.0.1
set GATEWAYQM gatewayqm
set PORT 1881
set BRIDGEQ bridgeq
set BRIDGEQNUM 1
set REALBRIDGENAME mqlocalq
set MQNAME QM_jane

mqe_script_qm —create —qmname $CLIENT —qmpath $PATH

mqe_script_qm —load

mqe_script_condef —create —cdname $GATEWAYQM —port $PORT —address $ADDRESS

mqe_script_condef —create —cdname $MQNAME —viaqmname $GATEWAYQM

mqe_script_sproxyq —create —qname $BRIDGEQ$BRIDGEQNUM —destination $MQNAME —alias $REALBRIDGENAME

mqe_script_msg —put —qname $REALBRIDGENAME —qmname $MQNAME

Back to top

Conclusion

Using multiple bridge queues and client connection objects can dramatically increase the throughput of messages from WebSphere MQ Everyplace to WebSphere MQ. However there are no concrete figures for these performance increases since it is dependent on more than the WebSphere MQ Everyplace configuration.

MQe_Script can be used to create these configurations with the ability to make simple changes to affect how many objects are created, which is an important part of achieving the optimal number for your individual setup.

Back to top

Download

Description	Name	Size	Download method
Code samples	scripts.zip	2KB	FTP|HTTP

Information about download methods

Resources

• Visit the Business Integration Web site to download the MQe_Script supportPac.
  
  
• Get WebSphere MQ user documentation from the WebSphere MQ family Web site.
  
  

About the author

Jane Stockdill is a software developer at IBM Hursley where she has been working on WebSphere MQ Everyplace for the past four years.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Performance concerns
• Performance increase
• Finding and creating the optimal configuration
• Tips on writing a script
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere MQ
• Webcast: A smarter way to successful SOA - Information as a trusted strategic asset
• Briefing: WebSphere flexible business processes for a smarter planet
• Buy: WebSphere MQ

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers