Moving large data objects in a WebSphere MQ cluster using Reference Messages

Document options Document options requiring JavaScript are not displayed Sample code Rate this page Help us improve this content

Level: Intermediate

Ramzi Choueri (r.choueri@fr.ibm.com), IT Architect, IBM Application Innovation Services, IBM

12 Sep 2007

This article shows you how to move large data objects between clustered queue managers when using WebSphere MQ, by extending the WebSphere MQ Reference Message sample so it can be used in a clustered environment.

Introduction

IBM® WebSphere® MQ provides a reliable, secure, high-speed, widely connected messaging backbone for SOA solutions. This article shows you how to enable the efficient movement of large data objects in the flexible and scalable clustered WebSphere MQ environment.

The scenario in this article involves a chain store IT department that leverages its existing WebSphere MQ environment to move large inventory data objects using the Reference Message sample. Later in the scenario, the IT department team extends the Reference Message sample to change its WebSphere MQ environment from a distributed queuing configuration to a clustered configuration in order to benefit from the ease of administration provided by WebSphere MQ clusters.

The Reference Message sample programs section in the WebSphere MQ Information center describes how to set up the solution in a distributed queuing environment. This article shows how you can extend this solution with minimal coding so that it can be used in a clustered environment to enable movement of large data objectsbetween clustered queue managers.

This method lets you transfer a large object from one node to another without storing it on WebSphere MQ queues at the source or destination node. Instead, you specify a message exit at both ends of a channel. WebSphere MQ provides a sample message exit for the Reference Message solution.

WebSphere MQ defines the format of a reference message header (MQRMH), which is recognized by means of a defined format name and may be followed by actual data. To initiate transfer of a large object, an application can put a message consisting of a reference message header with no data following it. As this message leaves the node, the message exit retrieves the object in an appropriate way and appends it to the reference message. It then returns the message (now larger than before) to the sending Message Channel Agent (MCA) for transmission to the receiving MCA.

Another message exit is configured at the receiving MCA. When this message exit sees one of these messages, it creates the object using the object data that was appended and passes on the reference message without it. The reference message can now be received by an application, which knows that the object has been created at this node.

Supported platforms

The configuration described in this article has been tested with WebSphere MQ V6.0.2.1 on Microsoft® Windows® XP Professional SP1 or later (32-bit versions only).

Scenario

The following scenario is from Setting up a new cluster in the WebSphere MQ information center.

A chain store has two branches, one in New York and one in London. The data and applications are hosted by systems running separate queue managers. The inventory application runs on the system in New York, connected to the queue manager NEWYORK. The application is driven by the arrival of messages on the INVENTQ queue, hosted by NEWYORK.

In London, inventory data is sent to the inventory application by users. Intercommunication between LONDON and NEWYORK is implemented with distributed queuing techniques.

The business is growing: need to process more data in one row

Activity in the store grows quickly and the staff must execute the sending task many times per day, because the maximum inventory data object size allowed by the system is only 4 MB. They ask the IT department if there is a way to send more data in a row. Handling messages greater than 4 MB long in the WebSphere MQ information center shows several ways to handle large objects using an existing WebSphere MQ environment. One approach is to increase the Queue Manager, Queues, and Channels maximum message size. However, this solution increases the memory usage of the system, and it does not allow data objects larger than 100 MB.

The IT department decides to use the Reference Message Solution to transfer large data files to the Inventory application. This solution lets you send files larger than 100 MB and still maintains low memory usage.

The chain store is growing: need to ease administration

The chain store is growing, and new branches are being set up. From the IT perspective, new queue managers will need to be connected to NEWYORK so that new branch applications can send data to the inventory application. This involves creating many objects on both NEWYORK and the new queue managers.

The IT department considers using clusters to ease system administration. The department wants to keep the Reference Message method to move large data objects, but they don't know if there is a way to set up this solution in a clustered environment. WebSphere MQ provides a sample exit for Reference Message, which is intended to be deployed on the following channels: sender, server, receiver, and requester. This exit, which is the key element of the solution, does not handle cluster-sender and cluster-receiver channels. The sections below explain:

