MQSeries Queue Manager Clusters

MQSeries Queue Manager Clusters SC34-5349-03

Note! Before using this information and the product it supports, be sure to read the general information under Appendix. Notices on page 125. Fourth edition (November 2000) This edition applies to the following products: v MQSeries for AIX V5.1 v MQSeries for AS/400, V5.1 v MQSeries for Compaq Tru64 UNIX, V5.1 v MQSeries for HP-UX, V5.1 v MQSeries for OS/2 V5.1 v MQSeries for OS/390 V5.2 v MQSeries for Sun Solaris, V5.1 v MQSeries for Sun Solaris, Intel Platform Edition, V5.1 v MQSeries for Windows NT V5.1 and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation 1999, 2000. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents Figures.............. vii Tables............... ix About this book........... xi Who should read this book......... xi What you need to know to understand this book.. xi How to use this book........... xi Conventions and terminology used in this book xii Summary of changes........ xiii Changes for this edition (SC34-5349-03)..... xiii Changes for the third edition (SC34-5349-02)... xiii Changes for the second edition (SC34-5349-01).. xiii Part 1. Getting started with queue manager clusters.......... 1 Chapter 1. Concepts and terminology.. 3 Concepts............... 3 Comparison with distributed queuing..... 3 Overview of cluster components....... 4 Terminology.............. 5 Benefits................ 8 Things to consider............ 8 Summary of the concepts.......... 9 Chapter 2. Using clusters to ease system administration........ 11 How can I use clusters?.......... 11 Can I use clusters and queue-sharing groups?.. 11 How does the system administrator benefit?... 12 Definitions to set up a network using distributed queuing.............. 12 Definitions to set up a network using clusters.. 12 What about my applications?........ 13 How should I prepare to use clusters?..... 14 How do I set up a cluster?......... 14 Establishing communication in a cluster.... 15 Chapter 3. First tasks........ 19 Task 1: Setting up a new cluster....... 19 The steps required to complete task 1.... 19 The cluster achieved by task 1....... 22 Converting an existing network into a cluster.. 24 Task 2: Adding a new queue manager to a cluster 25 The steps required to complete task 2.... 25 The cluster achieved by task 2....... 26 Part 2. Using queue manager clusters.............. 27 Chapter 4. How queue manager clusters work............ 29 Components of a cluster.......... 29 Queue managers and repositories...... 29 Queues............... 30 Cluster transmission queue........ 30 Cluster channels............ 30 Auto-definition of remote queues...... 31 Auto-definition of channels........ 31 What makes clustering work?........ 32 Using aliases and remote-queue definitions with clusters................ 33 Queue-manager aliases......... 33 Reply-to queue aliases.......... 34 Queue aliases............. 35 Examples of using aliases within clusters... 35 Chapter 5. Using clusters for workload management............ 41 More than one instance of a queue...... 41 Workload balancing........... 43 Cluster workload user exit........ 43 Writing and compiling cluster workload exit programs.............. 43 Sample cluster workload exit....... 45 Programming considerations........ 46 Reviewing applications for message affinities.. 46 MQI and clusters............ 49 MQOPEN.............. 49 MQPUT and MQPUT1......... 50 MQINQ.............. 50 MQSET............... 51 Return codes.............. 51 Chapter 6. Using MQSeries commands with clusters............ 53 MQSeries command attributes........ 54 Queue-manager definition commands.... 54 Channel definition commands....... 54 Queue definition commands........ 55 MQSeries commands for work with clusters... 56 DISPLAY CLUSQMGR......... 57 SUSPEND QMGR and RESUME QMGR.... 57 REFRESH CLUSTER.......... 58 RESET CLUSTER........... 58 Chapter 7. Managing MQSeries clusters 59 Cluster-design considerations........ 59 Selecting queue managers to hold repositories.. 59 Organizing a cluster.......... 60 Choosing names............ 61 Overlapping clusters.......... 61 Objects............... 62 Cluster-administration considerations...... 63 Copyright IBM Corp. 1999, 2000 iii

Maintaining a queue manager....... 63 Refreshing a queue manager........ 64 Maintaining the cluster transmission queue... 64 What happens when a queue manager fails?.. 64 What happens when a repository fails?.... 65 What happens if I put-disable a cluster queue? 65 How long do the repositories retain information? 65 Cluster channels............ 66 Chapter 8. Keeping clusters secure.. 67 Stopping unauthorized queue managers sending messages to your queue manager....... 67 Stopping unauthorized queue managers putting messages on your queues.......... 67 Stopping your queue manager putting messages to remote queues............. 68 Preventing queue managers joining a cluster... 68 Using security exits on cluster channels.... 69 Forcing unwanted queue managers to leave a cluster................ 70 Chapter 9. Advanced tasks...... 71 Task 3: Adding a new queue manager that hosts a queue................ 71 The steps required to complete task 3.... 72 The cluster achieved by task 3....... 73 Extensions to this task.......... 74 Task 4: Removing a cluster queue from a queue manager............... 75 The steps required to complete task 4.... 75 The cluster achieved by task 4....... 76 Extensions to this task.......... 76 Task 5: Removing a queue manager from a cluster 77 The steps required to complete task 5.... 77 The cluster achieved by task 5....... 78 Task 6: Moving a repository to another queue manager............... 79 The steps required to complete task 6.... 79 The cluster achieved by task 6....... 80 Task 7: Converting an existing network into a cluster................ 81 The steps required to complete task 7.... 82 The cluster achieved by task 7....... 84 Task 8: Adding a new, interconnected cluster... 85 The steps required to complete task 8.... 85 The cluster achieved by task 8....... 87 Extensions to this task.......... 89 Task 9: Removing a cluster network...... 90 The steps required to complete task 9.... 90 Task 10: Adding new queue managers that host a shared queue.............. 92 The steps required to complete task 10.... 92 The cluster achieved by task 10....... 93 Part 3. Reference information... 95 Chapter 10. Cluster workload exit call and data structures......... 97 MQ_CLUSTER_WORKLOAD_EXIT - Cluster workload exit.............. 98 iv MQSeries Queue Manager Clusters Syntax............... 98 Parameters............. 98 Usage notes............. 98 C invocation............. 98 System/390 assembler invocation...... 98 MQWXP - Cluster workload exit parameter structure............... 99 Fields............... 99 C declaration............ 104 System/390 assembler declaration..... 105 MQWDR - Cluster workload destination-record structure............... 106 Fields............... 106 C declaration............ 109 System/390 assembler declaration..... 109 MQWQR - Cluster workload queue-record structure............... 110 Fields............... 110 C declaration............ 113 System/390 assembler declaration..... 113 MQWCR - Cluster workload cluster-record structure............... 114 Fields............... 114 C declaration............ 115 System/390 assembler declaration..... 115 Chapter 11. Constants for the cluster workload exit........... 117 List of constants............ 117 MQ_* (Lengths of character string and byte fields)............... 117 MQBND_* (Binding).......... 117 MQCHS_* (Channel status)........ 118 MQCQT_* (Cluster queue type)...... 118 MQPER_* (Persistence)......... 118 MQQA_* (Inhibit put)......... 118 MQQF_* (Queue flags)......... 118 MQQMF_* (Queue-manager flags)..... 119 MQWDR_* (Cluster workload exit destination-record length)........ 119 MQWDR_* (Cluster workload exit destination-record structure identifier).... 119 MQWDR_* (Cluster workload exit destination-record version)........ 119 MQWQR_* (Cluster workload exit queue-record length).............. 119 MQWQR_* (Cluster workload exit queue-record structure identifier).......... 120 MQWQR_* (Cluster workload exit queue-record version).............. 120 MQWXP_* (Cluster workload exit structure identifier).............. 120 MQWXP_* (Cluster workload exit structure version).............. 120 MQXCC_* (Exit response)........ 120 MQXR_* (Exit reason)......... 121 MQXT_* (Exit identifier)......... 121 MQXUA_* (Exit user area)........ 121 Part 4. Appendixes........ 123

Appendix. Notices......... 125 Programming interface information...... 126 Trademarks.............. 127 Glossary of terms and abbreviations 129 Bibliography............ 135 MQSeries cross-platform publications..... 135 MQSeries platform-specific publications.... 135 Softcopy books............. 136 HTML format............ 136 Portable Document Format (PDF)..... 136 BookManager format......... 137 PostScript format........... 137 Windows Help format......... 137 MQSeries information available on the Internet.. 137 Index............... 139 Sending your comments to IBM... 143 Contents v

vi MQSeries Queue Manager Clusters

Figures 1. Distributed queuing.......... 4 2. A cluster of queue managers....... 5 3. A network of four queue managers.... 12 4. A small cluster of two queue managers 15 5. The INVENTORY cluster with two queue managers............. 22 6. The INVENTORY cluster with three queue managers............. 26 7. A cluster of queue managers, showing auto-defined channels......... 33 8. Putting from a queue manager outside the cluster.............. 36 9. Putting to a queue manager outside the cluster 38 10. Bridging across clusters........ 39 11. A cluster with multiple instances of the same queue.............. 42 12. A typical 2-repository topology...... 59 13. A hub and spoke arrangement of repositories 60 14. A complex repository topology...... 60 15. Classes of service.......... 62 16. The INVENTORY cluster with four queue managers............. 73 17. The INVENTORY cluster, with TORONTO outside the cluster.......... 78 18. The INVENTORY cluster with the repository moved to PARIS........... 80 19. A hub and spoke network....... 81 20. A cluster with a hub and spokes..... 84 21. Interconnected clusters......... 88 22. Cluster and queue-sharing group..... 93 Copyright IBM Corp. 1999, 2000 vii

viii MQSeries Queue Manager Clusters

Tables 1. Definitions for distributed queuing..... 12 2. Definitions for clustering........ 13 3. Queue-manager attributes........ 97 4. Queue attributes........... 97 5. Fields in MQWXP.......... 99 6. Fields in MQWDR.......... 106 7. Fields in MQWQR.......... 110 8. Fields in MQWCR.......... 114 Copyright IBM Corp. 1999, 2000 ix

x MQSeries Queue Manager Clusters