• How to set up the Reference Message solution in a distributed queuing environment using the Reference Message sample exit.
• How to edit and deploy the sample exit to set up the solution in a clustered environment, so that the chain store branches can still send large data objectsto the inventory application.

Setting up the Reference Message solution in a distributed queuing environment

Assumptions:

• You have two queue managers named LONDON and NEWYORK.
• LONDON has a TCP listener running on port 1515 and NEWYORK is listening on port 1616.
• The installation directory of WebSphere MQ is C:\IBM\WebSphere MQ.

To set up and test the solution:

1. Copy the amqsxrm.dll file from C:\IBM\WebSphere MQ\Tools\c\Samples\Bin to C:\IBM\WebSphere MQ\exits.
2. Issue the following MQSC commands on LONDON:
   
   Listing 1. MQSC commands on LONDON
   

   DEFINE CHL(LONDON.NEWYORK) + CHLTYPE(SDR) + TRPTYPE(TCP) + CONNAME('localhost(1616)') + XMITQ(NEWYORK) + MSGDATA(FLATFILE) + MSGEXIT('amqsxrm.dll(MsgExit)') + REPLACE DEFINE CHL(NEWYORK.LONDON) + CHLTYPE(RCVR) + TRPTYPE(TCP) + REPLACE DEFINE QL(NEWYORK) + USAGE(XMITQ) + TRIGGER + TRIGDATA(LONDON.NEWYORK) + INITQ(SYSTEM.CHANNEL.INITQ) + REPLACE DEFINE QR(INVENTQ) + RNAME(INVENTQ) + RQMNAME(NEWYORK) + XMITQ(NEWYORK) + REPLACE END

   
   
3. Issue the following MQSC commands on NEWYORK:
   
   Listing 2. MQSC commands on NEWYORK
   

   DEFINE CHL(LONDON.NEWYORK) + CHLTYPE(RCVR) + TRPTYPE(TCP) + MSGEXIT('amqsxrm.dll(MsgExit)') + MSGDATA(FLATFILE) + REPLACE DEFINE CHL(NEWYORK.LONDON) + CHLTYPE(SDR) + TRPTYPE(TCP) + CONNAME('localhost(1515)') + XMITQ(LONDON) + REPLACE DEFINE QL(LONDON) + USAGE(XMITQ) + TRIGGER + TRIGDATA(NEWYORK.LONDON) + INITQ(SYSTEM.CHANNEL.INITQ) + REPLACE DEFINE QL(INVENTQ) + REPLACE END

   
   
4. Use amqsprm1.exe, which you can download below, to put a Reference Message to the remote queue named INVENTQ and defined on LONDON.
5. Check that the reference message has arrived in the INVENTQ on NEWYORK and that the file has been successfully transferred to the C:\outfiles folder.

Setting up the Reference Message solution in a clustered environment

Setting up the solution involves four steps: create the cluster, edit and build the sample exit code, deploy it, and test it. Adding a queue manager to the cluster does not require additional tasks related to the Reference Message solution.

To help you go through the following steps, the following files are included in refmsg-files.zip, which you can download below:

• Exit library that you will deploy on the cluster channels to set up the solution: amqsxrm_cluster.dll.
• Exit source code and definition file if you want to build the exit library: amqsxrma_cluster.c and amqsxrm_cluster.def.
• Sample program to put a reference message in a queue, that you will use to test the solution: amqsprm1.exe.
• Sample program source code: amqsprma1.c.

Set up the INVENTORY cluster

1. Delete all previously created objects on both queue managers.
2. Create the INVENTORY cluster. To do so use the WebSphere MQ Explorer or the follow the procedure Setting up a new cluster in the WebSphere MQ Information center. You will need to adapt the CONNAME attribute of the cluster channels to your environment.
   
   Figure 1. Using the WebSphere MQ Explorer
   
   
   
3. If not already done, create a local queue named INVENTQ on NEWYORK and share it in the INVENTORY cluster. You can either use the WebSphere MQ Explorer or issue the following MQSC command:

   DEFINE QL(INVENTQ) CLUSTER(INVENTORY) END

   
   

   The INVENTORY cluster should look like this:

   
   
   Figure 2. The INVENTORY cluster
   
   
   

Both LONDON and NEWYORK hold the full repositories: a cluster can work adequately with only one full repository, but using two improves availability.

Editing the Reference Message sample exit

The following comments section of the exit code describes the main logic of the sample exit. As you can see, it doesn't have any cases for cluster-sender and cluster-receiver channels, and therefore if it's used on one of these channels, nothing will happen.

                
/*   AMQSXRMA is a sample C program that is intended to be used as  */
/*   a channel message exit.                                        */
/*                                                                  */ 
/*   It recognises reference messages with an object type that      */
/*   matches the object type in the message exit user data field of */
/*   the channel definition.                                        */
/*                                                                  */
/*   For these messages it does the following (other messages are   */
/*   ignored) -                                                     */
/*                                                                  */
/*     Sender and Server channels  -                                */
/*       The specified length of data is copied from the specified  */
/*       offset of the specified file into the space remaining in   */
/*       the agent buffer after the reference message.              */
/*       If the end of the file is not reached the reference        */
/*       message is put back on the transmission queue after        */
/*       updating the DataLogicalOffset field.                      */
/*                                                                  */
/*     Requestor and Receiver channels  -                           */
/*       If the DataLogicalOffset field is zero and the specified   */
/*       file does not exist, it is created.                        */
/*       The data following the reference message is added to the   */
/*       end of the specified file.                                 */
/*       If the reference message is not the last one for the       */
/*       specified file, the reference message is discarded.        */
/*       Otherwise, the reference message, without the appended     */
/*       data, is returned to the channel program and will be put   */
/*       to the target queue.                                       */