About this book Who should read this book This book describes how to create and use clusters of MQSeries queue managers. It explains the concepts and terminology of clustering and shows how you can benefit by taking advantage of clustering. It details changes to the message queue interface (MQI), and summarizes the syntax of new and changed MQSeries commands. It shows a number of examples of tasks you can perform to set up and maintain clusters of queue managers. This book is for anyone who needs an understanding of MQSeries clusters. The following readers are specifically addressed: v Network planners responsible for designing the overall queue manager network v v v Application programmers responsible for designing applications that access queues and queue managers within clusters Systems administrators responsible for monitoring the local system and implementing some of the planning details System programmers with responsibility for designing and programming the user exits What you need to know to understand this book How to use this book This book describes MQSeries clustering in detail, and includes step-by-step examples that you should be able to follow with only limited background knowledge about MQSeries in general. An understanding of the concepts of message queuing, for example the purpose of queues, queue managers, and channels, would be an advantage. To understand fully how to make the best use of clusters, it is useful to be familiar with the MQSeries products for the specific platforms you will be using, and the communications protocols that are used on those platforms. It is also helpful to have an understanding of how distributed queue management works. These topics are discussed in the MQSeries Intercommunication book. This book contains three parts. The chapters in Part 1. Getting started with queue manager clusters on page 1 are aimed at users who are new to clusters. Read these chapters first to learn what queue manager clusters are and how to use them. Throughout this part of the book, the use of clusters is compared with more traditional distributed-queuing techniques. If you are not familiar with distributed queuing, you should skip the sections that are not of interest to you. You should still be able to follow the guidance and examples given. The chapters in this part are: v v Chapter 1. Concepts and terminology on page 3, which introduces the concepts of queue manager clusters, explains the associated terminology, and highlights the differences between using clusters and using distributed queuing techniques. Chapter 2. Using clusters to ease system administration on page 11, which shows the benefits of using clusters and shows when and where you might choose to implement them in your existing network. Copyright IBM Corp. 1999, 2000 xi

About this book v Chapter 3. First tasks on page 19, which describes some of the first tasks you may need to perform in order to set up and use a cluster. You should be able to accomplish these first tasks without an in-depth understanding of clusters or distributed queuing. The chapters in Part 2. Using queue manager clusters on page 27 are aimed at more experienced users who want to understand about clusters in detail. Read these chapters to learn how to use clusters to the best advantage. The chapters in this part are: v v v v v v Chapter 4. How queue manager clusters work on page 29, which provides more detail about the components of clusters and explains how clustering works. Chapter 5. Using clusters for workload management on page 41, which describes how to use clusters to achieve workload balancing. Chapter 6. Using MQSeries commands with clusters on page 53, which introduces commands that are specific to work with MQSeries clusters. Chapter 7. Managing MQSeries clusters on page 59, which provides administrative information about how to design and maintain a cluster. Chapter 8. Keeping clusters secure on page 67, which discusses security aspects associated with using clusters. Chapter 9. Advanced tasks on page 71, which guides you through a series of more advanced tasks. The chapters in Part 3. Reference information on page 95 contain reference information about the cluster workload exit. The chapters in this part are: v Chapter 10. Cluster workload exit call and data structures on page 97. v Chapter 11. Constants for the cluster workload exit on page 117. Conventions and terminology used in this book Throughout this book, the term MQSeries for Sun Solaris applies to: v Sun Solaris, SPARC Platform Edition v Sun Solaris, Intel Platform Edition There is a glossary and a bibliography at the back of the book. xii MQSeries Queue Manager Clusters

Summary of changes This section describes changes in this edition of MQSeries Queue Manager Clusters. Changes since the previous edition of the book are marked by vertical lines to the left of the changes. Changes for this edition (SC34-5349-03) The major changes for this edition are the: v Addition of support for queue-sharing groups in MQSeries for OS/390, V5.2 v Addition of support for clusters on MQSeries for Compaq Tru64 UNIX v Addition of support for clusters on MQSeries for Sun Solaris, Intel Platform Edition Changes for the third edition (SC34-5349-02) The third edition was not published. Changes for the second edition (SC34-5349-01) The major change for this edition is the v Addition of support for clusters on MQSeries for AS/400 Copyright IBM Corp. 1999, 2000 xiii

Changes xiv MQSeries Queue Manager Clusters

Part 1. Getting started with queue manager clusters Chapter 1. Concepts and terminology..... 3 Concepts............... 3 Comparison with distributed queuing..... 3 Overview of cluster components....... 4 Terminology.............. 5 Benefits................ 8 Things to consider............ 8 Summary of the concepts.......... 9 Chapter 2. Using clusters to ease system administration............. 11 How can I use clusters?.......... 11 Can I use clusters and queue-sharing groups?.. 11 How does the system administrator benefit?... 12 Definitions to set up a network using distributed queuing.............. 12 Definitions to set up a network using clusters.. 12 What about my applications?........ 13 How should I prepare to use clusters?..... 14 How do I set up a cluster?......... 14 Establishing communication in a cluster.... 15 Channel initiator.......... 15 Channel listener........... 15 Chapter 3. First tasks.......... 19 Task 1: Setting up a new cluster....... 19 The steps required to complete task 1.... 19 1. Prepare the queue managers...... 19 2. Decide on the organization of the cluster and its name............ 20 3. Determine which queue managers should hold full repositories......... 20 4. Alter the queue-manager definitions to add repository definitions......... 20 5. Define the CLUSRCVR channels.... 20 6. Define the CLUSSDR channels..... 21 7. Define the cluster queue INVENTQ... 22 The cluster achieved by task 1....... 22 Verifying task 1........... 23 Using the cluster set up in task 1..... 23 Converting an existing network into a cluster.. 24 Task 2: Adding a new queue manager to a cluster 25 The steps required to complete task 2.... 25 1. Prepare the PARIS queue manager.... 25 2. Determine which full repository PARIS should refer to first.......... 25 3. Define a CLUSRCVR channel on queue manager PARIS........... 25 4. Define a CLUSSDR channel on queue manager PARIS........... 25 The cluster achieved by task 2....... 26 Copyright IBM Corp. 1999, 2000 1

Getting started 2 MQSeries Queue Manager Clusters

Chapter 1. Concepts and terminology This chapter introduces the concepts of queue manager clusters and explains some of the terminology. For the benefit of customers familiar with traditional distributed-queuing techniques, it compares the use of clusters with the use of distributed queuing. If you are not familiar with distributed queuing, you should skip the sections that are not of interest to you. Concepts Businesses are increasingly becoming aware of the advantages of establishing an intranet or of connecting processors to a LAN. You might also have connected some OS/390 processors to form a sysplex, or some AIX processors in the form of an SP2. Processors linked in these ways benefit from support from each other and have access to a far wider range of programs and data. In the same way, MQSeries queue managers can be connected to form a cluster. This facility is available to queue managers on the following platforms: v MQSeries for AIX, V5.1 v MQSeries for AS/400, V5.1 v MQSeries for Compaq Tru64 UNIX, V5.1 v MQSeries for HP-UX, V5.1 v MQSeries for OS/2 Warp, V5.1 v MQSeries for OS/390 v MQSeries for Sun Solaris, V5.1 v MQSeries for Sun Solaris, Intel Platform Edition, V5.1 v MQSeries for Windows NT, V5.1 The queue managers can be connected using any of the communications protocols that are available on your platform. That is, TCP or LU 6.2 on any platform, and in addition, NetBIOS or SPX on OS/2 or Windows NT, and UDP on AIX. Connections on more than one protocol may exist within a cluster. Of course, if you try to make a connection to a queue manager using a protocol that it does not support, the channel will not become active. Comparison with distributed queuing If you do not use clusters, your queue managers are independent and communicate using distributed queuing. If one queue manager needs to send messages to another it must have defined: v A transmission queue v A channel to the remote queue manager v A remote-queue definition for every queue to which it wants to send messages Figure 1 on page 4 shows the components required for distributed queuing. Copyright IBM Corp. 1999, 2000 3

Concepts QM1 QM2 Remote queue definitions MCA Message Flow MCA Dead Letter Queue Transmission Queue Channel Application Queues If you group queue managers in a cluster, the queue managers can make the queues that they host available to every other queue manager in the cluster. Any queue manager can send a message to any other queue manager in the same cluster without the need for explicit channel definitions, remote-queue definitions, or transmission queues for each destination. Every queue manager in a cluster has a single transmission queue from which it can transmit messages to any other queue manager in the cluster. Each queue manager in a cluster needs to define only: v One cluster-receiver channel on which to receive messages v One cluster-sender channel with which it introduces itself and learns about the cluster Overview of cluster components Figure 2 on page 5 shows the components of a cluster called CLUSTER. 4 MQSeries Queue Manager Clusters Figure 1. Distributed queuing v v v v v In this cluster there are three queue managers, QM1, QM2, and QM3. QM1 and QM2 host repositories of information about the queue managers in the cluster. They are referred to as repository queue managers. (The repositories are represented in the diagram by the shaded cylinders.) QM2 and QM3 host some queues that are accessible to any other queue manager in the cluster. These are called cluster queues. (The cluster queues are represented in the diagram by the shaded queues.) As with distributed queuing, an application uses the MQPUT call to put a message on a cluster queue at any queue manager. An application uses the MQGET call to retrieve messages from a cluster queue on the local queue manager. Each queue manager has a definition for the receiving end of a channel called TO.qmgr on which it can receive messages. This is a cluster-receiver channel. A cluster-receiver channel is similar to a receiver channel used in distributed queuing, but in addition to carrying messages this channel can also carry information about the cluster. Each queue manager also has a definition for the sending end of a channel, which connects to the cluster-receiver channel of one of the repository queue managers. This is a cluster-sender channel. In Figure 2 on page 5, QM1 and QM3 have cluster-sender channels connecting to TO.QM2. QM2 has a cluster-sender channel connecting to TO.QM1. A cluster-sender channel is similar to a sender channel used in distributed queuing, but in addition to carrying messages this channel can also carry information about the cluster. Once both the cluster-receiver end and the cluster-sender end of a channel have been defined, the channel is started automatically.

Concepts CLUSTER QM1 TO.QM1 QM2 TO.QM2 QM3 TO.QM3 Terminology Figure 2. A cluster of queue managers Before proceeding to the next chapter it is useful to understand the following terminology: Cluster A cluster is a network of queue managers that are logically associated in some way. The queue managers in a cluster may be physically remote. For example, they might represent the branches of an international chain store and be physically located in different countries. Each cluster within an enterprise should have a unique name. Cluster queue manager A cluster queue manager is a queue manager that is a member of a cluster. A queue manager may be a member of more than one cluster. (See Overlapping clusters on page 61.) Each cluster queue manager must have a name that is unique throughout all the clusters of which it is a member. A cluster queue manager may host queues, which it advertises to the other queue managers in the cluster. A cluster queue manager does not have to host or advertise any queues. It may just feed messages into the cluster and receive only responses that are directed explicitly to it, and not to advertised queues. In MQSeries for OS/390, V5.2, a cluster queue manager may be a member of a queue-sharing group. In this case, it shares its queue definitions with other queue managers in the same queue-sharing group. For more information about queue-sharing groups see the MQSeries for OS/390 Concepts and Planning Guide. Chapter 1. Concepts and terminology 5