The first task is to add MQCHT_CLUSSDR to the sender case, so that the exit reads and sends the file if the channel is a cluster-sender. See line 695 in the amqsxrma_cluster.c file:

                
/*******************************************************************/
/* Move the data to or from the file.                              */
/*******************************************************************/
switch (pChannelDef -> ChannelType)
{
  /*****************************************************************/
  /* For server and sender channels append data from the file to   */
  /* the reference message and return it to the caller.            */
  /* If the end of the file is not reached then put the reference  */
  /* back on the transmission queue.                               */
  /*****************************************************************/
    
  /*****************************************************************/
  /* developerWorks edit - add cluster sender channel support      */
  /*****************************************************************/
  case MQCHT_CLUSSDR:
  /*****************************************************************/
  /* end of developerWorks edit                                    */
  /*****************************************************************/
  case MQCHT_SENDER:
  case MQCHT_SERVER:

Also add MQCHT_CLUSRCVR to the receiver case, so that the exit creates and adds data to the file if the channel is cluster-receiver. See line 994 in the provided source code:

                

/* For requestor and receiver channels, copy data from the       */
/* reference message into the file.                              */
/* If this is the first part of the file then (re)create the     */
/* file first.                                                   */
/* If this is the last part of the file then return the          */
/* reference message to the caller, otherwise discard it.        */
/*****************************************************************/
   
/*****************************************************************/
/* developerWorks edit - add cluster receiver channel support    */
/*****************************************************************/
case MQCHT_CLUSRCVR:
/*****************************************************************/
/* end of developerWorks edit                                    */
/*****************************************************************/
case MQCHT_REQUESTER:
case MQCHT_RECEIVER:

You might think it would be enough to get it working on a cluster channel. As shown in the comments section of the sending process, if end of file is not reached, then the message is put back in the transmission queue with its reading offset field updated. This will trigger the sender channel again in order to loop until end of file is reached. However, with a cluster-sender channel, a cluster-sender channel is triggered as soon as there is a message whose CorrelId field is set to the channel name available on the SYSTEM.CLUSTER.TRANSMIT.QUEUE. Cluster-sender channels all use this system queue as a transmission queue.

You need to do a last change to the sample exit code: if the channel is a cluster-sender, set the channel name in the CorrelId field of the message descriptor before putting it back on this queue. Otherwise set it to NONE. See lines 914 to 920 in the provided source code:

                
//***********************************************************/
/* developerWorks edit -                                   */
/*   if the channel is a cluster sender, we need to set    */
/*   the channel name in the CorrelId field of the message */
/*   descriptor to trigger it.                             */
/*   Note that we need to pad the field with the blank     */
/*   character, otherwise the message will be stuck in the */
/*   SYSTEM.CLUSTER.TRANSMIT.QUEUE.                        */
/***********************************************************/
if (pChannelDef -> ChannelType == MQCHT_CLUSSDR) {
  memset(md.CorrelId, 32, sizeof(md.CorrelId));
  memcpy(md.CorrelId, pChannelDef -> ChannelName, sizeof(pChannelDef -> ChannelName));
}
else {
  memcpy(md.CorrelId, MQCI_NONE, sizeof(md.CorrelId));
}
/***********************************************************/
/* end of developerWorks edit                              */
/***********************************************************/

You are now ready to test. To get through the next step, use the supplied amqsxrm_cluster.dll exit library, or build it from the amqsxrma_cluster.c source file and the amqsxrm_cluster.def definition file using the Microsoft® Visual C++ compiler: cl amqsxrma_cluster.c -o "C:\IBM\WebSphere MQ\exits\amqsxrm_cluster.dll" -LD -DEFAULTLIB mqm.lib mqmvx.lib amqsxrm_cluster.def.

Channel configuration and exit deployment

Now your INVENTORY cluster is set,. You should have a TO.NEWYORK cluster-sender channel on LONDON, and a TO.NEWYORK cluster-receiver channel on NEWYORK.

You have manually defined the TO.NEWYORK channel on LONDON: be aware that even manually-defined cluster-sender channels have their attributes automatically modified to ensure that they match those on the corresponding cluster-receiver definition. Therefore you only need to add the exit to the cluster-receiver definition of the TO.NEWYORK channel. The cluster-sender definition of the TO.NEWYORK channel will be automatically updated. If you test using separate machines, you will need to have the exit library deployed on both systems. You can now deploy the exit library and configure the channel:

1. Copy the amqsxrm_cluster.dll file in C:\IBM\WebSphere MQ\exits. If your queue managers are hosted by separated machines, copy it on each one.
2. Alter the cluster-receiver definition of TO.NEWORK on NEWYORK using the WebSphere MQ Explorer, or issuing the following mqsc command:

   ALTER CHANNEL(TO.NEWYORK) + CHLTYPE(CLUSRCVR) + MSGEXIT('amqsxrm_cluster.dll(MsgExit)') + MSGDATA(FLATFILE) END

   
   
3. Restart the channel from the sending end on LONDON by using the WebSphere MQ Explorer or by issuing the following mqsc commands:

   START CHANNEL(TO.NEWYORK) END

   
   

Testing the solution

Use the supplied amqsprm1.exe program to put a Reference Message to the INVENTQ from LONDON: amqsprm1.exe -m LONDON -g NEWYORK -q INVENTQ -i C:\infiles\stock.dat -o C:\outfiles\stock.dat -t FLATFILE

Make sure to add the -g option to specify the destination queue manager.

Check that the reference message has arrived in the INVENTQ on NEWYORK and that the file has been successfully transferred to the C:\outfiles folder.

Adding a queue manager to the cluster

You will now see how easy is to add a queue manager in the cluster and how it doesn't need any additional configuration tasks specific to the Reference Message Solution.

A new branch of the chain store is being set up in Paris and the IT department wants to add the PARIS queue manager to the cluster. PARIS will hold a partial repository, and will be linked to LONDON to refer of one of the full repositories. Use the WebSphere MQ Explorer wizard or follow the procedure Adding a new queue manager to a cluster in the WebSphere MQ Information center. Make sure that PARIS holds a partial repository.

You only need to create two channels to add PARIS to the INVENTORY cluster. To connect PARIS to the inventory application in a distributed queuing environment, you would need to create one remote queue definition, four channels, and two transmit queues. The INVENTORY cluster should now look like this:

Now PARIS learns, from the full repository at LONDON, that the INVENTQ queue is hosted by NEWYORK. When an application hosted by the system in Paris tries to put messages to the INVENTQ queue, then PARIS automatically defines a cluster-sender channel to connect to the TO.NEWYORK cluster-receiver channel. Auto-defined cluster-sender channels take their attributes from those specified in the corresponding cluster-receiver channel on the receiving queue manager, including the Reference Message exit configuration.

Thus there are no configuration tasks related to the Reference Message solution.

Use amqsprm1.exe, which you can download below, to put a Reference Message to the INVENTQ from PARIS: amqsprm1.exe -m PARIS -g NEWYORK -q INVENTQ -i C:\infiles\stock.dat -o C:\outfiles\stock.dat -t FLATFILE.

The -m option now specifies PARIS, which means that we put the message to the INVENTQ from PARIS. Check that the reference message has arrived in the INVENTQ on NEWYORK and that the file has been successfully transferred to the C:\outfiles folder.

Restrictions and limitations

• The MCA and the message exit run under a WebSphere MQ user ID. The message exit (and therefore the user ID) need to access the object to either retrieve it at the sending end or create it at the receiving end. This may be feasible only when the object is universally accessible, which raises a security issue.
• The message exit writes data in the correlation ID of the message, overwriting any previous value that an application may have set.
• Only distributed platforms can be used in this configuration, and this facility is not possible on z/OS. Currently only Windows has been tested.

Conclusion

The WebSphere MQ Reference Message sample is a great solution to move large data objectsbetween queue managers in a distributed queuing environment. This article showed you how to extend this solution with minimal coding so it can be used in the flexible and scalable clustered WebSphere MQ environment, and thus making possible movement of large data objects between clustered queue managers. The article provides a channel exit that can be deployed on a cluster channel, its source code, and a test program to put Reference Messages in a queue.

Back to top

Download

	Information about download methods

Resources

• WebSphere MQ developer resources page
  Technical resources to help you design, develop, and deploy messaging middleware with WebSphere MQ to integrate applications, Web services, and transactions on almost any platform.
  
  
• WebSphere MQ product page
  Product descriptions, product news, training information, support information, and more.
  
  
• WebSphere MQ V6 trial download
  A no-charge trial download of WebSphere MQ V6. Includes limited online support for Windows® and Linux® installations at no charge during the trial period.
  
  
• WebSphere MQ V6 information center
  A single Eclipse-based Web portal to all WebSphere MQ V6 documentation, with conceptual, task, and reference information on installing, configuring, and using your WebSphere MQ environment.
  
  
• WebSphere MQ documentation library
  WebSphere MQ product manuals.
  
  
• WebSphere MQ SupportPacs
  Downloadable code, documentation, and performance reports for the WebSphere MQ family of products.
  
  
• WebSphere MQ public newsgroup
  A non-IBM forum where you can get answers to your WebSphere MQ technical questions and share your WebSphere MQ knowledge with other users.
  
  
• developerWorks WebSphere Business Integration zone
  For developers, access to WebSphere Business Integration how-to articles, downloads, tutorials, education, product info, and more.
  
  
• WebSphere Business Integration products page
  For both business and technical users, a handy overview of all WebSphere Business Integration products
  
  
• WebSphere forums
  Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
  
  
• Most popular WebSphere trial downloads
  No-charge trial downloads for key WebSphere products.
  
  
• Trial downloads for IBM software products
  No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
  
  
• Technical books from IBM Press
  Convenient online ordering through Barnes & Noble.
  
  
• developerWorks technical events and Webcasts
  Free technical sessions by IBM experts that can accelerate your learning curve and help you succeed in your most difficult software projects. Sessions range from one-hour Webcasts to half-day and full-day live sessions in cities worldwide.
  

About the author

		Ramzi Choueri is an IT Architect with IBM Application Innovation Services in France. He works on the Enterprise Integration team, helping clients integrate new services into their existing IT infrastructures in order to increase competitiveness. He holds an M.S. degree in Telecommunications and Wireless Technology from Paris Superior Institute of Electronics (ISEP). You can contact Ramzi at r.choueri@fr.ibm.com.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Back to top