Terminology Cluster queue managers are autonomous. They have full control over queues and channels that they define. Their definitions cannot be modified by other queue managers (other than queue managers in the same queue-sharing group). When you make or alter a definition on a cluster queue manager, the information is sent to the repository queue manager and the repositories in the cluster are updated accordingly. Cluster queue A cluster queue is a queue that is hosted by a cluster queue manager and made available to other queue managers in the cluster. The cluster queue manager makes a local queue definition for the queue specifying the name of the cluster that the queue is to be available in. This definition has the effect of advertising the queue to the other queue managers in the cluster. The other queue managers in the cluster can put messages to a cluster queue without needing a corresponding remote-queue definition. A cluster queue can be advertised in more than one cluster. A cluster queue may be a queue that is shared by members of a queue-sharing group in MQSeries for OS/390, V5.2. Repository A repository is a collection of information about the queue managers that are members of a cluster. This information includes queue-manager names, their locations, their channels, what queues they host, and so on. The information is stored in the form of messages on a queue called SYSTEM.CLUSTER.REPOSITORY.QUEUE. (This queue is one of the default objects created on V5.1 of MQSeries for AIX, AS/400, Compaq Tru64 UNIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT and is defined as part of queue-manager customization on MQSeries for OS/390.) Typically, two queue managers in a cluster hold a full repository. The remaining queue managers all hold a partial repository. Repository queue manager A repository queue manager is a cluster queue manager that holds a full repository. To ensure availability, you are recommended to set up two or more repository queue managers in each cluster. The repository queue managers receive information sent by the other queue managers in the cluster and update their repositories accordingly. The repository queue managers send messages to each other to be sure that they are both kept up to date with new information about the cluster. Full repository and partial repository A repository queue manager hosts a complete set of information about every queue manager in the cluster. This set of information is called the repository or sometimes the full repository. The other queue managers in the cluster inquire about the information in the full repositories and build up their own subsets of this information in partial repositories. A queue manager s partial repository contains information about only those queue managers with which the queue manager needs to exchange messages. The queue managers request updates to the information they need, so that if it changes, the repository queue manager will send them the new information. For much of the time a queue manager s partial repository has all the information it needs to perform within the cluster. When a queue manager needs some additional information, it makes inquiries of the full repository and updates its partial repository. The queue managers use a queue called 6 MQSeries Queue Manager Clusters

Terminology SYSTEM.CLUSTER.COMMAND.QUEUE to request and receive updates to the repositories. This queue is one of the default objects created on V5.1 of MQSeries for AIX, AS/400, Compaq Tru64 UNIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT and is defined as part of queue-manager customization on MQSeries for OS/390. Cluster-receiver channel A cluster-receiver (CLUSRCVR) channel definition defines the receiving end of a channel on which a cluster queue manager can receive messages from other queue managers in the cluster. A cluster-receiver channel can also carry information about the cluster information destined for the repository. The definition of a cluster-receiver channel has the effect of advertising that a queue manager is available to receive messages. You need at least one cluster-receiver channel for each cluster queue manager. Cluster-sender channel A cluster-sender (CLUSSDR) channel definition defines the sending end of a channel on which a cluster queue manager can send cluster information to one of the full repositories. The cluster-sender channel is used to notify the repository of any changes to the queue manager s status, for example the addition or removal of a queue. It is also used to transmit messages. The repository queue managers themselves have cluster-sender channels that point to each other. They use them to communicate cluster status changes to each other. It is of little importance which repository a queue manager s CLUSSDR channel definition points to. Once the initial contact has been made, further cluster-sender channels are defined automatically as necessary so that the queue manager can send cluster information to every repository, and messages to every queue manager. Cluster transmission queue Each cluster queue manager has a cluster transmission queue called SYSTEM.CLUSTER.TRANSMIT.QUEUE. The cluster transmission queue transmits all messages from the queue manager to any other queue manager that is in the same cluster. This queue is one of the default objects created on V5.1 of MQSeries for AIX, AS/400, Compaq Tru64 UNIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT and is defined as part of queue-manager customization on MQSeries for OS/390. Binding You may create a cluster in which more than one queue manager hosts an instance of the same cluster queue. This is discussed in More than one instance of a queue on page 41. If you do this, you may need to ensure that a sequence of messages are all sent to the same instance of the queue. You can bind a series of messages to a particular queue by using the MQOO_BIND_ON_OPEN option on the MQOPEN call (see MQOPEN on page 49). Chapter 1. Concepts and terminology 7

Benefits Benefits Things to consider There are two quite different reasons for using clusters: 1. Reduced system administration. As soon as you start to establish even a small cluster you will benefit from simplified system administration. Establishing a network of queue managers in a cluster involves fewer definitions than establishing a network that is to use distributed queuing. With fewer definitions to make, you can set up or change your network more quickly and easily, and the risk of making an error in your definitions is reduced. 2. Increased availability and workload balancing. You may be content to use simple clusters and benefit from the easier system administration. It is not necessary or applicable in every case to consider the availability and workload balancing aspects. If you do choose to use more complicated clusters, you will benefit from scalability of the number of instances of a queue you can define, and therefore from greater availability. Because you can define instances of the same queue on more than one queue manager the workload can be distributed throughout the queue managers in a cluster. These two objectives are discussed in detail in Chapter 2. Using clusters to ease system administration on page 11 and Chapter 5. Using clusters for workload management on page 41. Consider the following before starting to use clusters: v On OS/390 you cannot use clustering if you are using CICS for distributed queuing. v To get the most benefit out of clusters, all the queue managers in the network must be on a platform that supports clusters. Until all your systems are migrated to a platform that supports clusters, you may have queue managers outside a cluster that are not able to access your cluster queues without extra manual definitions. v If two clusters with the same name are merged, it is not possible to separate them again. Therefore it is advisable to give all clusters a unique name. v If a message arrives at a queue manager but there is no queue there to receive it, the message is put on the dead-letter queue as usual. (If there is no dead-letter queue, the channel fails and retries, as described in the MQSeries Intercommunication book.) v The integrity of persistent messages is maintained. Messages are not duplicated or lost as a result of using clusters. v Using clusters reduces system administration. Clusters make it easy to connect larger networks with many more queue managers than you would be able to contemplate using distributed queuing. However, as with distributed queuing, there is a risk that you may consume excessive network resources if you attempt to enable communication between every queue manager in a cluster. v If you use the MQSeries Explorer, which presents the queue managers in a tree structure, the view for large clusters may be cumbersome. v The MQSeries Explorer cannot administer a cluster with repository queue managers on MQSeries for OS/390. You must nominate an additional repository on a system that the MQSeries Explorer can administer. 8 MQSeries Queue Manager Clusters

Things to consider v v v v v The purpose of distribution lists, which are supported on V5.1 of MQSeries for AIX, AS/400, Compaq Tru64 UNIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT, is to use a single MQPUT command to send the same message to multiple destinations. You can use distribution lists in conjunction with queue manager clusters. However, in a clustering environment all the messages are expanded at MQPUT time and so the advantage, in terms of network traffic, is not so great as in a non-clustering environment. The advantage of distribution lists, from the administrator s point of view, is that the numerous channels and transmission queues do not need to be defined manually. If you are going to use clusters to achieve workload balancing, you must examine your applications to see whether they require messages to be processed by a particular queue manager or in a particular sequence. Such applications are said to have message affinities. You may need to modify your applications before you can use them in complex clusters. If you use the MQOO_BIND_ON_OPEN option on an MQOPEN call to force messages to be sent to a specific destination, and the destination queue manager is not available, the messages are not delivered. Messages are not routed to another queue manager because of the risk of duplication. Take care when using clustering in an environment where IP addresses change on an unpredictable basis, for example on machines where Dynamic Host Configuration Protocol (DHCP) is being used. If you specify the IP address rather than the hostname in your channel definitions, you must update the IP address each time DHCP issues a new one. Do not use generic names, for example VTAM generic resources or Dynamic Domain Name Server (DDNS) generic names as the connection names for your channels. If you do, your channels may connect to a different queue manager than expected. Summary of the concepts If you are familiar with MQSeries and distributed queuing, you may like to think of a cluster as a network of queue managers maintained by a conscientious systems administrator. Whenever you create a receiver channel or define a queue, the systems administrator automatically creates corresponding sender channels and remote-queue definitions on the other queue managers. You do not need to make transmission queue definitions because MQSeries provides a transmission queue on each queue manager. This single transmission queue can be used to carry messages to any other queue manager. All the queue managers that join a cluster agree to work in this way. They send out information about themselves and about the queues they host, and they receive information about the other members of the cluster. This information is stored in repositories. Most queue managers retain only the information that they need, that is, information about queues and queue managers with which they need to communicate. Some queue managers retain a full repository of all the information about all queue managers in the cluster. A cluster-receiver channel is a communication channel similar to a receiver channel. When you define a cluster-receiver channel, not only is the object created on your queue manager, but also information about the channel and the queue manager that owns it is stored in the repositories. The definition of a cluster-receiver channel is a queue manager s initial introduction to a cluster. Once Chapter 1. Concepts and terminology 9

Summary of concepts it has been defined, other queue managers can automatically make corresponding definitions for the cluster-sender end of the channel as needed. A cluster-sender channel is a communication channel similar to a sender channel. You need a cluster-sender channel only if you want to communicate with another cluster queue manager. When another cluster queue manager wants to communicate with you, your cluster-sender channel is created automatically by reference to the appropriate cluster-receiver channel definition. However, each queue manager must have one manually defined cluster-sender channel, through which it makes its initial contact with the cluster. Queue managers on platforms that support clusters do not have to be part of a cluster. You can continue to use distributed queuing techniques as well as, or instead of, using clusters. 10 MQSeries Queue Manager Clusters

Chapter 2. Using clusters to ease system administration How can I use clusters? This chapter describes how you can use clusters to simplify system administration in your environment. It is intended for users who have not used clusters before and who want to learn how they might benefit from setting up and using a simple cluster. This chapter covers: v How can I use clusters? v How does the system administrator benefit? on page 12 v What about my applications? on page 13 v How should I prepare to use clusters? on page 14 v How do I set up a cluster? on page 14 For information about how to set up a more complex cluster that benefits from workload management, refer to Chapter 5. Using clusters for workload management on page 41. Typically a cluster contains queue managers that are logically related in some way and need to share some data or applications. For example you may have one queue manager for each department in your company, managing data and applications specific to that department. You could group all these queue managers into a cluster so that they all feed into the PAYROLL application. Or you may have one queue manager for each branch of your chain store, managing the stock levels and other information for that branch. If you group these queue managers into a cluster, they are all able to access the same set of SALES and PURCHASES applications, which are held centrally, perhaps on the head-office queue manager. Once a cluster has been set up, the queue managers within it can communicate with each other without the need for any channel definitions or remote-queue definitions. You can convert an existing network of queue managers into a cluster or you can establish a cluster straightaway, when setting up a new network. An MQSeries client can connect to a queue manager that is part of a cluster, just as it can connect to any other queue manager. See the MQSeries Clients book for more information about clients. Can I use clusters and queue-sharing groups? On MQSeries for OS/390, V5.2 you can group queue managers into queue-sharing groups. A queue manager in a queue-sharing group can define a local queue that is to be shared by up to 32 queue managers. For more information about queue-sharing groups see the MQSeries for OS/390 Concepts and Planning Guide. Shared queues can also be cluster queues. Furthermore, the queue managers in a queue-sharing group can also be in one or more clusters. See Task 10: Adding new queue managers that host a shared queue on page 92 for an example task showing how to use clusters in combination with queue-sharing groups. Copyright IBM Corp. 1999, 2000 11

System administration benefits How does the system administrator benefit? Using clusters leads to easier administration of a network. Look at Figure 3, which shows four queue managers each with two queues. Let us consider how many definitions are needed to connect these queue managers using distributed queuing. Then we will see how many definitions are needed to set up the same network as a cluster. QM1 QM2 QM3 QM4 Figure 3. A network of four queue managers Definitions to set up a network using distributed queuing To set up the network shown in Figure 3 using distributed queuing, you might have the following definitions: Table 1. Definitions for distributed queuing Description Number per queue manager Total number A sender-channel definition for a channel on which to 3 12 send messages to every other queue manager A receiver-channel definition for a channel on which to 3 12 receive messages from every other queue manager A transmission-queue definition for a transmission queue 3 12 to every other queue manager A local-queue definition for each local queue 2 8 A remote-queue definition for each remote queue to which 6 24 this queue manager wants to put messages Optionally, on OS/390, a process definition specifying trigger data if channels are to be triggered 3 12 While you might reduce this number of definitions by, for example, using generic receiver-channel definitions, the maximum number of definitions could be as many as 20 on each queue manager, which is a total of 80 for this network. Definitions to set up a network using clusters When using clusters, you need: v Just one CLUSSDR and one CLUSRCVR definition at each queue manager v No separately defined transmission queues v No remote-queue definitions 12 MQSeries Queue Manager Clusters

Therefore, to set up the network shown in Figure 3 on page 12 using clusters you need the following definitions: Table 2. Definitions for clustering Description A cluster-sender channel definition for a channel on which to send messages to a repository queue manager A cluster-receiver channel definition for a channel on which to receive messages from other queue managers in the cluster System administration benefits Number per queue manager Total number 1 4 1 4 A local-queue definition for each local queue 2 8 What about my applications? To set up this cluster of queue managers (with two full repositories), you would need 4 definitions on each queue manager a total of 16 definitions all together. You would also need to alter the queue-manager definitions for two of the queue managers, to make them repository queue managers for the cluster. The CLUSSDR and CLUSRCVR channel definitions need be made only once. When the cluster is in place you can add or remove queue managers (other than the repository queue managers) without any disruption to the other queue managers. Clearly, this amounts to a significant reduction in the number of definitions required to set up a network containing a large number of queue managers. With fewer definitions to make there is less risk of error. v There is no danger of a mismatch of object names, for example the channel name in a sender-receiver pair. v You do not need to worry that the transmission queue name specified in a channel definition matches the correct transmission queue definition or matches the transmission queue name specified in a remote queue definition. v There is no danger of a QREMOTE definition pointing to the wrong queue at the remote queue manager. Furthermore, once a cluster is set up, you can move cluster queues from one queue manager to another within the cluster without having to do any system management work on any other queue manager. There is no danger of forgetting to delete or modify channel, remote-queue, or transmission-queue definitions. You can add new queue managers to a cluster without any disruption to the existing network. You need not make any alterations to your applications if you are going to set up a simple MQSeries cluster. The application names the target queue on the MQOPEN call as usual and need not be concerned about the location of the queue manager. However, if you set up a cluster in which there are multiple definitions for the same queue, as described in Chapter 5. Using clusters for workload management on page 41, you must review your applications and modify them as necessary. Chapter 2. Using clusters to ease system administration 13

Preparation How should I prepare to use clusters? You can create queue-manager clusters on the following platforms: v MQSeries for AIX, V5.1 v MQSeries for AS/400, V5.1 v MQSeries for Compaq Tru64 UNIX, V5.1 v MQSeries for HP-UX, V5.1 v MQSeries for OS/2 Warp, V5.1 v MQSeries for OS/390 v MQSeries for Sun Solaris, V5.1 v MQSeries for Sun Solaris, Intel Platform Edition, V5.1 v MQSeries for Windows NT, V5.1 Installation procedures for your platform are described in: v The MQSeries for AIX Quick Beginnings book v The MQSeries for AS/400 Quick Beginnings book v The MQSeries for Compaq Tru64 UNIX Quick Beginnings book v The MQSeries for OS/2 Warp Quick Beginnings book v The MQSeries for HP-UX Quick Beginnings book v The MQSeries for Sun Solaris Quick Beginnings book v The MQSeries for Sun Solaris, Intel Platform Edition Quick Beginnings book v The MQSeries for Windows NT Quick Beginnings book v The MQSeries for OS/390 Program Directory V5.1 of MQSeries for AIX, AS/400, Compaq Tru64 UNIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT After installing the product, you have to create queue managers. You use the command crtmqm to create a queue manager with all the default objects that you need. Creation of queue managers is described in the MQSeries System Administration book and in the MQSeries for AS/400 System Administration book. MQSeries for OS/390 You need to customize your queue managers as described in the MQSeries for OS/390 System Setup Guide. Ensure that you customize the queue managers to use distributed queuing and clustering. The queue managers may be members of a queue-sharing group. How do I set up a cluster? Having decided that you want to create a cluster of certain queue managers, you need to consider which queue managers in the cluster are to hold the full repositories of cluster information. You can choose any number of queue managers for this purpose but the recommended number is two. See Selecting queue managers to hold repositories on page 59 for more information. The smallest possible cluster would contain only two queue managers. In this case both queue managers would contain full repositories. You need only a small number of definitions to set this up, and yet there is a high degree of autonomy at each queue manager. Figure 4 on page 15 shows a cluster of two queue managers. You could set up a cluster like this using MQSeries commands (MQSC), or any other type of administration command or utility that is available on your platform. See Chapter 6. Using MQSeries commands with clusters on page 53 for more information. 14 MQSeries Queue Manager Clusters

How to set up a cluster DEMO QM1 QM2 Cluster queue TO.QM1 TO.QM2 Q1 Figure 4. A small cluster of two queue managers The steps you should take to set up a cluster like this are described in Task 1: Setting up a new cluster on page 19. Establishing communication in a cluster To establish communication between queue managers in a cluster you need to configure a link using one of the supported communication protocols. The supported protocols are TCP or LU 6.2 on any platform, and in addition NetBIOS or SPX on OS/2 or Windows NT, and UDP on AIX. Configuring communication links is described in detail in the MQSeries Intercommunication book. As part of this configuration, you also need channel initiators and channel listeners just as you do with distributed queuing. Channel initiator All cluster queue managers need a channel initiator to monitor the system-defined initiation queue SYSTEM.CHANNEL.INITQ. This is the initiation queue for all transmission queues including the cluster transmission queue. MQSeries for OS/390 There is one channel initiator for each queue manager and it runs as a separate address space. You start it using the MQSeries command START CHINIT, which you would normally issue as part of your queue manager startup. V5.1 of MQSeries for AIX, AS/400, Compaq Tru64 UNIX, HP-UX, OS/2 Warp, Sun Solaris, and Windows NT When you start a queue manager, a channel initiator is automatically started too. Channel listener You need to run a channel listener program on each queue manager. A channel listener program listens for incoming network requests and starts the appropriate receiver channel when it is needed. Chapter 2. Using clusters to ease system administration 15

How to set up a cluster The implementation of channel listeners is platform specific. MQSeries for OS/390 Use the channel listener program provided by MQSeries. To start an MQSeries channel listener use the MQSeries command START LISTENER, which you would normally issue as part of your channel initiator startup. For example: START LISTENER PORT(1414) TRPTYPE(TCP) In MQSeries for OS/390, V5.2, as well as a listener for each queue manager, members of a queue-sharing group may make use of a shared listener. Do not use shared listeners in conjunction with clusters. If you do, queue managers may receive messages pertaining to queues for which they do not have a CLUSRCVR definition. MQSeries for AS/400 Use the channel listener program provided by MQSeries. To start an MQSeries channel listener use the MQSeries for AS/400 CL command STRMQMLSR. For example: STRMQMLSR MQMNAME(QM1) PORT(1414) Alternatively, you could use the MQSeries command START LISTENER. MQSeries for OS/2 Warp Use either the channel listener program provided by MQSeries, or inetd, or the facilities provided by the operating system (for example, Attach manager for LU 6.2 communications). To start the MQSeries channel listener use the RUNMQLSR command. For example: RUNMQLSR -t tcp -p 1414 -m QM1 Alternatively, you could use the MQSeries command START LISTENER. To use inetd to start channels, two files must be configured: 1. Edit the file TCPIP\ETC\SERVICES. If you do not have the following line in that file, add it as shown: MQSeries 1414/tcp # MQSeries channel listener where 1414 is the port number required for MQSeries. You can change this, but it must match the port number specified at the sending end. 2. Edit the file TCPIP\ETC\INETD.LST. If you do not have the following line in that file, add it as shown: MQSeries tcp C:\MQM\BIN\AMQCRSTA -m queue.manager.name where queue.manager.name is the name of your queue manager. If you have MQSeries for OS/2 Warp installed on a different drive, replace the C: with the correct drive letter. MQSeries for Windows NT Use either the channel listener program provided by MQSeries, or the facilities provided by the operating system. To start the MQSeries channel listener use the RUNMQLSR command. For example: RUNMQLSR -t tcp -p 1414 -m QM1 16 MQSeries Queue Manager Clusters