Websphere MQ Integrator

Front cover
WebSphere MQ Integrator
Deployment and
Migration
Migration possibilities for brokers and
NEON-based message flows
Multi-broker and multi-platform
configuration scenarios
New features, including
enhanced MRM and Java
nodes
Geert Van de Putte

Chris Griego
Brian McCarty
Peter Toogood
Ralf Ziegler
ibm.com/redbooks
International Technical Support Organization

WebSphere MQ Integrator Deployment and
Migration
April 2002
SG24-6509-00
Take Note! Before using this information and the product it supports, be sure to read the
general information in Notices on page ix.
First Edition (April 2002)

This edition applies to Version 2, Release 1 of WebSphere MQ Integrator, for use with Windows
NT Version 4, Windows 2000, AIX and Sun Solaris, Program Numbers 5724-A82-00,
5724-A82-01 and 5724-A82-02.
Comments may be addressed to:
IBM Corporation, International Technical Support Organization
Dept. HZ8 Building 662
P.O. Box 12195
Research Triangle Park, NC 27709-2195
When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the
information in any way it believes appropriate without incurring any obligation to you.
Copyright International Business Machines Corporation 2002. All rights reserved.
Note to U.S Government Users Documentation related to restricted rights Use, duplication or disclosure is subject to
restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
Contents
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
The team that wrote this redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Chapter 1. WebSphere MQ Integrator features overview . . . . . . . . . . . . . . 1
1.1 WebSphere MQ Integrator basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.1 Architecture of WebSphere MQ Integrator . . . . . . . . . . . . . . . . . . . . . 4
1.1.2 The role of the Configuration Manager . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1.3 The functionality of the broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1.4 Publish/subscribe and the User Name Server . . . . . . . . . . . . . . . . . 10
1.1.5 The user interface: the Control Center . . . . . . . . . . . . . . . . . . . . . . . 11
1.2 Anatomy of a message flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.3 Enhanced Message Repository Manager . . . . . . . . . . . . . . . . . . . . . . . . . 18
1.4 XML support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
1.5 Database support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
1.6 New ESQL features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
1.7 Summary of new features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Chapter 2. Migration considerations . . . . . . . . .
2.1 Considerations overview . . . . . . . . . . . . . . . . .
2.2 Uninstalling the older version . . . . . . . . . . . . .
2.3 Message repository changes . . . . . . . . . . . . .
2.4 Moving components . . . . . . . . . . . . . . . . . . . .
2.5 Enhancement and schedule considerations . .
2.6 DB2 database upgrade . . . . . . . . . . . . . . . . . .
2.7 Recommendations . . . . . . . . . . . . . . . . . . . . .
......
......
......
......
......
......
......
......
.......
.......
.......
.......
.......
.......
.......
.......
......
......
......
......
......
......
......
......
..
..
..
..
..
..
..
..
27
28
28
29
30
31
33
34
Chapter 3. Migration of an MQSeries Integrator environment . . . . . . . . . 37

3.1 Evolution of the MQSeries Integrator environment . . . . . . . . . . . . . . . . . . 38
3.2 The original environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.3 Adding a new broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
3.4 Adding a new application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
3.5 Adding a new broker using WebSphere MQ Integrator V2.1 . . . . . . . . . . 77
3.6 Introducing a V2.1 Configuration Manager . . . . . . . . . . . . . . . . . . . . . . . . 92
3.7 Using a V2.0.2 broker with a V2.1.0 Configuration Manager . . . . . . . . . 105
3.8 Product upgrade on AIX1, NT1 and NT2 . . . . . . . . . . . . . . . . . . . . . . . . 108
Copyright IBM Corp. 2002
iii
3.8.1 Upgrade on AIX1. . . . . . . . . . . . . . . . . . .

3.8.2 Upgrade on NT1 . . . . . . . . . . . . . . . . . . .
3.8.3 Upgrade on NT2 . . . . . . . . . . . . . . . . . . .
3.9 Consolidating Configuration Managers . . . . . .
......
......
......
......
.......
.......
.......
.......
......
......
......
......
.
.
.
.
109
116
123
128
Chapter 4. Deploying a broker on Sun Solaris using Oracle 8i . . . . . . . 131

4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
4.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
4.3 Software installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
4.4 Creating and configuring the broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
4.4.1 Connecting the brokers queue managers and the Configuration
Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
4.4.2 Configuring XA support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
4.4.3 Verification of the installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Chapter 5. Deploying a broker on Windows 2000 using SQL Server . . . 143
5.1 Why install on SQL Server? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
5.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
5.3 Installation of SQL Server 7.0 SP2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
5.4 Installing a WebSphere MQ Integrator broker . . . . . . . . . . . . . . . . . . . . . 153
5.4.1 Broker only installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
5.4.2 Using the SQLServer broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
5.4.3 Verification of the installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Chapter 6. New MRM features explored . . . . . . . . . . . . . . . . . . . . . . . . . . 163
6.1 Converting a delimited message to XML. . . . . . . . . . . . . . . . . . . . . . . . . 164
6.1.1 Creating a new message set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
6.1.2 Adding the physical formats to the message set. . . . . . . . . . . . . . . 168
6.1.3 Creating message elements and types . . . . . . . . . . . . . . . . . . . . . . 170
6.1.4 Creating a message using the compound type . . . . . . . . . . . . . . . . 176
6.2 Creating a message flow to convert CSV to XML . . . . . . . . . . . . . . . . . . 179
6.2.1 Configuring the MQInput node . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
6.2.2 Configuring the Compute node . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
6.3 Deploying the message set and flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
6.4 Testing the message flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
6.5 Changing XML names in the output . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
6.6 Converting a tagged message to XML . . . . . . . . . . . . . . . . . . . . . . . . . . 191
6.6.1 Configuring a message set for tagged data . . . . . . . . . . . . . . . . . . 191
6.6.2 Testing the transformation of a tagged message . . . . . . . . . . . . . . 195
6.7 Using the debugger to examine the message tree . . . . . . . . . . . . . . . . . 198
6.7.1 Importing the Web materials message sets and flows . . . . . . . . . . 203
Chapter 7. Exploring the new XML features . . . . . . . . . . . . . . . . . . . . . . . 205
7.1 Importing an XML DTD and using it in a flow . . . . . . . . . . . . . . . . . . . . . 206
iv
WebSphere MQ Integrator Deployment and Migration
7.1.1 Creating a DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

7.1.2 Creating the message set and adding an XML format . . . . . . . . . . 208
7.1.3 Importing the DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
7.1.4 Examining the imported message set definitions . . . . . . . . . . . . . . 212
7.1.5 Correcting some of the XML names . . . . . . . . . . . . . . . . . . . . . . . . 215
7.2 Using the message set in a flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
7.2.1 Configuring the Compute node . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
7.2.2 Testing the message flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
7.2.3 Modifying the message in the Compute node . . . . . . . . . . . . . . . . . 222
7.2.4 Problem solving with this flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
7.2.5 Some possible errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
7.3 Some more advanced features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
7.3.1 Processing multiple persons in a single message . . . . . . . . . . . . . 229
7.3.2 Using generic XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
7.3.3 Using ESQL reference variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
7.3.4 Importing the Web materials message set and flows . . . . . . . . . . . 236
Chapter 8. Migration of solutions based on New Era Of Networks
functionality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.1 New Era Of Networks support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
8.1.1 MQSeries Integrator V1.0 and V1.1 . . . . . . . . . . . . . . . . . . . . . . . . 239
8.1.2 MQSeries Integrator V2.0 and V2.0.1 . . . . . . . . . . . . . . . . . . . . . . . 240
8.1.3 MQSeries Integrator V2.0.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
8.1.4 WebSphere MQ Integrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
8.2 Summary of changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
8.2.1 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
8.2.2 Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
8.2.3 Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
8.3 Migration of the New Era Of Networks environment . . . . . . . . . . . . . . . . 249
8.3.1 Migration steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
8.3.2 Example migration from MQSeries Integrator to WebSphere MQ
Integrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
8.4 Working on New Era Of Networks messages . . . . . . . . . . . . . . . . . . . . . 289
8.4.1 Scenario 1: A simple reformat procedure . . . . . . . . . . . . . . . . . . . . 291
8.4.2 Scenario 2: Exploiting WebSphere MQ Integrator functionality for
messages in the NEONMSG domain . . . . . . . . . . . . . . . . . . . . . . . 299
8.4.3 Scenario 3: Transforming New Era Of Networks message to XML 307
8.4.4 Scenario 4: Routing a message using a NEONRules node . . . . . . 320
8.4.5 Scenario 5: Further exploitation of WebSphere MQ Integrator features
for NEONMSG messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
8.4.6 Scenario 6: Simulating the rules engine . . . . . . . . . . . . . . . . . . . . . 343
8.4.7 Other migration considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Contents
Chapter 9. Developing and deploying custom nodes in Java. . . . . . . . . 351

9.1 What can you do with a Java plug-in?. . . . . . . . . . . . . . . . . . . . . . . . . . . 352
9.1.1 Plug-in nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
9.1.2 MbInputNodeInterface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
9.1.3 MbNodeInterface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
9.2 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
9.2.1 System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
9.2.2 Programming requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
9.2.3 Debugging and logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
9.3 Implementing an input node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
9.3.1 The Java code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
9.3.2 Packaging and loading the input node . . . . . . . . . . . . . . . . . . . . . . 359
9.3.3 Simple message flow to test the input node . . . . . . . . . . . . . . . . . . 360
9.3.4 How to test the input node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
9.3.5 How to use the input node to read a telnet stream . . . . . . . . . . . . . 369
9.4 Implementing a plug-in node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
9.4.1 Details of the example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
9.4.2 The Java code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
9.4.3 Packaging and loading the input node . . . . . . . . . . . . . . . . . . . . . . 374
9.4.4 A simple message flow to test the plug-in node . . . . . . . . . . . . . . . 374
9.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Chapter 10. Using the aggregation nodes . . . . . . . . . . . . . . . . . . . . . . . . 379
10.1 Developing a message flow using aggregation . . . . . . . . . . . . . . . . . . . 380
10.2 Components of the example system . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
10.3 The role of the aggregation nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
10.3.1 The AggregateControl node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
10.3.2 AggregateRequest node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
10.3.3 AggregateReply node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
10.4 The FAN_OUT flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
10.5 The processing flows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
10.5.1 PROC_A flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
10.5.2 PROC B flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
10.6 The FAN_IN flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
10.7 A trace showing the compound message tree . . . . . . . . . . . . . . . . . . . 404
10.8 Best practices for aggregation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Appendix A. Hardware/software configuration . . . . . . . . . . . . . . . . . . . . 411
A.1 Hardware/software specification for brokers running on Windows 2000 412
A.2 Hardware/software specification for the AIX broker machine . . . . . . . . . 413
A.3 Hardware/software specification for the Sun Solaris broker machine. . . 413
Appendix B. Source code for the Java extensions to WebSphere MQ
Integrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
vi
B.1 Java input node getting started example . . . . . . . . . . . . . . . . . . . . . . . . 416

B.1.1 SocketNode.java. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416
B.1.2 SocketNodeException.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
B.1.3 SocketNodeMessages.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
B.1.4 DirFilter.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
B.1.5 Compilation and packaging instructions . . . . . . . . . . . . . . . . . . . . . 421
B.2 Java plug-in node getting started example . . . . . . . . . . . . . . . . . . . . . . . 422
B.2.1 SwitchNode.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
B.2.2 TransformNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
B.2.3 Compilation and packaging instructions . . . . . . . . . . . . . . . . . . . . . 426
Appendix C. Oracle8i installation and configuration on Solaris. . . . . . . 429
Installation planning and design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Which versions are supported by the product? . . . . . . . . . . . . . . . . . . . . . . . 430
Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Preparing the Solaris machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Install Oracle8i server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Appendix D. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Contents of the Web material. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
System requirements for downloading the Web material . . . . . . . . . . . . . 447
How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
Related publications . . . . . . . . . . . . . . . . . . . . . .
IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Other resources . . . . . . . . . . . . . . . . . . . . . . . .
Referenced Web sites . . . . . . . . . . . . . . . . . . . . . .
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . .
IBM Redbooks collections . . . . . . . . . . . . . . . . .
......
......
......
......
......
......
.......
.......
.......
.......
.......
.......
......
......
......
......
......
......
.
.
.
.
.
.
449
449
449
449
450
450
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Contents
vii
viii
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult
your local IBM representative for information on the products and services currently available in your area.
Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product, program, or service that
does not infringe any IBM intellectual property right may be used instead. However, it is the user's
responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document.
The furnishing of this document does not give you any license to these patents. You can send license
inquiries, in writing, to:
IBM Director of Licensing, IBM Corporation, North Castle Drive Armonk, NY 10504-1785 U.S.A.
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer
of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made
to the information herein; these changes will be incorporated in new editions of the publication. IBM may
make improvements and/or changes in the product(s) and/or the program(s) described in this publication at
any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any
manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the
materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Information concerning non-IBM products was obtained from the suppliers of those products, their published
announcements or other publicly available sources. IBM has not tested those products and cannot confirm
the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on
the capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate them
as completely as possible, the examples include the names of individuals, companies, brands, and products.
All of these names are fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrates programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in
any form without payment to IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating platform for which the
sample programs are written. These examples have not been thoroughly tested under all conditions. IBM,
therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy,
modify, and distribute these sample programs in any form without payment to IBM for the purposes of
developing, using, marketing, or distributing application programs conforming to IBM's application
programming interfaces.
ix
Trademarks
The following terms are trademarks of the International Business Machines Corporation in the
United States, other countries, or both:
Redbooks(logo)
e (logo)
IBM
AIX
AS/400
CICS
Database 2
DB2
DB2 Universal
Database
Everyplace
IMS
iSeries
MQSeries
RAA
Redbooks
RETAIN
RS/6000
OS/390
ServicePac
SP
SP2
SupportPac
Tivoli
VisualAge
WebSphere
xSeries
z/OS
The following terms are trademarks of other companies:

ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel Corporation in the
United States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation
in the United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States, other countries, or both.
C-bus is a trademark of Corollary, Inc. in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by SET
Secure Electronic Transaction LLC.
Other company, product, and service names may be trademarks or service marks of others.
Preface
The release of WebSphere MQ Integrator Version 2.1 has introduced quite a few
changes; these changes make it more appealing for message flow developers
and message set designers to migrate to the new version so that they can exploit
this functionality.
After a brief overview of the product, we look at several migration issues that
might arise; we also describe the migration process for MQSeries Integrator
Version 2.0.1 and Version 2.0.2 on Windows NT and AIX platforms. The migrated
environment is further extended with a broker running on Solaris using Oracle,
and a broker running on Windows using SQL Server. Besides the migration of
brokers and the Configuration Manager, this redbook also investigates the
migration of message flows that use NEON functionality. We discuss several
scenarios explaining how to take advantage of the tighter integration between
NEON-based functionality and base WebSphere MQ Integrator functionality.
Finally, we introduce the major new features of this release. The extended
functionality of the Message Repository Manager and the extended support for
XML messages is explored using several examples. The support for Java-based
plug-in nodes and input nodes is demonstrated by developing a simple input
node which reads files from a directory to initiate a message flow. The new
aggregate nodes also demonstrate how to combine several messages of several
formats into a single XML message.
The team that wrote this redbook

This redbook was produced by a team of specialists from around the world
working at the International Technical Support Organization, Raleigh Center.
Geert Van de Putte is an IT Specialist at the International Technical Support
Organization, Raleigh Center. He is a subject matter expert in messaging and
business integration and has six years of experience in the design and
implementation of MQSeries-based solutions. Before joining the ITSO, Geert
worked in IBM Global Services, Belgium.
Chris Griego is an IT Architect for IBM Global Services working in the Enterprise
Application Integration West US practice. He has 25 years of IT experience,
working within a wide range of fields including mainframe application
programming, mainframe systems programming and support, and various
xi
Windows platforms and UNIX operating systems. He is an IBM certified

Solutions Expert for MQSeries Integrator and holds all three MQSeries
certifications. His areas of expertise include MQSeries, MQSeries Integrator,
CICS, and DB2.
Brian McCarty is an EAI specialist from the United States. He has worked with
IBM WebSphere and MQSeries technology for four years. His areas of expertise
include EAI and legacy to e-Business integration. Previously, he was an
application developer within the finance industry. In his free time, he contributes
to several WebSphere and Java users groups in Texas.
Peter Toogood is a Technical Specialist with Royal & Sun Alliance Insurance in
Sussex, England. He has a wide range of IT experience, from mainframe system
programming to distributed middleware architecture and design. He is an IBM
certified Solutions Expert for MQSeries and MQSI V2. In his spare time, he edits
the Xephon monthly technical journal MQ Update.
Ralf Ziegler is an IT Specialist in the Integration Technology Services of IBM in
Mainz, Germany. He is an IBM MQSeries Integrator certified specialist and has
comprehensive support and service experience with MQSeries and all versions
of MQSeries Integrator on distributed platforms.
Comments welcome
Your comments are important to us!
We want our Redbooks to be as helpful as possible. Send us your comments
about this or other Redbooks in one of the following ways:
Use the online Contact us review redbook form found at:
ibm.com/redbooks
Send your comments in an Internet note to:

redbook@us.ibm.com
Mail your comments to the address on page ii.
xii
Chapter 1.
features overview
While this redbook is intended for more experienced users of MQSeries
Integrator, we will start this first chapter with a quick summary of the basic
structure of the WebSphere MQ Integrator product and the roles of each
component. We will then introduce and briefly discuss the major new features
therein.
1.1 WebSphere MQ Integrator basics

WebSphere MQ Integrator, formerly called MQSeries Integrator, is IBMs
message broker product. It extends the messaging capabilities of MQSeries by
adding message routing and transformation features. It is used for Enterprise
Application Integration and is part of the WebSphere MQ family of products.
Business rules can be defined by graphically developing message flows which
consist of a sequence of nodes. Message flows are processes that can
encapsulate simple to extremely complex logic. They can be designed to perform
a wide variety of functions including (but not limited to):
Routing of messages to zero or more destinations based on the contents of
the message or message header. Both one-to-many and many-to-one
messaging topologies are supported.
Transformation of messages into different formats so that diverse applications
can exchange and understand messages.
Enrichment of the message content en-route, for example by using a
database lookup performed by the message broker.
Storing information extracted from messages en-route into a database, using
the message brokers built-in Database nodes.
Publishing messages, using topic/content based criteria for subscribers to
select which messages to receive.
Interfacing with other transport mechanisms, such as MQSeries Everyplace.
Extending the base function of WebSphere MQ Integrator with plug-in nodes,
which can be developed by customers as well as by IBM and ISVs.
Message content can be handled in a number of ways, including:
XML: for self-defining, or generic, XML messages.
MRM, or Message Sets defined in the Message Repository Manager, as:
XML defined to the MRM.
Tagged data.
Custom Wire Format, similar to a COBOL copybook layout.
Delimited data.
PDF, not Adobes PDF, but a specialIzed financial data format.
NEON: for messages defined using the New Era Of Networks formatter.
BLOB: for messages with no definition.
WebSphere MQ Integrator background

WebSphere MQ Integrator builds on the assured messaging capability of
MQSeries, and a typical message flow uses MQSeries messages for input and
output. There are MQSeries adapters and connectors available for various
systems and applications, and version 2.1 of WebSphere MQ Integrator also
allows other interfaces to be linked directly to broker message flows.
WebSphere MQ (formerly known as MQSeries) provides support for applications
with a number of application programming interfaces (MQI, AMI, JMS) in several
programming languages and for a number of communication models (including
point-to-point and publish/subscribe). WebSphere MQ also provides a number of
connectors and gateways to other products such as SAP R/3, CICS, and IMS.
WebSphere MQ Integrator extends the messaging capabilities of MQSeries by
adding message broker functionality driven by business rules. It provides the
intelligence to route and transform messages, the possibility to filter messages
(topic-based or content-based), and database capabilities for the enrichment of
the messages or for warehousing these messages. It also provides a framework
for extending the functionality with plug-ins for user-written or third-party
solutions.
MQSeries Workflow is the third component of IBMs family of products for
business integration and adds a further dimension to the integration of
applications. It is about integrating all the resources in a business process and
ensuring that the right information gets to the right target, be that a person or
application, at the right moment in the process flow.
WebSphere MQ Integrator applications

These can be existing MQSeries-enabled applications and need not be aware of
WebSphere MQ Integrator; in this case, the message flows set the correct
configuration values to handle the messages. Alternatively, the application can
prefix the user data of the message with a WebSphere MQ Integrator header
(MQRFH or MQRFH2) to control the way the broker handles the message.
WebSphere MQ Integrator supports two models for application communication:
Point to Point, which can include one-to-many and many-to-one (where the
number of message producers and the number of message receivers are
different).
Publish/Subscribe, which includes and extends the existing MQSeries
publish/subscribe model.
In addition to MQSeries inputs and outputs, WebSphere MQ Integrator now
supports MQSeries Everyplace and SCADA protocols. By developing plug-in
nodes, additional communication protocols can be supported.
Chapter 1. WebSphere MQ Integrator features overview
Family Traits
Workflow, Process Flow
Application Services
Tools
MQSeries
Workflow
Xform, Rules, Routing

API Framework
Templates, Utilities
MQSeries
Integrator
Modular Set of Offerings

MQSeries Foundation
Common Look and Feel
Management/Monitoring
Messaging Tools
Messaging Services
Standard Formats
Tools
MQSeries
Figure 1-1 WebSphere MQ Family
1.1.1 Architecture of WebSphere MQ Integrator

The components of a WebSphere MQ Integrator environment include:
Control Center(s), a Windows NT GUI for the message broker administration
and is also used for developing the message flows/sets.
Configuration Manager, with its configuration and message repository.
One or more brokers, which can be on different platforms or systems.
User Name Server, used to control publish/subscribe topic security.
MQSeries queue manager(s); at least one is needed per broker.
Database software to support the Configuration Manager and broker(s).
Client applications (source and target), which produce and consume
messages (or use the other supported types of protocols).
Optionally, system management software such as Tivoli to monitor the broker
and queue managers operational status.
Control
Center
Admin
Appl
GUI
Message Formats
Management
Message Flow
Configuration
Manager
Message
Repository
Broker
MQ Messages
Client
Client
Client
Appl
Appl
Appl
Message Flow
Controller
Filter
Input
Node
NodeFlow Engine(s)
Message
Administrative
Agent
Filter Node
Warehousing Node
Source
Client
Client
Client
Appl
Appl
Appl
Output Node
Output
Node
MQ Messages
Target
RDBMS
Input
Node
Filter
Node
Output Node
Compute Node
Output
Node
Message
Dictionary
UserNameServer
Warehousing Node
Figure 1-2 WebSphere MQ Integrator Architecture
1.1.2 The role of the Configuration Manager

A WebSphere MQ Integrator system is controlled by the Configuration Manager,
which manages the components and resources within the broker domain. The
domain configuration information is maintained in the configuration repository
and administered using the Control Center.
The Configuration Manager has the following main functions:
Maintaining the configuration repository.
This set of database tables records the configuration of the components in the
broker domain, including the message flows.
Managing the initialization and deployment of message brokers and message
flows.
Maintaining message set information in the message repository database.

These are the definitions of message contents and layout.
Checking the authority of defined user IDs to initiate control actions.
Domain
Local
Configuration
Repository
Shared/Deployed
Configuration
Repository
Message
Repository
JDBC
MQSeries
Java
Client
Control Center
Database
MQSeries
ODBC
Broker
Database
Configuration
Manager
ODBC
Queue Manager
Broker
User
Name
Server
Applications
Queue Manager
Queue Manager
Figure 1-3 Configuration Manager relationships
The Configuration Manager provides services to the other broker domain

components, performing the configuration updates in response to the Control
Center actions.
The Configuration Manager uses MQSeries messages to communicate with the
other components in the broker domain. Windows NT (or Windows 2000) with
DB2 must be used to host the Configuration Manager and its databases. Only
one Configuration Manager is used for a given broker domain.
A set of tables in a database, known as the configuration repository, is defined.
These tables must be managed using DB2 Universal Database for Windows NT.
The Configuration Manager uses a Java Database Connectivity (JDBC)
connection to this database.
A set of tables in a database, known as the message repository, is also defined.
These tables must also be managed using DB2 Universal Database for Windows
NT. The Configuration Manager uses an Open Database Connectivity (ODBC)
connection to this database.
A set of fixed named queues is defined on the MQSeries queue manager that
hosts the Configuration Manager. This MQSeries queue manager must exist on
the same physical system as the Configuration Manager, and is identified at the
time the Configuration Manager is created.
These queues are created when the mqsicreateconfigmgr command
(including associated variables) is executed through either the graphical
command assistant or through the command prompt. No actions are required
by the administrator to add the required definitions.
A server connection channel is defined to the MQSeries queue manager that
hosts the Configuration Manager. This connection is used by all instances of the
Control Center that communicate with the Configuration Manager.
Sender and receiver channels need to be defined to each broker in the broker
domain, except for a broker that shares its queue manager with the Configuration
Manager.
1.1.3 The functionality of the broker

A broker is the named resource that executes the business logic defined in the
message flows. Applications send and receive messages to and from a broker
(which is the deployed run-time, or execution, part of the product) using
MQSeries queues or the other supported methods of communication.
More than one broker can be defined per WebSphere MQ Integrator domain,
either on the same or on a different physical system. If you plan to use the
publish/subscribe service, you can connect a number of brokers together into a
collective, which allows optimization of the subscriber connections.
Message flows run within execution groups on the broker. An execution group is
an operating system process, and flows within it are threads. Individual flows and
execution groups can be stopped and started using the Control Center. By
default, only one execution group is defined, but more can be easily added.
It is good practice to run message flows belonging to different applications in
different execution groups, to provide some isolation between them in the event
of a problem. For even more isolation between applications, you can use
different brokers, but remember that each broker will need its own queue
manager.
Broker
Execution group
ODBC
connection
Message
flow
Message flow
Message dictionary
Queue Manager
Broker database
Figure 1-4 Broker overview
Brokers can run on a number of different platforms:

Windows NT (and Windows 2000)
AIX
HP-UX
Solaris
z/OS (using UNIX System Services)
iSeries (using the integrated xSeries server)
Linux (currently available as a technology preview)
Each broker has a related local MQSeries queue manager, which cannot be
shared with another broker, and a set of database tables to hold the broker
definitions; this set of tables is accessed through an ODBC connection.
These tables can be created using a number of database products:
IBM DB2
Microsoft SQL server (Windows only)
Oracle
Sybase
WebSphere MQ Integrator for z/OS brokers only support DB2.

Each broker requires:
A set of tables in a database to hold the brokers local data. This is accessed
using the ODBC connection.
A set of named queues on the queue manager associated with the broker
domain. These are created automatically when the mqsicreatebroker command
is issued.
Its own queue manager. It can share the queue manager hosting either the
Configuration Manager or the optional User Name Server, or both.
Since the broker uses a set of predetermined queue names, this creates the
dependency of an MQSeries Queue Manager per broker.
For operation, a broker requires both configuration and initialization data.
Configuration and initialization data are logically separate and stored in
different physical repositories.
Each broker instance needs an assigned, permanent and fixed name. This is the
Broker Instance name. This name, which is similar to the static identifier
assigned to a database before it is created, is used to distinguish tables
pertaining to one broker from tables where multiple brokers have been set up to
use the same database.
Creating a broker on the target execution platform does not itself update the
configuration repository; you need to create a reference to it using the Control
Center. Once this is done, and the broker is deployed (to initialize it), then
message flows and sets can be assigned to the broker. Deploying the flows
starts their execution.
Several different message flows can be assigned to an execution group,
although using different execution groups provides better application isolation. A
particular message flow can also be configured to run more than one instance of
itself inside the execution group.
The execution group environment is also known as a data flow (or message flow)
engine. The engine is responsible for loading any plug-in nodes which can be
developed, or provided, to extend the function beyond the supplied IBM nodes.
These are known as loadable implementation libraries (or .lil files).
Brokers provide information, in the form of published event messages, in
response to changes; these can be used by system management tools to update
their management agents as to the status of the broker components.
1.1.4 Publish/subscribe and the User Name Server

Message flows that include a publication node provide a publish/subscribe
service. Publishing applications generate input to such flows, and subscribing
applications register a subscription with the broker based on the topic and/or
content of interest to them. Within a broker collective, subscribers can register
with their local broker and messages are automatically routed to them.
With publish/subscribe, the broker provides indirection between publishers and
subscribers. Subscribers can use a mixture of topic and content criteria to select
which messages to receive.
Topic-based security can be implemented to provide administrative control over
who can publish and who can subscribe. The WebSphere MQ Integrator
component User Name Server, which is optional and needed only for
publish/subscribe security, is used to interface with the brokers platform security
system. It provides information about users and groups to the Configuration
Manager and brokers.
When the User Name Server is created, a set of fixed named queues are defined
to its hosting queue manager, which may be a queue manager shared with the
Configuration Manager or a broker if they are installed on the same system.
Figure 1-5 shows some applications of the role of publisher or subscriber and of
the role of the broker as intermediate message router.
10
.
Publish: STOCK/FORD
Publish: STOCK/IBM
Broker
M
/IB
CK
O
ST
Subscribe: STOCK/*
ta
ta
da
da
/F
CK
ta
da
Se
l
ST ecte
OC d
K/I
BM
O
ST
D
OR
Broker
Subscribe: STOCK/IBM
d O
cte F
le CK/
e
S O
ST
RD
ta
da
Subscribe: */FORD
WHERE number>1000
WHERE value>10000
Figure 1-5 Subscribing to topic/content
1.1.5 The user interface: the Control Center

The Control Center is a GUI running on Windows NT (or 2000) which allows you
to configure and control your brokers. The Control Center connects to the
Configuration Manager over TCP/IP, using the MQSeries Client for Java. It can
be installed on the same physical system as the Configuration Manager, but it is
typically used on another PC connected over a LAN.
Any number of Control Center instances can be connected to the Configuration
Manager; the Conntrol Center is also used by the message flow developers as
well as by broker administrators. Several user roles are predefined:
Message flow and message set developer:
Can create message flows and message sets.

Can access the Message Sets view and the Message Flows view.
Message flow and message set assigner:
Can create execution groups within brokers, then assign and deploy
message flows and message sets to brokers.
Can access the Assignments view only.
11
Operational domain controller:
Can create brokers and collectives, and define the topology.

Can deploy all types of data and monitor the operational domain.
Can access the Topology view, the Assignments view, the Topics view, the
Operations view and the Subscriptions view.
Topic security administrator:
Can create topics and their access control lists, and deploy them.
Can access the Topics view and the Topology view.
All Roles
Can perform all Control Center tasks.

Can access all views.
There are four Windows NT security groups (mqbrdevt, mqbrasgn, mqbrops,
mqbrtpic) which are used to grant privileges. Standard Windows user
administration is used to assign membership of one of more of these groups to
users; the role is then selected in the Control Center Preferences dialog.
Figure 1-6 Control Center view
12
When you decide to make changes to a resource managed by the Control

Center, you must check out the resource. This gives you exclusive control over a
locked copy until you check in or unlock the resource. You can save a local copy
of the changed resource without checking it back in, if you wish to do so.
Control Center resources can exist in three states:
Local: a copy of the configuration data being worked on, usually obtained by
checking out the resource from the shared copy. Changes made to the local
copy are not visible to other users until the copy is checked in.
Shared: the version of the resource stored by the Configuration Manager and
visible to all users. Note that only one level exists and no previous version is
saved. SupportPac IC04 offers procedures for version management.
Deployed: the active copy of the configuration data that is in the broker and
also stored in the deployment database of the Configuration Manager.
The Control Center allows the export and import of message flows to and from a
flat file in XML format. Message sets can be imported and exported using the
mrmimpexpmsgset command.
1.2 Anatomy of a message flow

Message flows consist of a number of nodes (or primitives) which are wired
together to form a broker application. Each node has terminals for input or
output, or both (most nodes have several output terminals). The Control Center
message flow view is used to construct the flows using nodes like:
MQInput node - encapsulates an MQGET operation.
MQOutput node - encapsulates an MQPUT operation.
Extract node - extracts specified fields from a message.
Filter node - routes a message according to an ESQL expression.
Compute node - modifies message or database contents using ESQL.
Database node - performs a database operation.
Reset Content Descriptor - resets the message properties.
There are many other IBM primitive nodes available; these are described in the
manual Using the Control Center, SC34-5602-04. Each node will have properties
which can be set to certain values for the parameters of the node. For example,
the queue manager name is a optional property of the MQOutput node.
13
Some nodes have their function controlled by ESQL statements. ESQL is a free
format, high-level programming language derived from SQL version 3. By coding
ESQL, it is possible to develop complex logic for manipulating either message or
database contents (or both), without using excessive nodes in a flow.
ESQL, like most programming languages, can be used to develop business
logic, but is generally coded to select and analyze message and/or database
contents, and to perform the more complicated conversions of data values.
Details about ESQL can be found in the manual ESQL Reference,
SC34-5923-01.
Although ESQL does not provide subroutines to reuse common code, it is
possible to include smaller message flows as sub-flows; such flows can be used
for generic parts of message flows such as error handling routines. In addition,
the use of sub-flows improves readability of the logic, regardless of reuse.
Extending the available nodes

WebSphere MQ Integrator allows the development and implementation of
custom nodes and custom parsers. These can be written in C or Java and may
also be provided by an ISV. A number of useful plug-ins are available as
SupportPacs and freely downloadable from the IBM WebSphere MQ Integrator
Web site. It is important to check that any such custom node is compatible with
all the target broker platforms onto which you may wish to deploy the message
flows.
Figure 1-7 shows a message flow that uses some of the available message
processing nodes.
Figure 1-7 Example of a message flow
14
Each node has properties that must be set; for example, with the MQInput node,
you would specify the input queue name (the queue managers is always the
same as the brokers), conversion and other MQGET options, the transaction
mode, the message domain, etc. Generally, it is necessary to specify more of
these values when handling messages that do not contain an MQRFH2 header.
Figure 1-8 shows the default page of the properties on an MQInput node; this
message flow is able to handle messages that do not have an MQRFH2 header.
Figure 1-8 Properties of the MQInput node
In most cases, the parsed message is passed unchanged from node to node,
except in the case of the Compute node, which can modify it; the output
message of the Compute node then becomes the input to the next node in the
flow. Some nodes provide a drag-and-drop graphical interface to assist with
element selection; for example, the DataUpdate node does so for its output
database table, as shown in Figure 1-9.
15
Figure 1-9 Example of DataUpdate node field selection
ESQL statements are added using the ESQL tab window on the Properties page
of WebSphere MQ Integrator nodes such as the Compute and Filter node. In
addition to simple assignments, ESQL includes branching and looping
capabilities.
Example 1-1 ESQL statements
SET OutputRoot = InputRoot;
DECLARE TotalItemQuantity INTEGER;
SET TotalItemQuantity = (SELECT SUM(CAST(T.itemquantity AS INT))
FROM InputBody.Message.receiptmsg.transactionlog.purchaseselement[] AS T
WHERE CAST(T.itemname AS CHAR) = 'Shampoo');
SET
OutputRoot.XML.Message.receiptmsg.transactionlog.totalselement.totalitemquantit
y = TotalItemQuantity;
The visual message flow builder in the Control Center can be used to assemble
sequences of nodes (or primitives) that provide logic similar to that of a
programming language. Loops and branches can be performed using nodes.
16
In Figure 1-10, the Filter node tests a counter stored in the message tree; if the
comparison proves false, the flow passes to a DataInsert node. This is followed
by a Compute node, which increments the counter. When the filter comparison
test eventually proves true, control passes to the MQOutput node.
Figure 1-10 Example of loop control in a flow
In traditional programming languages, subroutines are used to group commonly

used statements. With WebSphere MQ Integrator message flows, this is
achieved using sub-flows. These flows are comprised of the same nodes as
main-line flows, except that they have Input and Output Terminal nodes to
connect to an upper-level message flow.
Main message flows (or higher level sub-flows) simply include the desired
sub-flow as if it were another node, and wire up its terminals accordingly. This
technique is valuable for very complex message flows, as it structures the flow
into a series of smaller, more readable sub-flows.
Compute nodes are similar to groups of executable statements in other
languages and can be inserted into flows when there is a need to perform
calculations or assign values to fields, especially when converting data formats.
ESQL has branching and looping features that work inside the Compute node.
Compute nodes can modify the message tree contents and update databases.
They are, therefore, the most powerful nodes available. ESQL is also used
extensively in Filter and Database nodes. WebSphere MQ Integrator 2.1 offers
an ESQL code palette to allow drag-and-drop development.
17
1.3 Enhanced Message Repository Manager

WebSphere MQ Integrator supports self-defining XML and JMS messages.
These types of messages do not have to be defined to the Message Repository
Manager, although you can do this to exploit the MRM features and the
integration of MRM with other components of WebSphere MQ Integrator.
Defining your message formats to the MRM provides greater control over the
formats and enables increased functionality within the Control Center to
manipulate messages in the flows.
Predefined message formats are grouped in message sets. These are created in
the Control Center, or imported from previously exported copies. Message sets
allow message flows to understand the structure of incoming message data and
therefore need to be deployed to the run-time (or broker) environment.
You can change the format of any message in the MRM domain to any other
format defined to the MRM; most of the changes are made automatically by the
broker. Drag-and-drop element selection is available in the node properties
because the message structure is known at build time.
The MRM components are:
At build time:
GUI: the Control Center Message Sets tab

Repository: managed by the Configuration Manager
Importers and extractors: used to move message sets from one
Configuration Manager to another
Deployment: message sets need to be assigned to a broker and deployed
At run-time:
Message parsers
Run-time dictionaries
Physical format descriptors
The MRM message model consists of meta-data representing logical message
definitions that are platform- and language-independent. It has layers of
additional data used for mapping to physical formats. Definitions are made up of
reusable components or objects and organized into message sets. Figure 1-11
shows the definition model for a message.
18
Logical structures consist of one or more compound types made up of simple

types, elements or other compound types. Often, it is easier to import the
definitions than it is to create them in the Control Center; for example, a COBOL
or C structure can be imported to create a new compound type. XML DTDs can
now also be imported to create message set definitions.
Message
A message has a structure based on
..
User defined
Compound
Type
Made up of data units called
Or made up
of groups ..
Type
Element
Format defined by ..
Pre-defined
Simple type
Element may optionally

have Element Value
constraints, e.g., for
STRING elements;
minimum and/or maximum
length
Element
Value
Figure 1-11 Basic message components
A message set is a group of messages that are related in some way. A message
defines the format of a single unit of information to be exchanged between
applications. A message can contain, or embed, other messages (so-called
multi-part messages). An element defines the format of a single unit of
information within a message. A type defines the format of an element and can
be a simple or compound type. A category groups messages and transactions
within a message set. A transaction (in this sense) is a logical grouping of
messages within a message set.
Figure 1-12 shows what simple types are available in the MRM. These simple
types are the building blocks for constructing compound types.
19
Binary
Boolean
The data content does not conform to any numeric or

character representation (for example, BLOB)
Do not confuse with COBOL BINARY datatype.
Used when the element can have only two
values: true or false.
Used for dates and/or
Datetime
times
Decimal
Can be used for any number up to 31 decimal digits,

for fractions and numbers which are outside of the
Integer datatype.
Float
Can be used for any real number, for fractions and

numbers which are outside of the Integer or Decimal
datatype.
Integer
Used for whole numbers in the range -2147483648 to

+2147483647
String
Used for character data
Figure 1-12 Simple types in the MRM
The MRM type composition options are:

Empty
Choice
Unordered set
Ordered set (the default)
Sequence
Simple unordered set
Message
Value constraints can be defined for elements for such things as minimum
length, scale, default value, etc. This is primarily for documentation purposes, as
currently the broker does not perform run-time validation.
20
A message in the MRM domain can have one of the following wire formats:
CWF (Custom Wire Format or Legacy messages)
TDWF (Tagged / Delimited Wire Format, such as SWIFT)
XML (defined, as opposed to self-defining or generic)
PDF (not Adobe, but a specialized financial format)
CWF messages are often defined by importing a C or COBOL structure. XML

messages can also be defined by importing a DTD. Some tagged formats are
predefined to the MRM and others can be configured in the Control Center.
Message sets can be imported and exported to XML format flat files using the
supplied mqsiimpexpmsgset command. This can be used both for version control
and to copy message sets between Configuration Managers.
Tagged data formats

The following messaging standards can be selected in the Control Center:
Unknown (this is the default)
ACORD AL3
SWIFT
EDIFACT
X12
Tagged/Delimited messages:
Consist of text strings
Are optionally preceded by fixed text
Are followed by child elements, which:
May be of fixed length or separated by a delimiter.

May be preceded by a tag that uniquely identifies it (the tag may be of
fixed length or separated from the data by a delimiter)
The data for child elements may represent simple values or sub-structures.
Are followed optionally by fixed text
Example 1-2 shows a tagged/delimited message as used in the SWIFT network.
21
Example 1-2 A SWIFT message

{1:F01BANKBEBBAXXX2222123456}{2:I100IBMADEF0AXXXN}{4:
:20:X
:32A:940930USD1000000,
:50:LINE1
:59:LINE1
-}
The example SWIFT message includes two headers and a message body. Each
is wrapped within curly braces ({...})
{ is the Group Indicator.
: is the Tag Data Separator.
}{ is the Delimiter.
} is the Group Terminator.
1, 2, 4 are Tags.
In Chapter 6, New MRM features explored on page 163, some more examples
of tagged data formats are discussed.
1.4 XML support

XML messages are supported by WebSphere MQ Integrator as either generic (or
undefined) XML or as MRM defined XML. This determines whether the generic
parser or the MRM parser is used to interpret them. Defining XML messages in
the MRM enables more comprehensive facilities to process them, such as the
broker performing message transformation to Custom Wire Format.
When defining XML messages to the MRM, an XML format layer can be
specified. This allows the output XML to be customized; for example, the data
elements can be given attributes.
Output XML can be created:
With tags
With or without attributes
With or without attribute identifiers
With DOCTYPE, Root Tag Name, XML Name, Render, Format, Encoding
You can now import a DTD into the Control Center. This can be a DTD generated
from a WebSphere MQ Integrator message repository, or a DTD from another
source. You can then use the MRM to model these XML messages.
22
Several examples of this extended support for XML messages are given in
Chapter 7, Exploring the new XML features on page 205.
1.5 Database support

WebSphere MQ Integrator uses DB2 databases for the Configuration Manager
which must run on Windows NT (or 2000). The brokers can use DB2, SQL
Server, Oracle or Sybase for either the broker database and/or any user
database (SQL server only runs on Windows NT and z/OS only has DB2 as a
supported database manager).
User databases are where the message flows can optionally access or store
database records. Several nodes are provided to assist with developing
message flows that use database information. It is not mandatory to use a
database in a flow, although the broker uses its own database to retrieve
configuration data and store persistent run-time data.
When a message flow updates one or more user databases, an important
consideration is the transactionality of the flow. Many business transactions
require that all updates be committed, or rolled back, in a single unit of work. This
normally includes updates to message queues as well as databases.
MQSeries is able to coordinate transactions between queue managers and
databases by acting as an XA transaction manager. Supported releases of DB2,
Oracle and Sybase can participate as Resource Managers in a distributed XA
transaction coordinated by MQSeries. On z/OS, all transactions are coordinated
by RRS and all the flows are always globally coordinated by default.
Message flows can be made transactional for message queue and database
interaction by selecting the appropriate option in the node properties. XA (or
global) coordination needs some configuration to operate correctly: switch files
must be defined to the resource manager (in the qm.ini file on UNIX).
In Chapter 4, Deploying a broker on Sun Solaris using Oracle 8i on page 131,
we discuss the use of Oracle 8i as the database for the broker and how to
configure all products for XA resource coordination.
Supported releases are DB2 version 6.1 and 7.1, Oracle 8.1.6 and 8.1.7, and
Sybase 12. Fixpaks or service may need to be applied.
23
1.6 New ESQL features

SQL is the industry standard language for accessing and updating database
data. ESQL is a language derived from SQL V3 and is particularly suited to
manipulating both database and message data. An ESQL program consists of a
number of statements that are executed in the order they are written.
ESQL programs form an essential part of WebSphere MQ Integrator nodes, such
as the Compute, Filter and Database nodes. In common with other high-level
programming or scripting languages, ESQL has statements, operators,
expressions, functions, data types, variables, reserved words and so forth.
Example 1-3 ESQL from a Compute node
DECLARE C INTEGER;
SET C = CARDINALITY(InputRoot.*[]);
DECLARE I INTEGER;
SET I = 1;
WHILE I < C DO
SET OutputRoot.*[I] = InputRoot.*[I];
SET I=I+1;
END WHILE;
DECLARE elementnum INTEGER;
SET elementnum="InputBody"."totalselement"."f_reserve";
SET
"OutputRoot"."MRM"."purchaseselement"."q_reserve"="InputBody"."purchaseselement
"[elementnum]."itemquantity";
Some of the new ESQL features in WebSphere MQ Integrator version 2.1 are:
Environment: passes user defined variable information between nodes.
ESQL UUID function: creates a universally unique identifier.
Field references variables: these act as variable pointers.
Binary and Date/Time casting.
SQLCODE and SQLSTATE database indicators: these are introduced.
ESQL node rationalization for Compute, Filter and Database nodes:
These each can modify both DBMS data and environment variables.
Performance is improved by avoiding the need to create new message
tree elements for passing data between nodes in a flow.
They have drag and drop facility for ESQL code, selectable from a palette.
Improved support of NULLs.
PROPAGATE keyword to send messages to the output terminal.
24
Figure 1-13 shows the new ESQL palette on the left. From there, you can drag
and drop ESQL constructs to easily create valid ESQL statements.
Figure 1-13 ESQL code palette
1.7 Summary of new features

Following is a summary of the new features introduced with MQSeries Integrator
V 2.0.2 or are introduced in WebSphere MQ Integrator V2.1. Some of these
features have already been discussed briefly in this introduction chapter. Most of
them will be looked at in greater detail in the upcoming chapters.
MQSeries Integrator V2.0.2:

MQSeries Everyplace and SCADA input and output nodes
New Era Of Networks V5.2 libraries and improved integration
Visual debugger for message flow development
XA transaction support for Oracle on Solaris
25
Performance improvements
Support of MQSeries 5.2 and Windows 2000
Supported HP-UX 11 platform
AS/400 supported via the integrated Windows NT environment
Usability improvements and plug-in node development wizard
A new manual: ESQL Reference
WebSphere MQ Integrator V2.1:

Addition of the z/OS (OS/390) platform (using Unix System Services)
XML improvements (mixed content, attribute support, DTD import)
Tagged Message Support (user specified delimiters or tags)
Industry Standard messages (SWIFT, EDIFACT, X12, AL3)
Oracle and Sybase XA support on NT, AIX, Solaris and HP-UX
Plug-in API extensions (input nodes can now be developed)
Java environment available for plug-in nodes (but not parsers)
ESQL enhancements, including environment variable storage
New SupportPacs, including command line deploy
Available Control Center security exit
Message aggregation capability (three new nodes)
Improvements to the MRM (logical message model extensions)
MRM performance improvements
26
Chapter 2.
Migration considerations
This chapter discusses a variety of items that need to be considered when
planning an upgrade to WebSphere MQ Integrator V2.1. We do not mean to
cover every consideration possible. Many elements must be considered; many of
these are environment-specific and will depend on your individual installation.
Hopefully, the major points we cover will give you plenty of insight to plan your
upgrade successfully.
Some of the things that need to be factored into an upgrade plan are based on
the current environment. Some are based on schedules. Others, and perhaps
the most often overlooked, are the requirements imposed by the software. Many
users fail to fully read about and understand the differences between the release
they are implementing and the one being replaced. We cannot stress enough the
need to read all documentation and any readme files shipped with the software.
Readme files contain the most current information available on what you need to
know about the release being installed. For WebSphere MQ Integrator V2.1, this
information is also available on the Web:
http://www-3.ibm.com/software/ts/mqseries/support/readme/
This is especially helpful if you received the software some time before
installation.
27
2.1 Considerations overview

WebSphere MQ Integrator V2.1 contains several changes that require special
considerations when upgrading. There are also considerations to be taken into
account just because it is WebSphere MQ Integrator that is being upgraded.
WebSphere MQ Integrator requires that the following topics be considered during
an upgrade:

What platforms (operating systems) are involved?

Are any components moving from one machine to another?
Are there brokers that will move from one Configuration Manager to another?
What impact will the upgrade schedule have on your promotion schedules for
your applications?
Will there be co-existing multiple software versions?
Are there any MRM domain messages with XML format in the environment?
What database(s) is/are involved?
If the database is DB2, will it be upgraded?
If MQSeries Integrator V2.0.1 is installed, will it be upgraded to MQSeries
Integrator V2.0.2 or WebSphere MQ Integrator V2.1?
Are all Maximum Message Lengths, Queues, and Sender and Receiver
Channels set to sufficiently large values?
Are MQSeries logs large and numerous?
Are the brokers or Configuration Managers upgraded first?
What user IDs are used?
Are the user IDs defined using proper authorities?
Is the New Era Of Networks rules and/or formatter used?
Will any custom nodes or plug-ins be created?
How many message sets are there?
Are all message sets and message flows archived outside of MQSeries
Integrator?
Will the old version be uninstalled before the new version is installed?
2.2 Uninstalling the older version

Not all platforms require an older release to be uninstalled before installing the
newer one. Unfortunately, some do. Unix is one of those. There are also reasons
why it would be desirable to uninstall the old version before installing the new
one.
One of the reasons to uninstall has to do with the Windows platform. When an
older release was installed, it may have installed in directories that are versionor release-specific. It also may have created folders that are release- or
version-specific, including the one in the Start menu.
28
The install on a Windows platform will automatically install the upgrade in the
directories and folders where the current version is installed. It gives you no
choice.
This can be quite confusing for some. Imagine that you have WebSphere MQ
Integrator V2.1 installed, but all folders and directories have 2.0 in their name. Is
this confusing to you or your clients? You may want to correct this during the
upgrade. Either create all folders and directories without any release or version
information in the name, or use the current release and version in the names.
The most important thing to remember when performing an uninstall is that the
uninstall does a delete of the broker. Therefore, if you plan to uninstall, be sure to
undeploy everything from the brokers on the machine you are upgrading, before
you begin the uninstall.
2.3 Message repository changes

WebSphere MQ Integrator V2.1 has implemented an enhanced message set
environment. Because of this, the tables in the message repository database
(typically called MQSIMRDB) must be deleted and redefined.
This is significant to the person performing the upgrade. All message sets must
be exported prior to beginning the upgrade process. Care must be taken to
insure that no one has anything checked out and that no one will be connected to
the product during the upgrade. Each message set must be exported individually.
This can be a time consuming effort if there are numerous message sets. A script
to execute the export for all message sets might be the best solution.
If it is part of the standard procedures to export all message sets and archive
them in another tool, this export step may be bypassed, but only if all messages
sets are archived at their most current definition. This probably works best in a
non-development environment, such as production or quality assurance
environments. Environments where developers are making changes would more
than likely have message sets that have not been archived. You must take the
time to either export all message sets or discover those that are not archived in
their present state and export them.
The upgrade requires that the Configuration Manager be deleted and recreated
to include all changes to the message repository. The delete is executed without
affecting the configuration database or the message repository database.
Chapter 2. Migration considerations
29
After installing WebSphere MQ Integrator V2.1, the tables in the message

repository database will be dropped and the tables in the configuration database
will be migrated. This migration of tables will alter the tables to incorporate the
changes for this release. The changes to the message repository database are
too complex to perform a migration. Therefore, it is required that you export
message sets, drop the tables, recreate the tables, and import the message sets.
This is documented in the WebSphere MQ Integrator Installation Guide.
When the Configuration Manager is recreated, the message repository database
tables will also be recreated at that time. The configuration database is used in its
migrated state. The newly recreated Configuration Manager will have all the
information as to what was previously deployed to what brokers still available in
the configuration database. Care must be taken to insure that the Configuration
Manager is recreated with the proper service user ID and password.
2.4 Moving components

If a broker is to be moved from one Configuration Manager to another, it first
should be totally removed from the current Configuration Manager. What this
entails is the removal of all message flows and message sets currently deployed
to that broker. This broker must be deployed empty. Then the broker can be
removed from the current Configuration Managers topology. A full topology
deployment must be performed when deleting a broker. This is necessary to
insure that all database entries are updated properly. The broker can now be
defined to the topology of the new Configuration Manager.
If a broker is to be moved from one machine to another, it first must be deleted
from the current Configuration Manager. What this entails is the removal of all
message flows and message sets currently deployed to that broker. This broker
must be deployed empty. Then the broker can be removed from the Configuration
Managers topology. A full topology deployment must be performed when
deleting a broker. This is necessary to insure that all database entries are
updated properly. Now the broker can be created on the new machine. The
broker can now be redefined to the topology of the Configuration Manager.
If a Configuration Manager is to be moved from one machine to another, all
brokers must be removed from its topology, all message sets must be exported,
and all message flows must be exported. The procedures outlined above for
moving a broker are used to delete the brokers from the Configuration Managers
topology. After the message sets and flows have been exported, the
Configuration Manager can be deleted. It can now be defined on the new
machine. All message sets and flows can be imported, and brokers defined to
the topology and message sets and flows deployed.
30
It is not necessary to delete a Configuration Manager before creating its

replacement on another machine. However, the brokers must be removed from
the original topology before they can be assigned to the topology on the new
machine.
Again, if the message sets and message flows are archived in an external tool,
they may not need to be exported at this point. They can be recovered from the
archive. But if there is any question as to the validity of the archived components,
or just as an extra precaution, it may be desirable to go ahead with the export
anyway. This is a risk versus effort decision.
2.5 Enhancement and schedule considerations

When upgrading, it is unlikely that all environments will be upgraded at the same
time. At the very least, a production environment would not be upgraded until the
upgrade has been verified in another environment. Because of this, the
differences between releases and the production schedule must be considered.
These factors have an impact on how much time there is to accomplish the
upgrade, the order in which the components are to be upgraded, how thorough a
test must be performed, and what functions in the new release need to be
avoided until they can be promoted to production.
At the most basic level, care must be taken to avoid using new functionality in
applications until that functionality is available in production. This is why the
schedule becomes an important factor. The depth and length of testing has a
direct impact on how long you have to be careful not to use the new features. It is
important to avoid a situation in which a change has been thoroughly tested, yet
does not work as planned when promoted to production, due to incompatible
functions between releases.
Although you may be careful to avoid using new functions, you may come across
the case where something that was allowed in the current release cannot be
supported in the new release or across releases. Messages that are in the MRM
domain and in the XML format are not supported across releases. Therefore,
applications that use this scenario cannot be modified in an environment where
the broker and Configuration Manager are not at the same release level.
Most of the time, when something that was supported in the old release is not
supported in the new release, it is because someone has found a hole in the
logic. When something is documented as not working but someone finds that it
will work, or something works that does not seem like it should, do not use it. If it
was documented as not available or as working one way and not the way it is
31
actually working, it will probably not work in a near future patch or upgrade or in a
new release. This is good advice for any product at any time. Nothing is as
frustrating as having to rewrite an application because holes have been closed in
the software you have been using.
The changes to the message repository in V2.1 make it necessary to carefully
choose when the upgrade is to be performed. Once the upgrade has begun on
any environment that will have components promoted to another environment, all
promotions from the upgraded environment that involve MRM messages must be
postponed until the environment promoted to is also upgraded to V2.1.
This can have a significant impact on the schedule, especially if there are many
environments involved in an applications promotion path. A great deal of time
can pass between the production environment upgrade and the first environment
upgrade. This is where the application problems or enhancements must be taken
into consideration. It is very annoying to begin an upgrade knowing it is going to
take a fixed amount of time and then find that an application change is scheduled
to begin after you have begun, but is scheduled for production before you are.
This affects both the personnel performing the upgrade and the client who must
now wait for changes until the upgrade is complete.
When performing an upgrade, it is common for the upgrade to begin at the lowest
common denominator. In the case of WebSphere MQ Integrator, that would be
the broker. The WebSphere MQ Integrator V2.1 Administration Guide documents
that you can have a V2.1 broker with a V2.0.1 or V2.0.2 Configuration Manager if
you install the compatibility modules on the broker. It also strongly recommends
that the Configuration Manager be upgraded first. The brokers should be
upgraded immediately following the Configuration Manager upgrade and before
anything is deployed.
The best scenario is to upgrade both the Configuration Manager and all of its
brokers at the same time. If there is a broker on a UNIX machine, the software
must be uninstalled before the new release can be installed. Because of this and
the changes in the message repository, it is best if all flows and message sets
are undeployed, the software upgraded and flows and message sets redeployed.
This provides the surest method of insuring that all components are upgraded
and that all deployed flows and message sets match exactly what is in the
Configuration Manager.
If there is no UNIX machine attached to the Configuration Manager, then
undeploying the message flows is not required. However, because of the
changes in the message repository, the currently deployed message sets should
be undeployed and redeployed after the upgrade. Though this is not absolutely
required at this point, it will be required before the message sets can be deployed
again after the upgrade. As documented in 2.3, Message repository changes
on page 29, the UUID of the message set will change when it is reimported after
32
the upgrade. When the message set is later deployed, a duplicate message set
name error will occur. This is because the message set is already deployed with
the UUID created previously and the upgraded message set has a new UUID but
the same message set name. The previously deployed message set must be
undeployed before the new one can be deployed.
In an ideal world, there would be only one application environment per machine.
That is, if there were Development, Test, QA and Production environments, the
brokers for each of the environments would be on separate machines. When
dealing with UNIX environments, it is very common to find multiple environments
on one machine. Production environments are almost always separated from the
others, but all of the other environments can often be found on the same
machine.
This poses another problem. There is only one version of the software running
multiple environments. When the software is upgraded, all environments must
also be upgraded. When upgrading UNIX machines to WebSphere MQ
Integrator V2.1, the prior release must be uninstalled. The brokers should be
deleted before the uninstall is executed, as documented in 2.4, Moving
components on page 30.
Once the uninstall and upgrade is complete for the brokers on the UNIX machine,
the choice is now whether to upgrade all of the associated Configuration
Managers at once and redeploy, or to upgrade them one at a time. If you choose
to upgrade them one at a time, it must also be decided whether or not to deploy
anything from those not yet upgraded. The availability of compatibility modules
makes this a viable alternative.
The safest method would be to upgrade the Configuration Managers one at a
time, but not redeploy anything from a Configuration Manager that has not yet
been upgraded. This is, again, where scheduling is critical. Is there time for this
method? How much time is there to test each message flow after it has been
deployed following the upgrade? How many environments are involved? What
applications will this affect? These are all critical factors to the upgrade process
completing successfully without disrupting the ongoing daily business.
2.6 DB2 database upgrade

Version 7 of DB2 UDB is shipped with WebSphere MQ Integrator V2.1. It was
also shipped with MQSeries Integrator V2.0.2. MQSeries Integrator V2.0 and
V2.0.1 were shipped with V6.1 of DB2. The newer version of DB2 is not required.
Therefore, it poses the question of whether or not DB2 should be upgraded.
33
Many organizations have dedicated database servers and the database software
is maintained separately from the MQSeries Integrator software. The databases
themselves reside on servers apart from those where MQSeries Integrator
resides. Also, the group responsible for the databases and the database software
is most often a separate group from the group responsible for MQSeries
Integrator.
Other organizations may not require that the databases be on designated
database servers. The databases are on the same machines as the MQSeries
Integrator components. The group responsible for the MQSeries Integrator
software and the database software may be one and the same.
The reality is that a database upgrade is more complicated than simply installing
the new version of the software. It can be a large undertaking of its own.
Upgrading the database software can greatly impact your schedule.
Therefore, it is recommended that the database upgrade be made a separate
project from the upgrade of MQSeries Integrator when:
The databases are on dedicated database servers.
The databases are not on the same machine as MQSeries Integrator.
The database software is not dedicated to only the MQSeries Integrator
databases.
The databases cannot or should not be deleted.
The new version of DB2 can be implemented as part of the WebSphere MQ

Integrator upgrade without greatly impacting the schedule when:
The installation of the WebSphere MQ Integrator databases is on a new
machine where DB2 does not currently reside.
The MQSeries Integrator software is being deleted before installing
WebSphere MQ Integrator V2.1, allowing the databases to also be deleted
(typically only on UNIX broker machines).
2.7 Recommendations
Below are several recommendations that should be considered when planning
the upgrade to WebSphere MQ Integrator V2.1.
If upgading from MQSeries Integrator V2.0.1, bypass upgrading to MQSeries
Integrator V2.0.2.
Do not complicate the upgrade by also upgrading the version of the database
software used.
34
Perform complete backups of each machine prior to doing anything.

Stop any and all MQSeries Integrator components (brokers, Configuration
Managers, User Name Servers).
Stop all MQSeries Queue Managers.
Stop all databases.
Perform complete database backups.
Involve application groups in the scheduling of the upgrade.
Consider undeploying all message flows and message sets and deleting all
brokers when upgrading an environment.
Make a detailed list of which message flows and message sets are deployed
to which broker and which execution group before beginning.
If planning to add new machines and if it is possible, coordinate machine
installations with the upgrade. It is easier to perform a new install than to
move components from one machine to another.
Document all user IDs and passwords used for all components (WebSphere
MQ Integrator and database).
Make sure all maximum message lengths for transmission queues and
channels are set to the maximum allowed value.
35
36
Chapter 3.
Migration of an MQSeries
Integrator environment
This chapter describes the evolution of a typical MQSeries Integrator
environment. This environment consisted first of a single broker using MQSeries
Integrator. Over time, new applications and message flows were added. An
application was added on Windows and AIX using MQSeries Integrator V2.0.2.
This environment used its own Configuration Manager. When a third application
was added, the latest version of WebSphere MQ Integrator was implemented.
Over time, the described environment has come to consist of three different
Configuration Managers using three different versions of the product. We will first
investigate the migration of each Configuration Manager and its brokers and then
consolidate the brokers on a single Configuration Manager.
37
3.1 Evolution of the MQSeries Integrator environment

Originally, we had an MQSeries Integrator environment on a single Windows
2000 machine. We used version 2.0.1 of the MQSeries Integrator product. To
validate the configuration, message flows and message sets are deployed in this
environment that were previously published as SupportPac IC03, MQSeries
Integrator - Business Scenarios. This SupportPac can be downloaded from:
http://www-4.ibm.com/software/ts/mqseries/txppacs/txpsumm.html
As for any IT solution, the environment changes. New versions of the product are
deployed for new applications.
This environment went through the following levels:
MQSeries Integrator V2.0.1
WebSphere MQ Integrator V2.1.
Not only did the environment used different product levels, it also changed
functionally:
Brokers were added on different Windows machines, creating multi-version
environments.
Brokers were added on multiple operating systems and database products.
Multiple Configuration Managers were created and had to be managed.
Existing Configuration Managers and brokers were upgraded to V2.1.
All the applications were consolidated in a single Configuration Manager
running at version 2.1.
The Windows 2000 machines used in this environment are referred to as NT1,
NT2, NT3, NT4, NT5 and NT6. The AIX machine is referred to as AIX1 and the
Sun Solaris machine is referred to as SUN1. The hardware and software
configurations of these machines are listed in Appendix A, Hardware/software
configuration on page 411.
Whenever the environment changes, we describe:

38
The reason for the change

The process used
Changes in the configuration
Problems encountered
Limitations noted
3.2 The original environment

We begin with one Configuration Manager and one broker. Both are running on
machine NT1 which is at the MQSeries Integrator V2.0.1 level. We are running
the Control Center on another NT machine.
The components defined on NT1 are:

Configuration Manager
Configuration Manager queue manager NT1_CM_QMGR
Broker NT1_BK1
Broker queue manager NT1_BK1_QMGR
The V2.0.1 Control Center is installed on NT5. User ID DEVUSER is defined for
use by the MQSeries Integrator developer. This user ID is defined on both the
Control Center machine and on the Configuration Manager machine. On NT1,
where the Configuration Manager is running, DEVUSER is made a member of
the mqbrdevt, mqbrasgn, and mqbrops groups for MQSeries Integrator and the
mqm group for MQSeries. In our scenario, there is only one developer; he is
responsible for creating flows and getting them deployed. The roles that are
defined by MQSeries Integrator can be distributed among your staff as desired
by your organization. These roles correspond to the groups:
mqbrkrs: group of user IDs used by brokers and the Configuration Manager
mqbrasgn: message set and message flow assigners
mqbrdevt: message set and message flow developers
mqbrops: operational controllers
mqbrtpic: publish/subscribe topic security administrator
These roles are documented in the manual MQSeries Integrator Using the
Control Center, SC34-5602 and MQSeries Integrator Administration Guide,
SC34-5602.
The service user ID on NT1, used to run the Configuration Manager, is NT1CM.
This user ID is a member of the mqm group for MQSeries and a member of the
mqbrkrs group for MQSeries Integrator. This user ID is also a member of the
Administrators group, as this is required to allow the Configuration Manager
service complete access to the registry. This is required on Windows 2000
machines because of changes to the access rules for the registry. Alternatively,
the registry permissions can be modified to allow the user IDs of the
Configuration Manager, the broker and the User Name Server required access.
You can use the Windows utility regedt32 to alter the security settings on keys in
the registry.
Chapter 3. Migration of an MQSeries Integrator environment
39
The service user ID on NT1, used to run the broker, is NT1BK1. This user ID is a
member of the mqm group for MQSeries and a member of the mqbrkrs group for
MQSeries Integrator. This user ID is also a member of the Administrators group,
for the same reason as described for user ID NT1CM.
Graphically, the environment is shown in Figure 3-1.
DEVUSER
NT1BK1
Broker NT1_BK1
NT1_BK1_QMGR
Control Center
NT1CM
NT1_CM_QMGR
NT1 Machine
NT5 Machine
Legend:
Figure 3-1 Overview of the original MQSeries Integrator environment
In addition to the required software for MQSeries and DB2, we also installed
SupportPac MA88, MQSeries classes for Java on NT5. Java is used by the
Control Center on NT5 to connect to the Configuration Manager on NT1. This
SupportPac is required when using MQSeries V5.2. with a V2.0.1 Control
Center.
On NT1, we have an MQSeries queue manager for the Configuration Manager
(NT1_CM_QMGR) and a second queue manager for the broker NT1_BK1
(NT1_BK1_QMGR). It is not necessary to create two separate queue managers
when running just one broker and a Configuration Manager on one machine. The
Configuration Manager can share a queue manager with one broker. The queue
managers were defined using MQSeries Explorer prior to creating the
Configuration Manager and broker.
Sender and receiver channels are defined between the two queue managers on
NT1.
40
The message flows used to validate this environment are the retail flows,
provided with the MQSeries Integrator - Business Scenarios SupportPac IC03.
The message flows were constructed to run on NT1, but were modified and
deployed to broker NT1_BK1 on NT1 using the remote Control Center on NT5.
These message flows illustrate the following features:
Publish/Subscribe
Warehousing and writing to databases
Subflows
Controlling the flow of a message using FlowOrder and Filter nodes
Manipulating the content of a message or message header using Compute
and Extract nodes
Data conversion
Tracing message flow activity
The SupportPac includes files that support two versions of this scenario:
1. A message flow that uses a message set and a message defined using the
Message Repository Manager (MRM). The MRM is a component of the
Configuration Manager that manages message definitions and maintains the
message repository in which they are stored. You use the Control Center to
define messages to the MRM.
2. A message flow that uses a self-defining XML message.
The two versions illustrate the use of different nodes to handle the different
messages.
To connect to the Configuration Manager from the Control Center (Figure 3-2):
1. Click File -> Connection.
2. Enter the Host Name of the computer where the Configuration Manager
resides.
3. Enter the listener Port for the Configuration Manager Queue Manager.
4. Enter the Queue Manager Name for the Configuration Manager.
41
Figure 3-2 Connecting to Configuration Manager
5. Once connected to the Configuration Manager, click the Topology tab in the
Control Center.
6. Right-click the Topology document in the left pane and select Check Out.
7. Right-click the Topology document again and select Create -> Broker. A
new window comes up (Figure 3-3), in which you need to specify the name of
the broker and the name of the queue manager that is hosting the broker.
Click Finish to complete this step.
8. Right-click the Topology document again and select Check In to store the
changes in the database of the Configuration Manager.
9. Right-click the Topology document once more and select Deploy ->
Complete Topology Configuration.
42
Figure 3-3 Add broker NT1_BK1 to topology
10.The main message flow of the retail scenario is shown in Figure 3-4. To
assign this message flow and the corresponding message set, select the
Assignments tab in the Control Center.
11.In the left pane, expand the folder representing the broker NT1_BK1 and
check out the broker and the default execution group.
12.Drag the message set from the middle pane to the broker.
13.Drag the message flow from the middle pane to the execution group. The
boxes in the right pane should now display the assigned message set and
message flow.
14.Check in the execution group and the broker and deploy the topology.
43
Figure 3-4 Main message flow
For more information about the message flow and the message sets and how to
use them, refer to the documentation that is part of the SupportPac.
3.3 Adding a new broker

It may be determined that an additional broker is required and that the new
broker should run on a separate machine. The reasons for this requirement could
be many, including the need to separate some business units work load from
others. Also, an additional broker could be needed for performance or availability
reasons.
Another machine NT2 is added to the configuration. MQSeries Integrator V2.0.2
is installed together with DB2 V6.1 and MQSeries V5.2.1. This release of
MQSeries Integrator is installed because it is now the latest version. The product
installation of MQSeries Integrator in not covered here, since this is not an
44
upgrade and the installation procedures are documented in the MQSeries

Integrator Installation Guide for Windows NT, GC34-5600. The configuration of
this machine can be found in Appendix A, Hardware/software configuration on
page 411.
Schematically, the new environment is shown in Figure 3-5.
DEVUSER
NT1BK1
Broker NT1_BK1
NT1_BK1_QMGR
Control Center
NT1CM
NT1_CM_QMGR
NT5 Machine
NT1 Machine
Legends:
NT2BK1
Broker NT2_BK2
NT2_BK2_QMGR
NT2 Machine
Figure 3-5 MQSeries Integrator environment extended with another broker
On machine NT2, queue manager NT2_BK2_QMGR is created for the broker

NT2_BK2. The queue manager was defined with MQSeries Explorer prior to
creating the Configuration Manager and broker. This is preferable since this
method creates and starts all required components (command server, channel
initiator, channel listener, etc.), while MQSeries Integrator will not create all
components when it is allowed to create the queue managers.
To create the queue manager using the MQSeries Explorer:
1. Start the program by clicking Start -> Programs -> IBM MQSeries ->
MQSeries Explorer.
2. Right-click the Queue Managers folder
45
3. Click New -> queue manager.

4. Enter the Queue Manager name: NT2_BK2_QMGR
5. Enter the name of the Dead Letter Queue: SYSTEM.DEAD.LETTER.QUEUE.
6. Click Next.
7. Enter the parameters for logging for the queue manager. It is recommended
that larger log files and more log files, both primary and secondary, be used
than in the default. Messages transported between the Configuration
Manager and the broker are XML messages and can be large. This is
especially true in the case of a full deploy to a broker with many flows in
several execution groups.
8. Enter the log file sizes: 2048.
9. Enter the number of primary log files to use: 5
10.Enter the number of secondary log files to use: 3
You might want to use more depending on your activity.
11.Click Next.
12.Select the Start queue manager and Create Server Connection Channel
boxes.
13.Click Next.
14.Click Create listener configured for TCP/IP.
15.Enter the port number for your queue manager to use. Remember to use a
unique port number for the machine running the queue manager.
16.Click Finish.
It is important to note that MQSeries uses port 1414 as a default. It is very likely
that you will have more than one queue manager per machine. Therefore, it is
recommended that you work with the network administrators to establish a
standard for MQSeries port numbers and have these port numbers reserved in
your environment. For example:
Port 41000 through 41099 for production queue managers
Port 41100 through 41199 for quality assurance queue managers
Port 41200 through 41299 for test queue managers
User ID NT2BK2 was created to be used as the service user ID for the broker
NT2_BK2. This user ID was made a member of the mqm MQSeries group and
the mqbrkrs group for MQSeries Integrator. This user ID was also made a
member of the Administrators group as this is required on Windows 2000 to
allow the broker service process complete access to the registry. Alternatively,
you could change the access rights for the MQSeries Integrator related registry
keys.
46
The database administrator created database MQSIBKDB on NT2 and has

registered this database for ODBC. The service user ID for the broker, NT2BK2,
is granted the following authorities to this database:

Connecting to the database

Creating tables
Creating packages
Registering functions to execute in database managers process
To grant these authorities:

1. Click Start -> Programs -> DB2 for Windows NT -> Control Center.
2. Enter the user ID and password to access the database.
3. Open the tree structure until you have opened the User and Group Objects
folder for the MQSIBKDB database.
4. Open the DB Users folder.
5. Right-click the DB Users folder and click Add.
6. Choose the user ID from the drop-down menu.
7. Select the appropriate checkboxes.
8. Click OK.
9. Now broker NT2_BK2 is created on NT2 using the Command Assistant for
MQSeries Integrator. Click Start -> Programs -> IBM MQSeries Integrator
-> Command Assistant -> Create Broker.
The window shown in Figure 3-6 will appear.
47
Figure 3-6 Create Broker using Command Assistant - Step 1
10.Fill out the appropriate values and click Next, which will bring you to the
window shown in Figure 3-7.
11.Provide the name of the database, MQSIBK02, and the user ID that was
granted the required authorities for this database.
12.Click Next again; this will bring you to the window shown in Figure 3-8.
Review the options and click Finish to start the creation process.
48
Figure 3-8
Create Broker using Command Assistant - Step 3
49
Alternatively, the command to create the broker can be entered in a command

window. It would be the same command as in Figure 3-8.
mqsicreatebroker NT2_BK2 -i NT2BK2 -a nt2bk2 -q NT2_BK2_QMGR -n MQSIBKDB
-u NT2BK2 -p nt2bk2
Prior to adding the new broker to the topology for the Configuration Manager, you
must make sure that the Configuration Manager can communicate with the
broker. To do that, the queue manager for the Configuration Manager and the
queue manager for the broker need to have a sender/receiver channel pair
defined. Along with the channels, transmission queues need to be defined. The
name of the transmission queue should be the same as the queue manager
name.
It is important to remember that MQSeries Integrator uses XML messages
between components. These XML messages can be extremely large, especially
when a full deploy is performed. Therefore, we have chosen to set the maximum
message length to the maximum allowed for the transmission queues, sender
channels and receiver channels. All three should be set to the same value
because MQSeries will choose the lowest common denominator when
determining the allowed message size.
1. Start MQSeries Explorer on the NT2 machine and expand the folder for
queue manager NT2_BK2_QMGR. Right-click the folder Queues and select
New -> Local Queue. You will see a window as shown in Figure 3-9.
2. Set the name of the queue to NT1_CM_QMGR, which is the name of the queue
manager that is used by the Configuration Manager. Make sure to select
Transmission as the value for the Usage field.
50
Figure 3-9 Create transmission queue from NT2_BK2_QMGR to NT1_CM_QMGR
3. Click the Extended tab in Figure 3-9 and you will see the window shown in
Figure 3-10. Increase the value for Maximum Message Length.
51

continued
4. Click the Triggering tab to automate the start-up of the channel from queue
manager NT2_BK2_QMGR to the queue manager used by the Configuration
Manager.
5. Figure 3-11 shows the values to set for channel triggering to work. Set Trigger
Control to On and Trigger Type to First. The value for Trigger Data is the
name of the sender channel that will be created starting with Figure 3-12. The
value of Initiation Queue Name is normally SYSTEM.CHANNEL.INITQ.
52

continued
6. The next step is to create a sender channel. From the MQSeries Explorer,
expand the folder NT2_BK2_QMGR and select Advanced -> Channels.
Right-click the Channels folder and select New -> Sender Channel. A
window will appear as shown in Figure 3-12.
53
Figure 3-12 Create sender channel from NT2_BK2_QMGR to NT1_CM_QMGR
7. The Channel Name field should contain the same name as was entered in the
field Trigger Data in Figure 3-11. The drop-down menu Transmission Queue
should list the transmission queue that was defined in Figure 3-9 on page 51
and onward. Choose the appropriate Transmission Protocol and provide the
correct Connection Name for the machine hosting the Configuration Manager.
8. Click the Extended tab (Figure 3-13) to change the value of Maximum
Message Length from its default value of 4194304 to the value that was also
set during the definition of the transmission queue (see Figure 3-11).
54
Figure 3-13 Create sender channel from NT2_BK2_QMGR to NT1_CM_QMGR

continued
9. The next step is the definition of a receiver channel on queue manager

NT2_BK2_QMGR. From the MQSeries Explorer, expand the folder
NT2_BK2_QMGR and select Advanced -> Channels. Right-click the
Channels folder and select New -> Receiver Channel. A window will appear
as shown in Figure 3-14.
55
Figure 3-14 Create receiver channel for NT2_BK2_QMGR
10.Provide a name for the receiver channel that is in line with established naming
conventions in your environment. Select the Extended tab to change the
value for the Maximum Message Length field (see Figure 3-15).
56
Figure 3-15 Create receiver channel for NT2_BK2_QMGR continued
11.Instead of using the MQSeries Explorer, you could also use the command line
based tool runmqsc. The definitions for the objects could be stored in a text
file: NT2_BK2_QMGR_objects.txt. Open a command prompt, change the
current directory to the directory where this file is stored and type:
runmqsc NT2_BK2_QMGR < NT2_BK2_QMGR_objects.txt > output.txt
The file NT2_BK2_QMGR_objects.txt should contain commands like those

shown in Example 3-1.
Example 3-1 MQSC commands on NT2_BK2_QMGR
DEFINE QLOCAL ('NT1_CM_QMGR') +
DESCR('xmitq to NT1 Config Manager') +
MAXMSGL(100000000) +
USAGE(XMITQ) +
TRIGGER +
57
TRIGTYPE(FIRST) +
TRIGDATA('TO.NT1_CM_QMGR') +
INITQ('SYSTEM.CHANNEL.INITQ')
DEFINE CHANNEL ('TO.NT1_CM_QMGR') CHLTYPE(SDR) +
TRPTYPE(TCP) +
MAXMSGL(100000000) +
XMITQ('NT1_CM_QMGR') +
CONNAME('m23bk64b(1414)')
DEFINE CHANNEL ('TO.NT2_BK2_QMGR') CHLTYPE(RCVR) +
TRPTYPE(TCP) +
MAXMSGL(100000000)
Similarly, on queue manager NT1_CM_QMGR, we need to create a sender

and receiver channel and a transmission queue to allow the Configuration
Manager to communicate with the broker on NT2. These definitions are
shown in Example 3-2.
Example 3-2 MQSC definitions on NT1_CM_QMGR
DEFINE QLOCAL ('NT2_BK2_QMGR') +
DESCR('xmitq to NT2 Broker NT2_BK2') +
MAXMSGL(100000000) +
USAGE(XMITQ) +
TRIGGER +
TRIGTYPE(FIRST) +
TRIGDATA('TO.NT2_BK2_QMGR') +
DEFINE CHANNEL ('TO.NT2_BK2_QMGR') CHLTYPE(SDR) +
TRPTYPE(TCP) +
MAXMSGL(100000000) +
XMITQ('NT1_BK2_QMGR') +
CONNAME('m23p4yh(1414)')
DEFINE CHANNEL ('TO.NT1_CM_QMGR') CHLTYPE(RCVR) +
TRPTYPE(TCP) +
MAXMSGL(100000000)
Prior to deploying to a V2.0.2 broker from a V2.0.1 Control Center and

Configuration Manager, the file MQSIV202_xx_properties needs to be copied
into the <mqsi_root>\Tool directory of each V2.0.1 Control Center machine.
This file is required for the Control Center to understand the messages that the
broker is sending back as a result of (for example) a deploy action. Note that
there are different language versions of this file, for example,
MQSIv202_en.properties or MQSIv202_ja.properties. This is documented in
MQSeries Integrator Administration Guide, SC34-5792.
58
Finally, we can add the V2.0.2 broker NT2_BK2 on NT2 to the topology of the
Configuration Manager (which is using V2.0.1 of the product). The Control
Center is used by user ID DEVUSER on machine NT5.
To connect to the Configuration Manager from the Control Center:
1. Click File -> Connection (Figure 3-16).
2. Enter the Host Name of the computer where the Configuration Manager
resides.
3. Enter the listener Port for the Configuration Manager Queue Manager
4. Enter the Queue Manager Name for the Configuration Manager
Figure 3-16 Connect to Configuration Manager
To define the broker to the topology,

1. Click the Topology tab.
2. Right-click the Topology folder in the left pane.
3. Click Check Out.
4. Right-click the Topology folder again in the left pane.
5. Click Create -> Broker.
6. Enter the Broker Name in the Name field: NT2_BK2.
59
7. Enter the name of the queue manager the broker uses on the machine it
resides, NT2_BK2_QMGR.
8. Click Finish.
9. Click File -> Check In -> All (Save to shared).
10.Right-click the Topology folder in the left pane.
11.Click Deploy -> Delta Topology Configuration.
12.Click the Log tab.
13.Click View -> Refresh, or the Refresh button in the tool bar.
14.Verify that the deploy was successful.
The retail flow from the Business Scenarios SupportPac is now deployed to the
V2.0.2 broker NT2_BK2 on NT2. This is accomplished using the V2.0.1 Control
Center on NT5.
The retail flow was tested on broker NT2_BK2 on NT2. The sample data
supplied by the SupportPac was used as input and the proper queues contained
data after the flow processed the data. The data was input to the queue using
mqsiput.exe from SupportPac IH02.
At this point we have:
A V2.0.1 Configuration Manager on NT1.
A V2.0.1 broker on NT1, NT1_BK1.
A V2.0.2 broker on NT2, NT2_BK2.
The retail flow from the Business Scenarios SupportPac, running in broker
NT1_BK1 on NT1, deployed from the V2.0.1 Configuration Manager on NT1,
using the V2.0.1 Control Center on NT5.
using the V2.0.1 Control Center on NT5.

3.4 Adding a new application

There is a requirement for a new MQSeries Integrator environment for a separate
set of message flows. It is determined that MQSeries Integrator V2.0.2 will be
used for the Configuration Manager and the new message flows. Two brokers are
required. One broker needs to be run on Windows and the second one needs to
be hosted on an AIX machine.
60
Since machine NT2 already has MQSeries Integrator V2.0.2 installed, we decide
to build the V2.0.2 Configuration Manager on NT2. At this point, we just need to
create the required components, since we performed a full install of MQSeries
Integrator V2.0.2 when we installed it for the broker NT2_BK2 that was used in
3.3, Adding a new broker on page 44. The new environment is shown in
Figure 3-17.
DEVUSER
NT1BK1
Broker NT1_BK1
NT1_BK1_QMGR
Control Center
NT1CM
NT1_CM_QMGR
NT1 Machine
NT2BK2
NT5 Machine
AIX1BK1
Broker NT2_BK2
NT2_BK2_QMGR
Broker AIX1_BK1
AIX1_BK1_QMGR
NT2BK1
Broker NT2_BK1
NT2_BK1_QMGR
NT2CM
AIX Machine
Broker NT2_BK2
NT2_CM_QMGR
Legends:
NT2 Machine
Figure 3-17 MQSeries Integrator environment with two Configuration Managers
On NT2, queue manager NT2_CM_QMGR is created for the V2.0.2

Configuration Manager and queue manager NT2_BK1_QMGR is created for the
new V2.0.2 broker. The queue managers were defined with MQSeries Explorer
prior to creating the Configuration Manager and broker. This is was done for the
reasons documented in 3.3, Adding a new broker on page 44.
61
To create the queue managers using the MQSeries Explorer:

1. Start the Explorer by clicking Start -> Programs -> IBM MQSeries ->
MQSeries Explorer.
2. Right-click the Queue Managers folder.
3. Click New -> queue manager.
4. Enter the queue manager name: NT2_BK1_QMGR and NT2_CM_QMGR,
respectively.
6. Click Next.
than suggested by the default. Messages transported between the
Configuration Manager and the broker are XML messages and can be
extremely large. This is especially true in the case of a full deploy to a broker
with many flows in several execution groups.
9. Enter the number of primary log files to use: 5.
10.Enter the number of secondary log files to use: 3.
11.Click Next.
12.Select the Start queue manager and Create Server Connection Channel
boxes.
13.Click Next.
Click Finish.
The service user ID used to run the V2.0.2 Configuration Manager on NT2 is
NT2CM. This user ID is made a member of the mqm group for MQSeries and a
member of the mqbrkrs group for MQSeries Integrator. This user ID was also
made a member of the Administrators group, since this is required to allow the
Configuration Manager service complete access to the registry. This is required
on Windows 2000 machines due to changes to the access rules for the registry.
Alternatively, the registry permissions can be modified to allow the user IDs of
the Configuration Manager and broker.
62
User ID NT2BK1 was created on NT2 to be used as the service user ID for
broker NT2_BK1. This user ID was made a member of the mqm MQSeries group
and the mqbrkrs group for MQSeries Integrator. This user ID was also made a
member of the Administrators group.
The database administrator created the MQSICMDB and MQSIMRDB
databases on NT2, as documented in the MQSeries Integrator Installation Guide.
The service user ID for the Configuration Manager, NT2CM, is granted the
following authorities to these databases:


Creating tables
Creating packages
Database MQSIBKDB already exists on NT2, but the service user ID for the new
broker, NT2BK2, has to be granted the following authorities to this database:


Creating tables
Creating packages

2. Enter the user ID and password to access the Database (V6 of DB2).
folder for the desired database.
6. Choose the user ID from the drop-down menu.
7. Select the appropriate check boxes.
8. Click OK.
9. Repeat these steps for all three databases.
Note that the two brokers on NT2 are using the same database on NT2.
The databases need to be registered for ODBC. To do this, use the DB2 Client
Configuration Assistant. The Assistant will show the newly created databases.
Select it and click Properties. In the next window, select Register this
database for ODBC and click OK.
63
The V2.0.2 Configuration Manager is created on NT2 using the Command

Assistant for MQSeries Integrator. We logged onto NT2 with a user ID in the
Administrators group to perform the create. Any user ID in the Administrators
group can be used, but it is recommended that the user ID of the service be
used, NT2CM in our case. This will help determine if there are any missing or
invalid security definitions for the service user ID before attempting to start and
use the Configuration Manager.
1. To define the Configuration Manager, click Start -> Programs -> IBM
MQSeries Integrator -> Command Assistant -> Create Configuration
Manager.
2. The window shown in Figure 3-18 will come up. Enter the name and
password of the service user ID NT2CM and enter the name of the queue
manager that was created previously. Click Next..
Figure 3-18 Create Configuration Manager using Command Assistant - Step 1
3. In the next window (see Figure 3-19), enter the name of the configuration
database (MQSICMDB) and the name of the message repository (MQSIMRDB).
Since we have given the service user ID the proper database access rights,
there is no need to mention them again. For clarity, we have entered them
anyway.
64
4. Click Next again and a new window (Figure 3-20) will be shown that contains
all parameters that were entered in the steps illustrated in Figure 3-18 and
Figure 3-19.
65
5. Click Finish to start the creation process for the new Configuration Manager.
Now broker NT2_BK1 is created on NT2 using the Command Assistant for
MQSeries Integrator. Again, the requirement is to be in the Administrators group,
but it is recommended that the user ID of the service be used, NT2BK1 in our
case.
1. Click Start -> Programs -> IBM MQSeries Integrator -> Command
Assistant -> Create Broker.
2. You will see a window like the one shown in Figure 3-6 on page 48 and
onward. Alternatively, you can execute the mqsicreatebroker command in a
command window, as shown in Example 3-3.
Example 3-3 mqsicreatebroker command for broker NT2_BK1
mqsicreatebroker NT2_BK1 -i NT2BK1 -a ******** -q NT2_BK1_QMGR -n MQSIBKDB -u
NT2BK1 -p ********
66
MQSeries Integrator V2.0.2 is installed on AIX1. Only the broker components are
installed. MQSeries and DB2 are already installed. The installation of MQSeries
Integrator is not documented here, as it is not an upgrade and the installation
procedures are documented in the MQSeries Integrator for AIX Installation
Guide, GC34-5841. The installations of MQSeries and DB2 are not documented
here either. Each product has an installation guide that describes the installation
procedures.
The user ID aix1bk1 is created to be used as the service user ID for broker
AIX1_BK1. This user ID must be a member of the mqbrkrs group for MQSeries
Integrator and the mqm group for MQSeries. This is accomplished on AIX using
smit or smitty, the interfaces provided by the AIX operating system to allow
maintenance and administration. The mqm group was created before MQSeries
was installed and the mqbrkrs group was created before MQSeries Integrator
was installed.
Figure 3-21 Creation of AIX Broker user ID aix1bk1
67
The database administrator created the MQSIBKDB database on AIX1, as

documented in the MQSeries Integrator for AIX Installation Guide, GC34-5841.
The service user ID for the broker, aix1bk1, is granted the following authorities to
this database:


Creating tables
Creating packages
MQSeries Integrator uses the database quite extensively. It is required that a

change be made to the heap stack size for DB2 to provide for the MQSeries
Integrator requirements.
This is accomplished by:
1. Signing on as the database instance owner (db2inst1 for example)
2. Entering DB2 CONNECT TO DATABASE MQSIBKDB
3. Entering DB2 update database configuration for mqsibkdb using dbheap
900
This command will return the following messages:
DB2000I The SQL command completed successfully.
DB21026I For most configuration parameters, all applications must disconnect
from this database before the changes become effective.
A broker uses the ODBC interface to access its database. To configure ODBC,
we need a file .odbc.ini. The broker will find the location of this file by referring to
the environment variable ODBCINI. This environment variable will be part of the
profile for the broker user ID aix1bk1.
The .odbc.ini file is updated as show in Example 3-4. A line, starting with
MQSIBKDB, is added to the section [ODBC Data Sources]. A new section
[MQSIBKDB] is added to link the ODBC name to the DB2 alias and to refer to the
correct driver to load.
Example 3-4 ODBC configuration for the broker on AIX
[ODBC Data Sources]
MQSIBKDB=IBM DB2 ODBC Driver
MYDB=IBM DB2 ODBC Driver
[MQSIBKDB]
Driver=/u/db2inst1/sqllib/lib/db2.o
Description=MQSIBKDB DB2 ODBC Database
Database=MQSIBKDB
[MYDB]
68
Driver=/u/db2inst1/sqllib/lib/db2.o
Description=MYDB DB2 ODBC Database
Database=MYDB
[ODBC]
Trace=0
TraceFile=/var/mqsi/odbc/odbctrace.out
TraceDll=/usr/opt/mqsi/merant/lib/odbctrac.so
InstallDir=/usr/opt/mqsi/merant
The user ID used to create the broker is aix1bk1 and must be a member of the
mqbrkrs group for MQSeries Integrator and the mqm group for MQSeries. The
.profile file for user ID aix1bk1 is modified to set all required environment
variables and all path entries for:
DB2
The correct DB2 database instance
MQSeries Integrator
A sample profile (profile.aix) is available in the samples directory of the product

installation (/usr/opt/mqsi/sample/profiles). This file should be used as the basis
for the actual .profile file of the user ID that will be used for the broker.
You need to make sure that the db2profile command is executed as part of the
.profile, as shown in Example 3-5.
Example 3-5 Profile settings for user ID aix1bk1
PATH=/usr/bin:/etc:/usr/sbin:/usr/ucb:$HOME/bin:/usr/bin/X11:/sbin:.
export PATH
if [ -s "$MAIL" ]
then echo "$MAILMSG"
fi
# This is at Shell startup. In normal

# operation, the Shell checks
# periodically.
# The following will setup the NLS environment

NLSPATH=/usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/en_US/%N:$NLSPATH
export NLSPATH
# Set ODBCINI to pick up the ODBC ini file
ODBCINI=/var/mqsi/odbc/.odbc.ini
export ODBCINI
CLASSPATH=/usr/jdk_base/lib/classes.zip:$CLASSPATH
export CLASSPATH
LIBPATH=$LIBPATH:/usr/opt/mqsi/merant/lib
. /home/db2inst1/sqllib/db2profile
69
# The following are required to use the NEON support within MQSI V2.0.2
NEON_ROOT=/usr/lpp/neonsoft
export NEON_ROOT
NEON_CATALOGUES=$NEON_ROOT/NEONCatalogues
export NEON_CATALOGUES
ICU_DATA=$NEON_ROOT/share/icu16/data
export ICU_DATA
LIBPATH=$LIBPATH:$NEON_ROOT/bin
PATH=$PATH:$NEON_ROOT/bin
#
MQSI_REGISTRY=/var/mqsi
export MQSI_REGISTRY
export LIBPATH
export PATH
As on the Windows machines, the queue manager for the broker was created
manually. Most likely, an existing MQSeries environment is in place, including
procedures for the creation, configuration, and start-up of queue managers.
The queue manager is defined by executing:
crtmqm -u SYSTEM.DEAD.LETTER.QUEUE -lp 5 -ls 3 -lf 2048 AIX1_BK1_QMGR
The successful execution of this command returns the following text:

MQSeries queue manager created.
Creating or replacing default objects for AIX1_BK1_QMGR.
Default objects statistics : 29 created. 0 replaced. 0 failed.
Completing setup.
Setup completed.
Now the queue manager is started by entering: strmqm AIX1_BK1_QMGR

To create the MQSeries components to support the communication of the
Configuration Manager with the broker, follow these steps:
1. Enter runmqsc AIX1_BK1_QMGR
2. To create the XMITQ, enter :
define qlocal(NT2_CM_QMGR) usage(xmitq) maxmsgl(100000000) trigger
trigtype(first) trigdata(TO.NT2_CM_QMGR)
70
3. To create the receiver channel, enter :

define channel(TO.AIX1_BK1_QMGR) chltype(rcvr) maxmsgl(100000000)
4. To create the sender channel , enter :

define channel(TO.NT2_CM_QMGR) chltype(sdr) trptype(tcp)
conname(m28p4yh(1414)) xmitq(NT2_CM_QMGR)
maxmsgl(100000000)
The sender channel from the NT2 Configuration Manager queue manager to this
broker is created on NT2. As always, the channel names must match. This
channel definition on NT2 can be done with either the command line, as we did
on AIX, or the MQSeries Explorer, as previously described.
For reasons of completeness, the definitions made for queue manager
NT2_CM_QMGR are listed in Example 3-6
DEFINE QLOCAL ('AIX1_BK1_QMGR') +
DESCR('xmitq to AIX1 Broker AIX1_BK1') +
MAXMSGL(100000000) +
USAGE(XMITQ) +
TRIGGER +
TRIGTYPE(FIRST) +
TRIGDATA('TO.AIX1_BK1_QMGR') +
DEFINE CHANNEL ('TO.AIX1_BK1_QMGR') CHLTYPE(SDR) +
TRPTYPE(TCP) +
MAXMSGL(100000000) +
CONNAME('rs617002(1415)')
TRPTYPE(TCP) +
MAXMSGL(100000000)
For both channels and the transmission queue, the maximum message length
has been set to the maximum value, that is 100 MB. The transmission queues
are defined to support channel triggering.
To support inbound MQSeries communication on the AIX machine, two system
files need to be updated.
71
The /etc/services contains a list of all network services. For each queue
manager, a line needs to be added. The following is added to the /etc/services
file for the queue manager AIX1_BK1_QMGR:
AIX1BK1
1415/tcp
#MQSeries listener for AIX1_BK1_QMGR
The value AIX1BK1 should be unique and is used to search in another file for the
corresponding program to start when an incoming communication request is
intercepted by the operating system. We keep all entries in port number
sequence. 1415 is the port number for our queue manager to receive
communications (listen). As discussed before, port numbers need to be unique
and the network administrator should be involved to avoid conflicts.
The file /etc/inetd.conf contains the name and path of the actual program to start
for an incoming request. For our situation, the following is added to the
/etc/inetd.conf file:
AIX1BK1 stream tcp nowait mqm /usr/mqm/bin/amqcrsta amqcrsta -m
AIX1_BK1_QMGR
After these files are modified, the inetd service must be refreshed for the
changes to be in effect. This refresh is accomplished by entering the following
command:
refresh -s inetd
The following message is returned:

The request for subsystem refresh was completed successfully.
The entries in this file define what is executed when a message is received on
the associated port number in the /etc/services file. The entries in these two files
are connected by the identifier entered first in both files. This is AIX1BK1 in our
files. So when services detect a communication on port 1415, program amqcrsta
is started with the supplied parameters.
At this point, it is recommended that the two sender channels be verified. This is
best accomplished by issuing a PING CHANNEL from either MQSeries Explorer or
from the runmqsc command service. Channel connection problems are best
detected and dealt with prior to attempting a deploy of MQSeries Integrator
objects.
At this time, we can execute the mqsicreatebroker command. Note that there is
no command assistant available on AIX. The command needs to be executed by
the user ID aix1bk1 for which all the required configuration steps have been
performed. The parameters and the actual execution are shown in Figure 3-22.
72
Figure 3-22 Create Broker AIX1_BK1 on AIX
The Control Center on NT5 was used to interact with the Configuration Manager
on NT1. Both systems were using version 2.0.1 of the product. To manage the
new Configuration Manager running on NT2 with product code V2.0.2, we will
need to add a separate machine (NT4) for the user ID DEVUSER. The Control
Center has to be at the same level as the Configuration Manager. Managing a
multi-version broker environment is possible using a single version of the Control
Center, as shown in 3.3, Adding a new broker on page 44. Managing an
environment with multiple Configuration Managers at different software levels
can be more difficult for this reason.
Now the V2.0.2 broker, NT2_BK1 on NT2, and the V2.0.2 broker on AIX1 are
defined to the MQSeries Integrator V2.0.2 Configuration Manager on NT2. The
Control Center is started by clicking Start -> Programs -> IBM MQSeries
Integrator -> Control Center.
Then, to define the brokers to the topology,
3. Click Check Out.
73

7. Enter the name of the queue manager the Broker uses on the machine where
it resides: NT2_BK1_QMGR.
8. Click Finish.
10.Click Create -> Broker.
11.Enter the Broker Name in the Name field, AIX1_BK1.
12.Enter the name of the queue manager the Broker uses on the machine where
it resides: AIX1_BK1_QMGR.
13.Click Finish.
14.Click File -> Check In -> All (Save to shared).
The loan flow and message set from the Business Scenarios SupportPac are
used as a message flow and message set to validate the operation of the
extended MQSeries Integrator environment. The message flow and message set
are imported to the Configuration Manager on NT2.
The import of the message set for this flow is accomplished by importing a Cobol
copybook into the workspace. This process is covered very well in the
SupportPac IC03 documentation. The import of the flow to the workspace is also
very well detailed in the documentation.
The flow and message set are examined and confirmed to have been imported
correctly. Any other setup required for this scenario from the SupportPac is also
performed at this point. This includes all other database setup and MQSeries
component definitions.
74
Figure 3-23 The loan message flow
The flow is modified to use the proper database on NT2, as described in the
SupportPac documentation. We use db2admin for our schema identifier.
The loan flow and message set are now deployed to the V2.0.2 broker,
NT2_BK1, running on NT2 (see Figure 3-24). All other setup required for the
execution of these flows from the SupportPac is done prior to testing. This
includes the application database setup and initialization and the creation of the
required MQSeries objects. This is described in the SupportPac documentation.
75
Figure 3-24 Deployed message set and message flow for the loan application
This flow was tested using the sample input provided by the SupportPac. The
test was a success when data was propagated to the proper output queues after
the flows had processed the input data. The data was put to the flow input queue
using mqsiput.exe from SupportPac IH02 .
The loan flow and the message set are now deployed to the V2.0.2 Broker
AIX1_BK1 on AIX1. Any other setup required for these flows from the
SupportPac was performed prior to testing. This includes all other database
setup and MQSeries component definitions.
The flow is tested the same way on AIX1 that it is on NT2. The sample input data
provided by the SupportPac was used. The test was a success when data was
propagated to the proper output queues. Since the mqsiput.exe facility only
existed on NT, a remote queue definition was defined on an NT broker to route
the data to the proper queue on the AIX machine.
At this point we have :
A V2.0.1 Configuration Manager on NT1
A V2.0.1 broker on NT1: NT1_BK1
A V2.0.2 broker on NT2: NT2_BK2
using the V2.0.1 Control Center on NT5
using the V2.0.1 Control Center on NT5
A V2.0.2 Configuration Manager on NT2

76
A V2.0.2 Broker on NT2, NT2_BK1

A V2.0.2 Broker on AIX1, AIX1_BK1
The loan flow from the Business Scenarios SupportPac, running in Broker
NT2_BK1 on NT2 and Broker AIX1_BK1 on AIX1.
3.5 Adding a new broker using WebSphere MQ

Integrator V2.1
We determine that with the release of WebSphere MQ Integrator V2.1, the
migration to this release is to begin. The conversion to this release will be
achieved with small steps. As before, we decide to begin by using the broker
component only and then begin using the Configuration Manager for new flows.
The complete environment already has two Configuration Managers running at
different product levels.
WebSphere MQ Integrator V2.1 is installed following the procedures outlined in
the WebSphere MQ Integrator for Windows NT and Windows 2000 Installation
Guide, GC34-5600. NT3 is used for this phase since MQSeries V5.2.1 and DB2
V6.1 are already installed on NT3. A full product install is performed. Only the
broker component is used at this time.
Prior to the installation, the readme files were reviewed. We found several things
that we needed to be aware of. It is strongly recommended that you always
review the readme files shipped with the product. They contain the most
up-to-date information available about the product, its installation and any known
problems and their work-arounds. The latest version of the readme can be
consulted on the Web at:
http://www-3.ibm.com/software/ts/mqseries/support/readme/all21_read.htm
l
Some of what we found of note in the readme is listed below:

Message sets cannot be deployed from a V2.0.2 Configuration Manager to a
V2.1 broker without first applying some fixes available on the Web. We
downloaded fix IC32427 for V2.0.2 from the following Web site:
ftp://ftp.software.ibm.com/software/mqseries/fixes/wmqiv21/IC32427/
The V2.1.0 product must be upgraded to fixpack level U200167, which can be
downloaded from:
ftp://ftp.software.ibm.com/software/mqseries/fixes/wmqiv21/winnt/
Message sets cannot be deployed from a V2.1 Configuration Manager to a
V2.0.2 broker without first applying the above fixes available on the Web.
77
Message sets that contain XML messages with an MRM message domain
are not supported when deploying from a V2.0.2 Configuration Manager to a
V2.1 broker, even after applying the fixes.
Message sets that contain XML messages with an MRM message domain
are not supported when deploying from a V2.1 Configuration Manager to a
V2.0.1 broker, even after applying the fixes.
On NT3, a queue manager NT3_BK2_QMGR is created on NT3 for the V2.1

broker NT3_BK2. The queue manager is defined with MQSeries Explorer prior to
creating the broker. This is preferable since this method creates and starts all
required components (command server, channel initiator, channel listener, etc.),
while WebSphere MQ Integrator will not create all components when it is
allowed to create the queue managers. The mqsicreatebroker command has
been enhanced to create the queue manager using the
SYSTEM.DEAD.LETTER.QUEUE as the dead letter queue. While this is an
improvement, the channel initiator is still not started and the channel listener is
not defined or started.
To create the queue managers using the MQSeries Explorer:
1. Start the Explorer by clicking Start -> Programs -> IBM MQSeries ->
MQSeries Explorer.
2. Right-click the Queue Managers folder.
3. Click New -> Queue Manager.
4. Enter the queue manager name: NT3_BK2_QMGR.
6. Click Next.
than suggested in the default. Messages transported between the
Configuration Manager and the broker are XML messages and can be
extremely large. This is especially true in the case of a full deploy to a broker
with many flows in several execution groups.
9. Enter the number of primary log files to use: 5.
10.Enter the number of secondary log files to use: 3.
11. Click Next.
12.Select the Start Queue Manager and Create Server Connection Channel
boxes.
78
13.Click Next.
16.Click Finish.
User ID NT3BK2 is created on NT3 to be used as the service user ID for the
broker NT3_BK2. This user ID is made a member of the mqm MQSeries group
and the mqbrkrs group for MQSeries Integrator. This user ID was also made a
member of the Administrators group as this is required to enable the broker
service complete access to the registry.
The database administrator created the MQSIBKDB database on NT3. The
service user ID for the broker, NT3BK2, is granted the following authorities to this
database:


Creating tables
Creating packages

2. Enter the user ID and password to access the Database (V6 of DB2).
folder for the desired database (MQSIBKDB).
6. Choose the user ID from the drop-down menu (NT3BK2).
7. Select the appropriate checkboxes.
8. Click OK.
The broker NT3_BK2 is created on NT3 using the Command Assistant for
MQSeries Integrator. We logged onto NT3 with a user ID NT3BK2, which is in
the Administrators group, to perform the create. Any user ID in the Administrators
group can be used, but it is recommended that the user ID of the service be
used, NT3BK2 in our case. This will help determine if there is any missing or
invalid security definitions for the service user ID before attempting to start and
use the broker.
79
1. To define the broker, click Start -> Programs -> IBM WebSphere MQ
Integrator -> Command Assistant -> Create Broker.
2. Enter the Broker Name, Service User ID, Service Password and the Queue
Manager Name. Click Next.
80
3. Enter the Broker ODBC Data Source Name, User ID to access Database
(should be the broker service user ID) and the Broker Data Source Password.
Click Next.
81
4. The actual mqsicreatebroker command that will be issued is now displayed.

Click Finish.
Alternatively, the command to create the Broker can be entered in a command
window. It would be the same command as in Figure 3-27.
mqsicreatebroker NT3_BK2 -i NT3BK2 -a nt3bk3 -q NT3_BK2_QMGR -n
MQSIBKDB -u NT3BK2 -p nt3bk3
broker. To do that, a sender/receiver channel pair is defined to the queue
manager for the Configuration Manager and the queue manager for the broker.
Along with the channels, the transmission queues are also defined. The name of
the transmission queue is the same as the name of the target queue manager.
82
It is important to remember that WebSphere MQ Integrator uses XML messages

between components. These XML messages can be extremely large, especially
when a full deploy is performed. Therefore, we have chosen to set the maximum
message length to the maximum allowed for the transmission queues, sender
channels and receiver channels. All three should be set to the same value
because MQSeries will choose the lowest common denominator when
determining the allowed maximum message size.
MQSC commands to connect the broker queue manager to the queue manager
hosting the Configuration Manager are given in Example 3-7.
Example 3-7 MQSC commands for queue manager NT3_BK2_QMGR
MAXMSGL(100000000) +
USAGE(XMITQ) +
TRIGGER +
TRIGTYPE(FIRST) +
TRPTYPE(TCP) +
MAXMSGL(100000000) +
CONNAME('m28p4yh(1414)')
TRPTYPE(TCP) +
MAXMSGL(100000000)
MQSC commands to connect the queue manager hosting the Configuration

Manager to the broker queue manager are given in Example 3-8.
Example 3-8 MQSC commands for queue manager NT2_CM_QMGR
DESCR('xmitq to NT3 Broker') +
MAXMSGL(100000000) +
USAGE(XMITQ) +
TRIGGER +
TRIGTYPE(FIRST) +
83
TRPTYPE(TCP) +
MAXMSGL(100000000) +
CONNAME('m23cabxk(1416)')
TRPTYPE(TCP) +
MAXMSGL(100000000)
The V2.1 broker, NT3_BK2 on NT3, is then defined to the MQSeries Integrator
V2.0.2 Configuration Manager on NT2. This is accomplished by logging onto the
NT4 Control Center as DEVUSER. The Control Center is started by clicking
Start -> Programs -> IBM WebSphere MQ Integrator -> Control Center.
Connect to the Configuration Manager by clicking Connect.
Figure 3-28 Connecting Control Center to Configuration Manager
To define the V2.1 broker to the V2.0.2 Configuration Manager topology, follow
these steps
3. Click Check Out.
7. Enter the name of the queue manager the Broker uses on the machine it
resides: NT3_BK2_QMGR.
8. Click Finish.
84

The loan flow and message set were then deployed from the V2.0.2
Configuration Manager on NT2 to the V2.1 broker NT3_BK2 on NT3. Any other
setup required for the execution of these flows from the SupportPac is performed
prior to testing. This includes the application database setup and initialization
and the creation of the required MQSeries object. This is described in the
SupportPac documentation.
To deploy the flow and message set:
1. Click the Assignments tab.
2. Check out the Broker.
3. Check out the Execution Group.
4. Expand the Message Sets folder in the Assignable Resources pane.
5. Expand the Message Flows folder in the Assignable Resources pane.
6. Drag the desired message set from the Assignable Resources pane to the
appropriate Broker in the Domain Topology pane.
7. Drag the desired message flow from the Assignable Resources pane to the
appropriate Execution Group in the Appropriate Broker.
9. Right-click the Broker in the Domain Hierarchy pane.
10.Click Deploy -> Delta Assignments Configuration.
11.A message box will display stating the deployment has been initiated. Click
OK.
13.Click the Refresh button on the menu bar.
85
Figure 3-29 Prepared to deploy
According to the readme file, fixes must be applied before deploying across a
multiple version environment. If the fixes are not applied, the deploy will fail. The
messages that appear are shown below.
86
Figure 3-30 Deploy failed
Figure 3-30 shows the message that is indicative of the problem. The following
two messages are standard messages that occur when these types of problems
are encountered.
In this case, the broker was running without any fixes applied. The Configuration
Manager was not using the fix IC32427.
Figure 3-31 and Figure 3-32 show the text associated with the two other error
messages.
87
Figure 3-31 Deploy failed - continued
88
Figure 3-32 Deploy failed - continued
After upgrading the V2.1 product on machine NT3, the deploy still fails. The
errors (messages BIP5145 and BIP5347) are shown in Figure 3-33 and
Figure 3-34.
After applying the fix IC32427 on machine NT2, the deploy was successful
(messages BIP4040 and BIP2056 in Figure 3-34).
89
Figure 3-33 Messages during deploy with and without fix IC32427
90
Figure 3-34 Messages during deploy with and without fix IC32427
The flow is tested the same way on NT3 as it was on NT2. The sample input data
provided by the SupportPac was used and mqsiput.exe was used to put the data
to the input queue. The test was a success when data was propagated to the
proper output queues.
The resulting environment is shown in Figure 3-35.
91
DEVUSER
NT1BK1
Broker NT1_BK1
NT1_BK1_QMGR
Control Center
NT5 M achine
NT1CM
DEVUSER
NT1_CM_QMGR
Control Center
NT1 M achine
NT4 M achine
NT2BK2
AIX1BK1
Broker NT2_BK2
NT2_BK2_QMGR
Broker AIX1_BK1
AIX1_BK1_QMGR
NT2BK1
Broker NT2_BK1
NT2_BK1_QMGR
AIX1 Machine
NT3BK2
NT2CM
Broker NT3_BK2
NT3_BK2_QMGR
NT2_CM_QMGR
NT3 M achine
NT2 M achine
Legends:
WebSphere MQ Integrator V2.1.0
Figure 3-35 WebSphere MQ Integrator environment with three different product versions
3.6 Introducing a V2.1 Configuration Manager

Now that a version 2.1 broker is active, the next step in the migration is planned.
A new Configuration Manager using version 2.1 of the product is needed. The
ultimate goal is also to have a single Configuration Manager for the whole
environment. As can be seen in Figure 3-35, currently there are already two
Configuration Managers, which also means that developers and administrators
have to use two different versions of the Control Center to be able to work with
the Configuration Managers.
92
The new version 2.1 Configuration Manager will be used first for a new set of
message flows. These flows will be hosted on a new broker.
Once this new Configuration Manager is in place, we would like to consolidate all
Configuration Managers. There are two approaches to this. First, we could create
a new broker on NT1 and NT2 and connect these brokers to the new
Configuration Manager. This means that the Configuration Manager would be
used to manage brokers at three different levels of the product:
A version 2.0.1 broker on NT1
A version 2.0.2 broker on NT2
A version 2.0.2 broker on AIX1
A version 2.1.0 broker on NT3, the same machine that is used for the
A second approach is to first upgrade the product and the components on NT1
and NT2. This would result in three Configuration Managers on NT1, NT2, and
NT3. However, all would use the same level of the product. At the same time, all
the brokers would be upgraded as well. At that time, a new broker would be
defined on all machines to connect to the Configuration Manager on NT3. The
existing brokers would then no longer be needed and could be deleted, including
the Configuration Managers on the machines NT1 and NT2.
The first approach has several limitations. Fixes need to be installed to allow the
coexistence of a version 2.0.1 broker, a version 2.0.2 broker and a version 2.1.0
Configuration Manager. Even when the fixes are applied, there is always a risk
that developers will use new features of the product that are not available on the
brokers. An example of this approach is provided in 3.7, Using a V2.0.2 broker
with a V2.1.0 Configuration Manager on page 105.
The second approach will be started in the remainder of this section. A new
Configuration Manager and broker are defined on NT3. Section 3.8, Product
upgrade on AIX1, NT1 and NT2 on page 108 describes the upgrade of
machines NT1, NT2 and AIX1. Finally, Section 3.9, Consolidating Configuration
Managers on page 128 describes the consolidation to a single Configuration
Manager.
NT3 has WebSphere MQ Integrator V2.1 already installed, since it was used to
create broker NT3_BK2 that was connected to a version 2.0.2 Configuration
Manager (see 3.5, Adding a new broker using WebSphere MQ Integrator V2.1
on page 77). Since we did a full install of the product, we simply need to create
the required components: databases and the Configuration Manager itself.
As with the procedures that were used previously, we create a queue manager
NT3_CM_QMGR and a queue manager NT3_BK1_QMGR on machine NT3.
93
The service user ID used to run the Configuration Manager on NT3 is NT3CM.
This user ID is made a member of the mqm group for MQSeries and a member of
the mqbrkrs group for MQSeries Integrator. This user ID is also made a member
of the Administrators group, since this is required to allow the Configuration
Manager service complete access to the registry.
User ID NT3BK1 is created on NT3 to be used as the service user ID for broker
NT3_BK1. This user ID is made a member of the mqm MQSeries group and the
mqbrkrs group for MQSeries Integrator. This user ID is also made a member of
the Administrators group, since this is required to allow the broker service
complete access to the registry.
Machine NT6 is used to host an additional Control Center, to be used by the user
ID DEVUSER.
Legends:
NT3BK2

Broker NT3_BK2
NT3_BK2_QMGR
DEVUSER
NT3BK1
Broker NT3_BK1
NT3_BK1_QMGR
Control Center
NT3CM
NT3_CM_QMGR
NT3 machine
NT6 machine
Figure 3-36 Initial deployment of a new Configuration Manager
The database administrator created the MQSICMDB and MQSIMRDB

databases on NT3, as documented in the WebSphere MQ Integrator Installation
Guide. The service user ID for the Configuration Manager, NT3CM, is granted
the following authorities to these databases:

94

Creating tables
Creating packages
Database MQSIBKDB already exists on NT3, but the service user ID for the new
broker, NT3BK1, has to be granted the following authorities to these databases:


Creating tables
Creating packages
The V2.1 Configuration Manager is created on NT3 using the Command

Assistant for WebSphere MQ Integrator. We logged onto NT3 with the user ID
NT3CM to execute the mqsicreatebroker command. Any user ID in the
Administrators group can be used, but it is recommended that the user ID of the
service be used (NT3CM in our case). This will help determine if there is any
missing or invalid security definitions for the service user ID before attempting to
start and use the Configuration Manager.
1. To define the Configuration Manager, click Start -> Programs -> IBM
WebSphere MQ Integrator -> Command Assistant -> Create
Figure 3-37 Create Configuration Manager
95
2. Figure 3-37 shows the first window of the Command Assistant. Provide the
name of the queue manager (NT3_CM_QMGR) and the service user ID and
password.
Figure 3-38 Create Configuration Manager, continued
3. Figure 3-38 shows the second window of the Command Assistant where
database access parameters are provided. Figure 3-39 shows the complete
command. Select Finish to start the creation.
96
Figure 3-39 Create Configuration Manager, continued
Alternatively, the command to create the Configuration Manager can be entered

in a command window. It would be the same command as in Figure 3-39.
mqsicreateconfigmgr NT3_CM -i NT3CM -a nt3cm -q NT3_CM_QMGR -n
MQSICMDB -u NT3CM -p nt3cm -m MQSIMRDB -e NT3CM -r nt3cm
Now broker NT3_BK1 is created on NT3 using the Command Assistant for
WebSphere MQ Integrator. We logged on as user NT3BK1 to create the broker.
Again, the requirement is to be in the Administrators group, but it is
recommended that the user ID of the service be used, NT3BK1 in our case. Click
Start -> Programs -> IBM WebSphere MQ Integrator -> Command Assistant
-> Create Broker.
97
The interface of the Command Assistant to create a broker was shown previously
in 3.5, Adding a new broker using WebSphere MQ Integrator V2.1 on page 77.
Here, we will only show the final command.
mqsicreatebroker NT3_BK1 -i NT3BK1 -a nt3bk1 -q NT3_BK1_QMGR -n MQSIBKDB
-u NT3BK1 -p nt3bk1
broker. To do that, a sender/receiver channel pair is defined to the queue
manager for the Configuration Manager and the queue manager for the broker.
Along with the channels, transmission queues need to be defined.
Example 3-9 shows the definitions required on queue manager
NT3_BK1_QMGR to connect to the queue manager used by the Configuration
Manager.
Example 3-9 MQSC commands on NT3_BK1_QMGR
MAXMSGL(100000000) +
USAGE(XMITQ) +
TRIGGER +
TRIGTYPE(FIRST) +
TRPTYPE(TCP) +
MAXMSGL(100000000) +
TRPTYPE(TCP) +
MAXMSGL(100000000)
Similarly, on queue manager NT3_CM_QMGR, we need to create a sender and

receiver channel and a transmission queue to allow the Configuration Manager
to communicate with the broker on NT3. These definitions are shown in
Example 3-10.
DESCR('xmitq to NT3 Broker NT3_BK1') +
MAXMSGL(100000000) +
USAGE(XMITQ) +
98
TRIGGER +
TRIGTYPE(FIRST) +
TRPTYPE(TCP) +
MAXMSGL(100000000) +
TRPTYPE(TCP) +
MAXMSGL(100000000)
Now the V2.1 broker NT3_BK1 on NT3 is defined to the WebSphere MQ

Integrator V2.1 Configuration Manager on NT3. This is accomplished by logging
on to NT6 as DEVUSER. The Control Center is started by clicking Start ->
Programs -> IBM WebSphere MQ Integrator -> Control Center.
Then to define the brokers to the topology:
3. Click Check Out.
7. Enter the name of the queue manager the Broker uses on the machine it
resides: NT3_BK1_QMGR.
8. Click Finish.
99
The RouteToLabel flow and message set from the Business Scenarios
SupportPac are used as validation message flow and message set. The flow and
message set are imported to the V2.1 Configuration Manager on NT3.
Prior to importing the flow and message set, additional setup is required as
documented in the SupportPac documentation. MQSeries queues must be
defined. An application database must be created and tables created and
populated with data.
The message set for this flow is imported by:
1. Opening a command prompt window.
2. Stopping the Configuration Manager using the mqsistop configmgr
command.
3. Changing to the directory containing the RouteToLabel.mrp file.
4. Importing the message set by typing:
mqsiimpexpmsgset -i -u NT3CM -p nt3cm -n MQSIMRDB -f RouteToLabel.mrp
-x XML
where -u and -p are the user ID and password that are used for message
repository access, and -n specifies the name of the message repository (you
specified these parameters using the -n, -u, and -p flags on the
mqsicreateconfigmgr command).
5. Restart the Configuration Manager using the command mqsistart configmgr.
6. Restart the Control Center from the Start menu.
7. In the Control Center Message Sets view, right-click the Message Sets folder
and select Add to Workspace. Select the message set RouteToLabel, and
click Finish.
The -x XML in the mqsiimpexpmsgset command is a new feature with WebSphere
MQ Integrator V2.1. Multiple message types can now be defined for a given
message. The -x parameter is used to provide an identifier for the XML message
type. This parameter is required for our exercise due to the fact that our input
message is XML. The sample input data supplied by the SupportPac contains
the name XML for the message type. Therefore we use XML as our message
type identifier following the -x parameter.
The import of the flow to the workspace is accomplished as follows:
1. Select the Message Flows tab in the Control Center.
2. Import the dynamic routing message flow definition:
a. Select Import to Workspace... from the File menu.
100
b. Locate file RouteToLabel.xml that contains the message flow definition

(you can type in the full path and file name in the dialog or you can click
Browse and search for the file).
c. The Message Flows checkbox is selected by default. This will import only
message flows from the file you have identified as the source of the
resources to import.
d. Click Import.. The Control Center processes the file and imports the
message flows that are defined within it. The file RouteToLabel.xml
contains just one message flow, RouteToLabel. A list of resources that
have been imported is displayed in a dialog when the processing has
completed.
At this point, we received an error message indicating that the import
encountered a duplicate; this must be corrected. The problem is that the
SupportPac delivers the flow with the name RouteToLabel. This is also the name
of a product primitive node. This is no longer allowed.
To correct the problem, we decide to change all references to RouteToLabel to
RteToLbl. This includes the message set as well as the flow. The imported
message set name is changed to RteToLbl. The .xml file of the exported flow as
delivered by the SupportPac is edited. All references to RouteToLabel in this file
are changed to RteToLbl. The modified file is saved as ToLabel.xml. We now
import the modified flow from this file and get no errors.
After importing this modified .xml file, the new message flow appears in the
left-hand pane, with a blue cube beside it to show that it is new. Select the new
message flow. You can now configure the nodes within it before checking it into
the configuration repository. The connections to all RouteToLabel nodes are
broken when the import is completed. To correct this problem, each
RouteToLabel node was deleted and manually recreated using the instructions
for building the flow from scratch, included in the SupportPac documentation.
Select File -> Check In -> All (Save to Shared) to check in the message flow.
The flows and message set are now deployed to NT3_BK1.
101
Figure 3-40 Ready to deploy
To deploy the flow and message set:

1. Click the Assignments tab.
2. Check out the Broker.
3. Check out the Execution Group.
4. Expand the Message Sets folder in the Assignable Resources pane.
5. Expand the Message Flows folder in the Assignable Resources pane.
6. Drag the desired message set from the Assignable Resources pane to the
appropriate Broker in the Domain Topology pane.
7. Drag the desired message flow from the Assignable Resources pane to the
appropriate Execution Group in the Appropriate Broker.
9. Right-click the Broker in the Domain Hierarchy pane.
10.Click Deploy -> Delta Assignments Configuration. A message box will
display stating that the deployment has been initiated.
102
11.Click OK.
13.Click the Refresh button on the menu bar.
Figure 3-41 Deploy succesful
103
Figure 3-42 Operations tab view showing deployed message set and flow
This flow was tested using the sample input provided by the SupportPac. The
test was a success when data was propagated to the proper output queues after
the flows had processed the input data. The data was put to the flow input queue
using mqsiput.exe from SupportPac IH02 :
mqsiput LABELIN NT3_BK1_QMGR <trademsg.xml
104
Figure 3-43 Test is a success: data is in LABELOUT queue
3.7 Using a V2.0.2 broker with a V2.1.0 Configuration

Manager
As discussed in the beginning of 3.6, Introducing a V2.1 Configuration Manager
on page 92, one migration option is create a new version 2.0.2 broker on NT2
and connect it to the Configuration Manager that we have created on NT3. The
message flows and message sets need to be extracted from the version 2.0.2
Configuration Manager on NT2 and imported in the new version 2.1.0
Configuration Manager on NT3.
The advantage of this procedure is that you can keep the existing broker and
existing Configuration Manager on machine NT2. If the coexistence fails for
whatever reason, you can still continue to use the existing broker.
The steps include the following:
1. Broker NT2_BK3 is created on NT2. Refer to Example 3-3 on page 66 for an
example of the parameters of the mqsicreatebroker command.
2. Broker NT2_BK3 is defined to the V2.1 Configuration Manager on NT3.
3. Message flows are deployed to NT2_BK3.
105
This same technique could be used for the environment on AIX1 and NT1.
Figure 3-44 shows the broker domain using a V2.1 Configuration Manager next
to the broker domain using a V2.0.2 Configuration Manager.
NT2BK2
Broker NT2_BK2
NT2_BK2_QMGR
Legends:

NT2BK1
Broker NT2_BK1
NT2_BK1_QMGR
NT2CM
NT3BK2
NT2_CM_QMGR
Broker NT3_BK2
NT3_BK2_QMGR
NT3BK1
NT2BK3
Broker NT2_BK1
NT3_BK1_QMGR
Broker NT2_BK3
NT2_BK3_QMGR
NT3CM
NT2 Machine
NT3_CM_QMGR
DEVUSER
NT3 Machine
Control Center
NT6 Machine
Figure 3-44 Next step of migration and consolidation
According to the readme file, fixes must be applied before deploying across a
multiple version environment when MRM message sets are involved. At this
time, the fixes have not been applied and therefore the deploy fails. The
messages that appear are shown below.
106
Figure 3-45 Deploy failed
This is the message that is indicative of the problem. The following two
messages are standard messages that occur when these types of problems are
encountered.
We have several options to fix this problem.
We could apply the aforementioned fixes.
We could insure that we do not have a mixed release environment.
We could change the message flow to use generic XML instead of
MRM-defined XML. That means that all Compute and other nodes containing
ESQL that references message fields must change.
We created a flow, genericxml, that uses generic XML. This flow is deployed and
tested, and works.
After applying the fix IC32427 on the NT2 installation of MQSeries Integrator
V2.0.2, we see that the deploy of the original message flow works also. Using the
sample data provided with the SupportPac, the behavior of the message flow
was again validated.
107
3.8 Product upgrade on AIX1, NT1 and NT2

We now have three different releases of the MQSeries Integrator product in use.
We decide that it is time to stop supporting three separate releases. We now
begin to upgrade all installations on NT1, NT2 and AIX1 to the current V2.1
WebSphere MQ Integrator release.
Each installation is upgraded in place on the machine where it is currently
running. NT1 is upgraded from V2.01. to V2.1 and NT2 is upgraded from V2.0.2
to V2.1. Both NT1 and NT2 have a Configuration Manager and multiple brokers.
Each have an existing broker attached to the Configuration Manager at the same
release level on the same machine. They also both have one or more brokers
attached to a Configuration Manager at another release level and running on
another machine. The steps, challenges and lessons learned are documented
below.
Prior to performing the installation, the readme files were reviewed. We found
several things that we needed to be aware of. It is strongly recommended that
you always review the readme files shipped with the product. They contain the
most up-to-date information available about the product, its installation, as well
as any known problems and their work-arounds.
The first lesson we learn is that to upgrade the Configuration Managers, we
must:
1. Check in all checked-out message flow and message sets.
2. Export all message sets.
3. Delete the Configuration Manager without deleting the database tables.
4. Uninstall the currently installed version of MQSeries Integrator.
5. Install WebSphere MQ Integrator V2.1.
6. Drop the tables in MRM data repository MQSIMRDB.
7. Migrate the configuration repository database MQSICMDB.
8. Re-create the Configuration Manager.
9. Re-import the message sets.
The second lesson we learned was that if you want to move a broker from one
Configuration Manager to another, regardless of whether they are the same
release or not, you have to undeploy everything from the broker using the
Configuration Manager it is originally assigned to and then remove the broker
from that Configuration Managers topology. After deploying the deleted broker,
make sure you receive the message indicating that all references of that broker
has been removed, before you proceed. You then can define the broker to the
108
topology of another Configuration Manager. If you fail to perform these steps

exactly, you will have a problem with the old Configuration Manager. The
Configuration Manager will still think it owns the broker and it will show in the
Topology and Operations tabs of the Control Center. If you try to remove the
broker from the topology at this point, the Configuration Manager may try to
remove it and it may not succeed. Most likely you will get an error in the
database, a deploy will be attempted, but will fail. The broker will still show in the
Operations tab but not the Topology tab. Then, if you perform a full topology
deploy, the Configuration Manager will still try to deploy to the deleted broker.
Another lesson was that a delta topology deploy works when you add a broker to
the topology. But when you delete a broker from the topology, you must perform a
complete topology deploy, not a delta. A delta deploy at this point does not seem
to clean up all database entries on a delete. A full deploy does clean the
database properly.
3.8.1 Upgrade on AIX1

We decided to upgrade the AIX installation first and also move it to the V2.1
Configuration Manager on NT3. To upgrade on all UNIX platforms, the current
installed version must be uninstalled. When you uninstall the broker software, the
uninstall performs a delete of all brokers on the machine. When the broker is
deleted, the database tables are cleared. The tables are not deleted. Therefore,
you are not required to undeploy everything that is deployed to the brokers on the
AIX machine. It is still recommended that you do so. It is better that you know
what you have done than to constantly question what happened in case
something does not work.
Check out the topology document, delete the AIX broker, check in the topology
document and deploy the changes.
For a proof of concept, we deleted the AIX1_BK1 broker from the NT2_CM V2.02
topology, without undeploying all message sets and message flows, and
performed a topology deploy. To do this:
1. Click the Topology tab in the Control Center.
2. Right-click Topology.
3. Click Check Out.
4. Right-click the Broker in either window and click Delete.
5. Right-click Topology again.
6. Click Check in.
7. Right-click Topology again.
8. Click Deploy -> Complete Topology Configuration.
109
When checking the log, we received the message stating that the broker
successfully processed the configuration. However, we never received the
message saying that all references were deleted.
Regardless, we decided to proceed to see what would happen. We defined the
AIX1_BK1 broker to the Configuration Manager on NT3 (V2.1) topology.
When the deploy was executed, the following message were received:
Figure 3-46 Deployed failed
110
Figure 3-47 Deployed failed, continued
111
Figure 3-48 Deployed failed, continued
We decided to redefine the V2.0.2 broker AIX1_BK1 to the Configuration

Manager on the NT2 (V2.0.2) topology and delete all deployed message sets
and message flows, then delete the broker on AIX1. However, a major problem
occurred. We could not redeploy that broker to the Configuration Manager. The
UUIDs are created when the broker is defined to the topology on the Control
Center. When the topology is deployed, the broker is informed what UID belongs
to it. Therefore, when we redefined the broker to the Configuration Manager on
NT3, a new UUID was created. When the deploy was executed, the same
messages as above were displayed. Therefore, we decide to proceed and allow
the uninstall to delete everything for us. At this point, the broker is not defined to
any topology.
This uninstall of MQSeries Integrator V2.0.2. is accomplished using the smit or
smitty tool. Smit and smitty are system management tools supplied with AIX.
112
The steps are as follows:

1. Enter smit in a telnet session while logged on as root.
2. Select Software Installation and Maintenance.
3. Select Software Maintenance and Utilities.
4. Select Remove Installed Software.
5. Click List or press F4 to obtain a list of installed software.
6. Select all MQSeries Integrator Software Components (Figure 3-49).
113
Figure 3-49 Select MQSeries Integrator components to delete
7. Click OK.
8. Components are listed in the Software name field (Figure 3-50). Choose no
for Preview Only and for the other options.
114
Figure 3-50 Selected MQSeries Integrator components to delete
9. Click OK or press Enter.
Figure 3-51 MQSeries Integrator components are deleted
10.Successful completion is shown in Figure 3-51.

Before we began the process of removing the AIX1_BK1 broker from NT2_CM
Configuration Manager and uninstalling MQSeries Integrator V2.0.2 from the
AIX machine, we took a count of the number of records in each table in the
broker database. This is accomplished by logging on AIX as the DB2 instance
owner. Connect to the DB2 database, MQSIBKDB. Then run the following script:
115
Example 3-11 SQL statements to count records in MQSIBKDB tables

SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
COUNT(*)
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
FROM
AIX1BK1.BACLENTRIES
AIX1BK1.BCLIENTUSER
AIX1BK1.BGROUPNAME
AIX1BK1.BLOGICALTOPHYSNAME
AIX1BK1.BMQEPUBDEST
AIX1BK1.BMQEPUBMSGIN
AIX1BK1.BMQEPUBMSGOUT
AIX1BK1.BMQESTDMSGIN
AIX1BK1.BMQESTDMSGOUT
AIX1BK1.BMQPSTOPOLOGY
AIX1BK1.BNBRCONNECTIONS
AIX1BK1.BPHYSICALFILE
AIX1BK1.BPUBLISHERS
AIX1BK1.BRETAINEDPUBS
AIX1BK1.BRMCONFIG
AIX1BK1.BROKERAA
AIX1BK1.BROKERAAEG
AIX1BK1.BROKERRESOURCES
AIX1BK1.BSCADADEST
AIX1BK1.BSCADAMSGIN
AIX1BK1.BSCADAMSGOUT
AIX1BK1.BSUBSCRIPTIONS
AIX1BK1.BTOPOLOGY
AIX1BK1.BUSERCONTEXT
AIX1BK1.BUSERMEMBERSHIP
AIX1BK1.BUSERNAME
AIX1BK1.BWFFRELATIONSHIP
The same script was executed after the uninstall. This was to determine whether
the tables were indeed cleaned up.
After the uninstall of MQSeries Integrator V2.0.2 from AIX1, all the counts for
these tables were zero.
This indeed proves that the uninstall completes a successful delete of the
defined brokers. The undeploy did not delete the records from the tables. The
undeploy might have had it finished properly. Or the undeploy may just have
marked the rows as deleted. We believe they should have been deleted.
3.8.2 Upgrade on NT1

The upgrade of NT1 began by stopping the Configuration Manager and exporting
the message sets. The export has to be performed for all defined message sets.
116
mqsiimpexpmsgset -e -n MQSIMRDB -u NT1CM -p NT1CM -s "Receipt

Messages" -l 1 -f receiptmsg.mrp
At this point, the Configuration Manager was deleted without deleting the tables.
This is accomplished by entering the command mqsideleteconfigmgr, without
specifying any parameters.
Then WebSphere MQ Integrator V2.1 was installed. The install was executed
per the documented instructions without first uninstalling the current version of
the product. Because we saved our current installation and installed without
uninstalling the product, the directories that it was installed in were the old
directories that had 2.0 in their name. This is a bit confusing, but is documented
in the installation guide.
When the install reaches the point where it is going to install NEON, the choice is
to continue or cancel. Choosing Cancel displays a box that states that the
installation will be incomplete if you continue. We needed support for NEON
messages anyway, so we chose to install. The machine was then rebooted.
The mqsidropmrmtables command was executed from a DB2 command line
window.
mqsidropmrmtables -n MQSIMRDB -u NT1CM -p NT1CM
From this same DB2 command window, we migrated the remaining tables using
the mqsimigratetables command.
mqsimigratetables -n MQSICMDB -u NT1CM -p NT1CM
These procedures are documented in the WebSphere MQ Integrator

Administration Guide, SC34-5792.
We then recreated the Configuration Manager using the exact same parameters
we used when we originally created it. That is, we made sure to use the user ID
and password that were originally used to create it. This is the same user ID
used for the mqsidropmrmtables and mqsimigratetables commands.
Then we executed the mqsiimpexpmsgset command to import the receipt
message set that was previously exported.
mqsiimpexpmsgset -i -n MQSIMRDB -u NT1CM -p NT1CM -f receiptmsg.mrp
Then we created a dummy broker as instructed in chapter Migration from

MQSeries Integrator in the manual WebSphere MQ Integrator Administration
Guide, SC34-5792. The dummy broker causes the broker database
(MQSIBKDB) tables to be updated to include all changes made for the new
version. Once that is complete, the dummy broker is deleted.
117
Now the Configuration Manager and broker are started. This can be
accomplished from the command line with mqsistart configmgr and mqsistart
NT1_BK1 or from the Windows NT/2000 Services applet in the Control Panel.
When we imported the message set previously, we failed to include the -x
parameter, which is new. Since our sample messages were defined in the MRM
but have a message type of XML, we needed an XML layer added to the new
message set. We started the Control Center and connected to the Configuration
Manager. At that time, we received the message that obsolete data was present
in the message set in the workspace. To correct this problem, we needed to
import the workspace element values. We are not required to do this, since the
message set is correct in the database. If we really do not need the values for
any reason, they need not be added to the workspace. Then we checked out the
message set and added the XML layer with type name XML. This was checked
in and deployed to the broker.
To understand more about physical layers in the MRM and other new features of
the MRM, refer to Chapter 6, New MRM features explored on page 163.
To add the XML layer, right-click the message set. Then click Add -> Physical
Format -> XML Format (see Figure 3-52).
118
Figure 3-52 Add XML layer to Receipt Message Set
A new window will appear to name the new format (Figure 3-53).
119
Figure 3-53 Add XML layer to Receipt Message Set continued
You must provide a value for the XML identifier.
120
Figure 3-54 Add XML layer to Receipt Message Set, continued
This is the resulting XML layer. No changes need to be made.
121
Figure 3-55 Add XML layer to Receipt Message Set, continued
The changed message set is now assigned to the broker and deployed
successfully (Figure 3-55).
The message flow is tested as before. We use mqsiput.exe to put the sample
data file, provided in the SupportPac, to the input queue. Messages appear on
the appropriate output queue to prove that the flow still works.
122
Figure 3-56
Messages in the output queues of the message flow
3.8.3 Upgrade on NT2

The upgrade of NT2 began by stopping the Configuration Manager and exporting
the message sets.
mqsiimpexpmsgset -e -n MQSIMRDB -u NT2CM -p NT2CM -s "Loan Request"
-l 1 -f loanmsgset.mrp
At this point, the Configuration Manager was deleted without deleting the tables.
This was accomplished by entering the command mqsideleteconfigmgr, without
specifying any parameters.
mqsideleteconfigmgr
On NT1, we had chosen to install the new version on top of the existing one. The
result was that the new product code was stored in a folder with a name that
included the old version number. Because this is quite confusing, we decided to
uninstall the software on NT2.
Because we have saved the message sets and message flows, we can uninstall
the product completely, including the data.
MQSeries Integrator V2.0.2 was uninstalled as follows:
1. Click Start -> Programs -> MQSeries Integrator -> Uninstall..
2. Click the radio button Uninstall MQSI completely, including data.
3. Click Next.
4. Click Finish.
Choosing the option to delete the data and files is necessary to clean up all
registry entries.
123
When an uninstall is performed, an mqsideletebroker command is executed for

you. Therefore, you have no brokers when you reinstall. This can cause problems
if you have not planned for it. The Configuration Manager will still think it has
deployed brokers. This is not necessarily a problem if you redefine the brokers
exactly as you did before. Then you redeploy the full configuration to that broker
from the original Configuration Manager from which it was deployed.
WebSphere MQ Integrator V2.1 was then installed. The install was executed
following the documented instructions in the WebSphere MQ Integrator
Installation Guide for Windows NT/2000, allowing us to choose the directories in
which to install the product.
Then mqsidropmrmtables command was executed from a DB2 command line
window.
mqsimrmdroptables -n MQSIMRDB -u NT2CM -p NT2CM
From this same DB2 command window, we migrated the remaining table using
the mqsimigratetables command.
mqsimigratetables -n MQSICMDB -u NT2CM -p NT2CM
These procedures are documented in the WebSphere MQ Integrator

Administration Guide, SC34-5792. There is an entire chapter on migration
considerations.
We then recreated the Configuration Manager using the exact same parameters
we used when we originally created it. That is, we made sure to use the user ID
and password that were originally used to create it. This is the same user ID used
for the mqsidropmrmtables and mqsimigratetables commands. See Figure 3-18
on page 64, Figure 3-19 on page 65, and Figure 3-20 on page 66 for the values
that were used originally.
Then we executed the mqsiimpexpmsgset command to import the message set
that was previously exported.
mqsiimpexpmsgset -i -n MQSIMRDB -u NT2CM -p NT2CM -f loanrequest.mrp
-x XML
When we imported the message set, we included the new -x parameter. This
parameter allows you to enter an XML type name at import time and therefore
create the XML layer. Since our sample messages were defined in the MRM
domain and have a message type of XML, adding this XML layer is required.
124
We did not need to create a dummy broker as instructed in the Migration

Considerations chapter of the WebSphere MQ Integrator Administration Guide,
SC34-5792. The creation of the dummy causes the broker database
(MQSIBKDB) tables to be updated to include all changes implemented for the
new version. Since we performed an uninstall, the brokers were deleted.
Therefore, we simply recreate the brokers we require: NT2_BK1, NT2_BK2, and
NT2_BK3.
Now the Configuration Manager and broker are started. This can be
accomplished from the command line with mqsistart configmgr and mqsistart
NT2_BK1 or using the Windows NT/2000 Services applet.
We started the Control Center and connected to the Configuration Manager.
Figure 3-57 Connect to Configuration Manager
We added the loan request message set and all components that are a part of
that message set to the workspace. This is done to verify that the import worked
properly and that the XML layer was added. This is not required since the
message set is correct in the database. If you really do not need the values for
any reason, they need not be added to the workspace.
125
Figure 3-58 Imported Loan Request Message Set
Click the XML tab to verify the XML layer (Figure 3-59).
126
Figure 3-59 Imported Loan Request Message Set - XML Wire Format
The XML layer was added to the message set when it was imported. This was
accomplished by using the new -x parameter. Notice that the XML Wire Format
Identifier is XML, which is the name we supplied with the -x parameter.
The Configuration Manager still thinks it has three deployed brokers. This is
really not a problem. All that is required to make things work is to check out the
brokers. All message sets deployed to these brokers are deleted from each
broker. You need to drag each message set to the appropriate broker. This is
necessary, because the imported message sets will have new UUIDs. Check in
everything by clicking File -> Check In -> All (Save to Shared). Now a complete
deploy of all types is performed by clicking File -> Deploy -> Complete
Configuration (all types) -> Normal.
Now the message flows and message sets for brokers NT2_BK2 and NT2_BK3
can be redeployed. We connect to each Configuration Manager, NT1_CM and
NT3_CM and perform a complete deploy to the NT2 broker attached to each of
these Configuration Managers.
127
Having performed the upgrade of 2.0.1 to 2.1 in place without uninstalling the
2.0.1 version on NT1, and the upgrade of 2.0.2 in place with the uninstallation of
the 2.0.2 version on NT2, we have now a very complex environment. Since there
is already a planned consolidation of Configuration Managers, we decide to
proceed to that step.
3.9 Consolidating Configuration Managers

It is determined that we no longer need multiple Configuration Managers. The
components defined to each Configuration Manager on NT1, NT2 and NT3 are
migrated to a single consolidated Configuration Manager on NT3. NT1, NT2 and
NT3 continue to host the brokers, but only one each.
The steps taken to achieve this consolidation are documented below.
1. Export all message sets and flows from the Configuration Managers on NT1,
NT2.
2. Import all message sets and flows into the Configuration Manager on NT3.
3. Undeploy all message sets and flows from all brokers in the NT1, NT2
topologies.
4. Remove all brokers from the topologies on NT1 and NT2 and NT3. You must
get back a message stating that all references to the brokers have been
removed. If, for some reason, you do not receive this message, delete the
brokers on each machine. We deleted all of them and redefined only one
broker on each machine.
We define broker NT1_BK1 on NT1 and broker NT2_BK1 on NT2 and add them
to the topology in Configuration Manager NT3_CM on NT3.
We are deploying all message flows to all three machines, NT1, NT2 and NT3.
This accomplishes the goal of having each flow running in multiple places.
Finally, we deploy all flows and their message sets to the brokers on NT1, NT2,
and NT3 and test the execution.
Since the upgrade of message sets and flows was performed previously, the
consolidation turns out to be a rather simple task. The final environment of
WebSphere MQ Integrator is shown in Figure 3-60.
128
DEVUSER
NT1BK1
Broker NT1_BK1
NT1_BK1_QMGR
Control Center
NT5 Machine
NT1 Machine
DEVUSER
NT3CM
Control Center
NT3_CM_QMGR
NT6 Machine
NT3BK1
AIX1BK1
Broker NT3_BK1
NT3_BK1_QMGR
Broker AIX1_BK1
AIX1_BK1_QMGR
NT3 Machine
AIX1 Machine
NT2BK1
Broker NT2_BK1
NT2_BK1_QMGR
NT2 Machine
Legends:
Figure 3-60 Migrated multi-broker environment
129
130
Chapter 4.
Deploying a broker on Sun

Solaris using Oracle 8i
This chapter describes the process of installing and configuring a WebSphere
MQ Integrator broker running on Sun Solaris 8 with Oracle 8i as the data source.
This chapter assumes that you have a successful installation of Oracle 8i
software. However, if you do need help with the Oracle installation itself, please
refer to Appendix C, Oracle8i installation and configuration on Solaris on
page 429 for some assistance.
Once you have Oracle installed, this chapter will guide you through the process
of creating and configuring both a broker database and the broker to be used
with the remote Configuration Manager that was created in 3.9, Consolidating
Configuration Managers on page 128.
131
4.1 Introduction
One of the platforms that WebSphere MQ Integrator supports for running a
broker is Sun Solaris. With Solaris, there is also support for running a broker
using DB2, Sybase and Oracle. The installation and configuration options for all
of these data sources can be found in the documentation that accompanies the
product: WebSphere MQ Integrator for Sun Solaris Installation Guide,
GC34-5842, and the WebSphere MQ Integrator Introduction and Planning
Guide, GC34-5599. Since configurations utilizing DB2 and SQL Server were
used in other chapters of this book, we chose to take advantage of the
opportunity to conduct our broker installation using Oracle 8i while working with
Solaris.
On this platform and with these databases, there is full support for running a
message broker and a User Name Server on the same queue manager, as on all
of the other supported platforms. WebSphere MQ Integrator also supports the
MQSeries ability to implement an XA configuration with a compliant database,
such as DB2 or Oracle.
While this chapter will discuss these features, you should also consult all of the
supporting documentation for Solaris, Oracle and MQSeries to ensure proper
configuration for your requirements.
4.2 Getting started

Before starting the installation and configuration, make sure that your system
meets the following installation requirements:
Sun Solaris V8
Oracle 8i V8.1.6
MQSeries 5.2
1 GB of free disk space
512 MB of RAM
For XA support, you will need a SPARC compatible C compiler.
132
4.3 Software installation

The process of installing MQSeries and WebSphere MQ Integrator is well
documented in the Solaris Installation Guide for each product. We used the basic
settings for installing MQSeries, as described in MQSeries for Sun Solaris V5R0
Quick Beginnings, GC33-1870.
MQSeries installation
1. While logged in as root or super user, create the user and group mqm using
the admintool utility. Install the MQSeries software package using the pkgadd
utility.
2. Create a queue manager to be used by our broker called SUN1_BK1_QMGR. with
the command:
crtmqm SUN1_BK1_QMGR
Consider increasing the values for logging. You can update mqs.ini in
/var/mqm before running the crtmqm command. Or, if you do not want to
change the logging defaults, use the parameters -lp and -lf to increase the
size of the logging space. Remember also that you will need linear logging in
MQSeries to be able to use MQSeries built-in backup and restore facilities.
The next command creates a queue manager that has 20 MB of logging
space.
crtmqm -lp 5 -lf 1024 SUN1_BK1_QMGR
3. You also need to create a listener by editing the /etc/services file to add an
entry similar to the following:
sun1bk1
1415/tcp
# mq qmgr listener port for bk1
4. Finally, you will need to make one additional entry to the /etc/inetd.conf file:
sun1bk1 stream tcp nowait mqm /export/home/mqm/software/bin/amqcrsta
amqcrsta -m SUN1_BK1_QMGR
This should be all on one line. The value sun1bk1 in inetd.conf needs to
match the value sun1bk1 in the file services. You can choose any name you
want, as long as it is the same in both files.
5. We did not choose to make this queue manager the default queue manager,
so to start the queue manager you will need to specify:
strmqm SUN1_BK1_QMGR
Chapter 4. Deploying a broker on Sun Solaris using Oracle 8i
133
6. Verify that the queue manage is usable by starting the MQSC commands
with:
runmqsc SUN1_BK1_QMGR
If you execute runmqsc as the root user and root is not member of the mqm
group, the command may fail. Add root to the mqm group, or switch to the
mqm user by executing the command su - mqm.
WebSphere MQ Integrator installation

This installation also follows the standard installation outlined in the WebSphere
MQ Integrator for Sun Solaris Installation Guide, GC34-5842.
1. Create a new group (mqbrkrks) with the command:
groupadd mqbrkrs
2. Edit the /etc/group file and add root to the end of the mqbrkrs entry:
mqbrkrs::103:root
3. Create the new broker user ID, such as mqbroker, using the command:
user add -G mqbrkrs,mqm -c "WMQI user" mqbroker
passwd mq1broker
4. Once you have mounted the CD-ROM to a directory such as /cdrom, you are
ready to proceed with the software installation from the CD, using the
command:
pkgadd -d /cdrom/wmqi_solaris/
It would be best to install both wmqi and wmqi-docs packages.

5. After the installation has completed, you need to modify the profile for the
user that will be administrating the broker, such as mqbroker. The installation
also delivers an example profile.sol file stored in the
/opt/wmqi/software/sample/profiles directory. You can use the example
settings out of this file to update the .profile file for the user IDs which will
need access to WebSphere MQ Integrator commands or, alternatively, insert
this command directly into the user IDs .profile file if you prefer:
. /opt/wmqi/sample/profiles/profile.sol
After completing the Oracle installation and customization, we will need to

perform a few more steps before creating the broker.
134
Oracle customization
For the installation of the Oracle software packages, please refer to the specific
installations guides provided by Oracle. For further help, you can access the
installation guidelines that we used in Appendix C, Oracle8i installation and
configuration on Solaris on page 429. This demonstrates the basic installation
and configuration that we used for this project so that your installation will follow
our configuration. Every enterprise environment will have different configuration
requirements for performance and scalability. It is recommended that the data
source be housed on the same physical machine as the broker for performance
reasons and that a new database instance be created for the broker for ease of
management.
Once the Oracle software is installed and you have created a database instance
with a name such as WMQIBKDB, there are some additional tasks that must be
performed to support ODBC and connectivity with the broker.
1. If you are using Oracle 8.1.6, as we did, you will need to issue the following
command to update the Java Runtime Environment (JRE) that Oracle uses:
mqsi_setupdatabase oracle <database_install_directory>
where, in this case, the <database_install_directory> is:

/export/home/oracle/u01/app/oracle/product/8.1.6
2. Though we will discuss XA support later in the chapter, you can execute the
following command at this time:
ln -s <db_directory>/lib/libclntsh.so /usr/lib/libclntsh.a
where, in this case, the <db_directory> is:

/export/home/oracle/u01/app/oracle/product/8.1.6
If you are not signed on as the oracle user, you may have to change to that
user (oracle) to execute these commands.
3. Make sure that your SQL*Net listener is running by issuing the command:
lsnrctl status
In our environment, we named the listener LISTENER.

4. If it is not started, issue the command:
lsnrctl start LISTENER
5. Another check can be performed by using the command tnsping:

tnsping wmqibkdb
6. It is suggested that you create a new Oracle user ID to be used with your new
Oracle database to support the broker. Log in to SQLPlus with the
administrator user ID and password. If you just now created your new
135
database, the user ID and password are probably either system/manager or

whatever the GUI installation windows told you they are.
sqlplus system/manager@wmqibkdb
At the SQL prompt, run the command:

CREATE USER mqbroker IDENTIFIED BY mq1broker;
GRANT CONNECT TO mqbroker;
GRANT RESOURCE TO mqbroker;
GRANT CREATE TABLE TO mqbroker
Notice that we used the same user name and password for the database as
we did for the broker administrator. This was done mainly for the sake of
simplicity. You can create the Oracle user ID with whatever name you choose,
since it can be specified in the mqsicreatebroker command.
7. Exit SQLPlus and attempt to log back in using the newly created user name
and password:
sqlplus mqbroker/mq1broker@wmqibkdb
8. If you followed the instructions for installing and configuring the database
from Appendix C, Oracle8i installation and configuration on Solaris on
page 429, you should be able to see that the connection is using SQL*Net
and is not local. You can verify this by opening another terminal and logging in
as root. Now issue the command
ps -ef | grep mqbroker
and you should see an entry that looks like this:

mqbroker 1234 5678 0
12:00:00 ? 0:00 oraclemqbroker (local=NO)
9. Now you need to make some final adjustments for ODBC by editing the
/var/wmqi/odbc/.odbc.ini file as follows:
At the top of the file, add the entry:
[ODBC Data Sources]
WMQIBKDB=MERANT 3.70 Oracle 8 Driver
[WMQIBKDB]
Driver=/opt/wmqi/merant/lib/UKor816.so
WorkArounds=536870912
WorkArounds2=2
Description=Oracle8
ServerName=wmqibkdb
EnableDescribeParam=1
OptimizePrepare=1
136
Logging
After completing the software installations and creating the database, there are
still a few configuration requirements that must be completed before creating the
broker.
10.Add the stanza user.info /tmp/wmqisys.log to the /etc/syslog.conf file. This
will create logging ability.
11.Create the logging file by executing the command touch /tmp/wmqisys.log
Final adjustments to the broker user profile

These changes need to be made to the .profile file of the mqbroker user ID so
that you are assured of success in locating the ODBC and other resources upon
startup of the broker.
Important: There may already be some settings similar to these entries in
your .profile file. Make sure that you set these extra parameters below your
existing parameters, but before calling the export clause.
For our example, <oracle_home_directory> is:

/opt/oracle8/u01/app/oracle/product/8.1.6
1. Edit the file .profile of the mqbroker user ID and add the lines shown in
Example 4-1.
Example 4-1 Sample additions to the .profile for the mqbroker
ORACLE_HOME=<oracle_home_directory>
export ORACLE_HOME
LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
LIBPATH=$LD_LIBRARY_PATH
export LIBPATH
NLS_LANG=AMERICAN_AMERICA.UTF8
export NLS_LANG
2. Save your changes. Rerun the .profile command by logging off and back on
or by executing it like so:
. ./.profile
3. At this point, you should be ready to create the broker. If, when issuing the
mqsicreatebroker command, you are presented with some errors involving
data source, ODBC or connection to the database, investigate the error
137
message closely. Most likely the problem will be with one of the configuration
settings in either the .odbc.ini file or the .profile file for the broker user.
4.4 Creating and configuring the broker

Now you should be ready to create the broker.
1. Make sure that you are logged in to Solaris with the user ID mqbroker.
2. Run the mqsicreatebroker command:
mqsicreatebroker SUN1_BK1 -i mqbroker -a mq1broker -q SUN1_BK1_QMGR
-n WMQIBKDB -u mqbroker -p mq1broker
3. If the broker was created successfully, you should be able to issue the
command mqsilist and see the output:
BIP8099I: SUN1_BK1
SUN1_BK1_QMGR
BIP8071I: Successful command completion.
4.4.1 Connecting the brokers queue managers and the Configuration

Manager
1. Assuming that you are still signed on as mqbroker, start an MQSeries
command session using the command:
runmqsc SUN1_BK1_QMGR
2. Next, define a local queue to be used as a transmission queue by the sender

channel, using:
define qlocal(NT3_CM_QMGR) usage(xmitq) maxmsgl(100000000) trigger
trigtype(first) initq(SYSTEM.CHANNEL.INITQ) userdata(TO.NT3_CM_QMGR)
3. Now define the sender channel with the command:

define channel(TO.NT3_CM_QMGR) chltype(sdr) trptype(tcp)
conname(M23CABXK(1415)) xmitq(NT3_CM_QMGR) maxmsgl(100000000)
4. Now define the receiver channel with:

define channel(TO.SUN1_BK1_QMGR) chltype(rcvr) trptype(tcp)
maxmsgl(100000000)
On queue manager NT3_CM_QMGR, similar objects were created to complete

the MQSeries communication. Refer to Chapter 3, Migration of an MQSeries
Integrator environment on page 37 for details about the configuration of the
queue manager NT3_CM_QMGR.
138
4.4.2 Configuring XA support

A broker is at the same time an MQSeries application and a database
application. Message flows can include database updates and MQSeries
updates. Since version 5, MQSeries supports the XA 2 phase commit protocol.
This allows an application to create a single transaction for MQSeries updates
and database updates. The queue manager acts as a resource coordinator
between itself and the database manager.
WebSphere MQ Integrator has the possibility of exploiting this XA commit
protocol. However, before the broker can use it, a number of configuration steps
are required for the queue manager, the database manager and the broker.
Compilation of a switch module

The queue manager will load a so-called switch module to interact with the
database manager. Basically, this switch module tells the queue manager what
the entry points are for each call of the XA protocol. This switch module must be
compiled for the version of the queue manager and the database manager used
in your environment.
Follow these steps to make this module available for the queue manager.
1. Create a directory to compile and store the switch module. Make sure that this
directory is accessible to the queue manager:
mkdir /var/mqm/exit/oracle
2. Copy the source file, the include file, and the make file for the switch module
into this directory.
cd /opt/mqm/samp/xatm
cp oraswit.c xa.h xaswito8.mak /var/mqm/exit/oracle
3. Compile the source module. You will need a compatible C compiler, such as
Forte C++ V6. The user ID executing the make command will need to have an
environment set up for compilation.
make -f xaswit.mak
4. Depending upon your environment, you may need to create the following
links:
ln -s /usr/ucblib/libucb.so /usr/lib/libucb.so
ln -s /usr/ucblib/libucb.so.1 /usr/lib/libucb.so.1
In addition to these, you should have created another link, as discussed in

Oracle customization on page 135.
139
When the compilation is finished, verify again that the queue manager user ID
has access to the shared library.
Changes to qm.ini
The queue managers initialization file qm.ini has a special stanza for XA
coordination. Add the stanza XAResourceManager: to this file for each Oracle
database. You may add more than one database to this file. Example 4-2 shows
the settings for the brokers own database. Add similar statements for any other
database that is accessed by the database nodes in your message flows.
Example 4-2 Settings in qm.ini for an Oracle database
XAResourceManager:
Name=Oracle WMQIBKDB
SwitchFile=/var/mqm/exits/oracle/ora8swit
XAOpenString=
Oracle_XA+Acc=P/mqbroker/mq1broker+SesTm=35+logDir=/var/mqm/exits/oracle/ora.lo
g+DB=WMQIBKDB
Note that XAOpenString= should be on a single line. The XA protocol also allows
for XACloseString, but this is not required for Oracle databases.
Changes to Oracle
The user ID that was included in XAOpenString needs to have select authority for
a specific Oracle table. To grant this authority, log on using the user ID oracle and
start the SQLPlus interface. Within SQLPlus, log on to Oracle using user ID sys.
Execute the following command:
grant select on DBA_PENDING_TRANSACTIONS to mqbroker;
Changes to .profile files

The .profile files of the mqm user and the mqbroker user should contain exports
of two environment variables:
export ORACLE_HOME=/opt/oracle8/u01/app/oracle/product/8.1.6
export ORACLE_SID=oracle
This completes the configuration of XA support.
140
4.4.3 Verification of the installation

Before starting the broker itself, start the queue manager and verify in its log files
that the queue manager is starting and that it has no problems communicating
with the database manager. MQSeries stores error messages in three different
locations, depending on the type and source of error. Verify all of them:
/var/mqm/errors
/var/mqm/qmgrs/SUN1_BK1_QMGR/errors
/var/mqm/qmgrs/@SYSTEM/errors
Replace SUN1_BK1_QMGR with the name of your queue manager.

Next, start the broker itself, by executing the command
mqsistart SUN1_BK1
Verify the log file /tmp/wmqissy.log (refer to Logging on page 137) and check
that no errors are reported.
When no errors are encountered, you can add the broker to the topology in the
Configuration Manager and deploy the topology. Once the deploy of the topology
is successful, you can assign message flows to the broker.
141
142
Chapter 5.
Deploying a broker on
Windows 2000 using SQL
Server
This chapter describes the process of installing a WebSphere MQ Integrator
Broker on Windows 2000 with SQL Server 7.0.
With WebSphere MQ Integrator, it is now possible to configure and deploy a
broker using Microsoft SQL Server as the database. It is not possible to use MS
SQL Server as the data source for either the Configuration Manager or the
Message Repository.
143
5.1 Why install on SQL Server?

WebSphere MQ Integrator 2.1 is a tool supported over several platforms and
environments and is intended for use in dynamic and creative scenarios. Adding
support for SQL Server on either Windows NT or 2000 increases the flexibility of
supporting new brokers in architectures that may already be based on SQL
Server as a data source. Additionally, organizations that may have better
administrative support for SQL Server on Windows NT/2000 than for DB2 might
find this extra support useful.
It is important to note that using SQL Server as a data source for a broker over
DB2 or some other data source provides no specific technological or
performance benefits. This support adds some flexibility to a distributed
architecture.
Other sections in this chapter outline the steps used to install SQL Server and a
WebSphere MQ Integrator broker on Windows 2000 with Service Pack 2. This is
intended to provide guidance and reference. If you choose to use another
platform, such as Windows NT 4.0 or another release of SQL Server, please be
sure to first consult all of the WebSphere MQ Integrator release notes from IBM
and Microsoft SQL Server, as well as the NT release notes.
5.2 Getting started

Although there is some flexibility for the hardware and software requirements, our
example installation uses these specific pre-requisites:
Windows 2000 with Service Pack 2
SQL Server version 7.0
WebSphere MQ Integrator version 2.1 (Broker Install Only)
Pentium III, 512 MB RAM
Configuration Manager configured on a remote host
The broker that we are going to create is going to run on its own stand-alone
server, with the Configuration Manager running on a separate machine. There is
no good reason to install a broker on SQL Server and Configuration Manager on
the same machine, since they would require a separate database product.
Important: Remember that you should conduct all of these installation steps
signed on as a user that is a member of the Administrator group.
144
5.3 Installation of SQL Server 7.0 SP2

Before installing and configuring SQL Server, we will first create a database user
ID for use by the database engine.
Setting up the database user

To make the SQL Server software installation easier, it is best to create the
database user(s) first.
1. Go to Start -> Settings Control Panel -> Administrative Tools ->
Computer Management.
2. Expand Local Users and Groups. Right-click the Users folder and add a
new user.
3. For the database user ID, use wmqi_db with a suitable password (for example
wmqi_db).
4. Click Password never expires (this is for convenience only, set as needed).
Click Create, then click Close.
Figure 5-1 Setting up the database user
5. Right-click the new user and select Properties. Select the Member Of tab
and add the user to the Administrators group.
6. Close the window and proceed to the SQL Server installation.
Chapter 5. Deploying a broker on Windows 2000 using SQL Server
145
SQL Server typical installation

For this example, we conducted a standard software installation of SQL Server
V7.01 from CD. A general outline of the software installation we conducted is
outlined below. If you require more advanced assistance with the Microsoft
portion of the installation, please refer to the specific documentation.
1. Mount the CD and let the autorun start. If it does not load the installation
window automatically, double-click autorun.exe from the CD directory.
2. Choose Install SQL Server 7.0 Components.
3. Choose Database Server - Desktop Edition (If you are running Windows
2000 Server, you may want to use Database Server - Standard Edition).
4. Choose Local Install and continue to select Next until you reach the window
shown in Figure 5-2:
Figure 5-2 Typical or custom setup menu
5. Here you can select a Typical or Custom installation. For our purposes, the
Typical installation is sufficient. Verify the installation directory and click Next.
6. The next step is to assign the user that will run the SQL Server services. Use
the user ID that we defined above and the correct password. Use the local
machine name as the domain to be specific for our example. Click Next.
146
Figure 5-3 Assigning user to SQL Server Services
7. This should be all of the information that you need to begin the install. When
the install completes, you will need to apply the Service Pack. If your
installation prompts you to reboot, then do so. If the system does not prompt
you to reboot, you should be able to conduct the service pack install
immediately.
8. We received Service Pack 2 from this URL:
http://www.microsoft.com/sql/downloads/sp2.asp
For this example, it was only necessary to use the Database Components
Service Pack 2, and not the OLAP Service Pack 2, since we did not install
those features. The file to download is called sql70sp2i.exe for Intel platforms.
Since the minimum requirement for running a WebSphere MQ Integrator
Broker on SQL Server 7.0 is Service Pack 2, that is what we choose to use.
You may want to attempt to use a later service pack, if needed.
9. Save this file to a temporary directory and unzip it. Run the Setup.bat
command file. The installation should start and you should be able to select
Windows NT authentication. That should be all the information you need to
let the installation continue. Several scripts are run and it will take some time
for the service pack to finish the installation.
10. When the installation is completed, open the Windows Services menu and
locate MSSQLServer and SQLServerAgent. Set both of these services to
start up automatically (this may already have been done).
147
11. This would be a good time to reboot. Once the reboot is completed, open he
Services menu again and ensure that the two required services are running.
12. Open the Event Viewer and see whether there are any new messages in the
Application or System Event log that pertain to the SQL Server installation.
13. Go to Start -> Programs -> Microsoft SQL Server 7.0 -> Enterprise
Manager. Expand the nodes until Databases is visible. If the two services are
running and you still get a message similar to the one shown in Figure 5-4,
simply ignore it and click Yes.
Figure 5-4 Possible message when accessing Databases
14. Now we are going to create a database that will be used by the WebSphere
MQ Integrator broker. Right-click Databases and select New Database. The
name of the database should be WMQIBKDB. Accept the default values for the
other fields; these can be optimized later if necessary.
15. Now expand the Security folder. Right-click Logins and select New Login.
For the name, use the user that you created earlier, wmqi_db. Use the
Windows NT Authentication and set the Domain name as your local
machine name for this example. Use Grant Access and set the Default
Database to WMQIBKDB. The pane should look like Figure 5-5.
148
Figure 5-5 Setting security for the broker database
16. Under the Database Access tab (see Figure 5-6), click the Permit checkbox
for WMQIBKDB. Under Database Roles, you can also select public,
db_owner, db_accessadmin, db_securityadmin, db_ddladmin,
db_datareader and db_datawriter. When you are finished, click OK.
149
Figure 5-6 Granting database access
17. Close the SQL Server Enterprise Manager. We now have to define the
ODBC datasource.
18. Select Start -> Settings -> Control Panel -> Administrative Tools -> Data
Sources (ODBC). Select the System DSN tab and click Add.
19. Scroll down the driver list until you find SQL Server and double-click it. For
the datasource Name, just use the same name as the database,
WMQIBKDB. Use the same for the Description and select (local) from the
pull-down menu to choose the SQL server (see Figure 5-7).
150
Figure 5-7 SQL server ODBC DNS configuration
20. Click Next.In the next window, select Windows NT authentication using
the network login ID. It is probably also a good idea to select the Connect to
SQL Server to obtain default settings for the additional configuration
options checkbox (see Figure 5-8).
Figure 5-8 SQL server login for ODBC configuration
21. Click Next. Change the default database to WMQIBKDB and accept the other
default values.
151
Figure 5-9 SQL server default database for ODBC configuration
22.Click Next, then Finish.
Figure 5-10 Finishing the ODBC setup
23.If you want to test the data source, you can do so in the next window by using
the button provided.
152
Figure 5-11 SQL Server ODBC Data Source Test
24.When finished, click OK. Close the data source window by clicking OK. Now
you are ready to install WebSphere MQ Integrator 2.1.
5.4 Installing a WebSphere MQ Integrator broker

The remainder of this chapter discusses how to install and configure a broker to
run on the SQL Server database that we created in the previous section.
In order for your broker to have any value, you must also have a working
Configuration Manager and Message Repository on a remote machine. The
broker will be defined in the Configuration Manager that we built in 3.9,
Consolidating Configuration Managers on page 128.
5.4.1 Broker only installation

1. Proceed with the standard product installation by loading the WebSphere MQ
Integrator CD and running Setup.exe. We choose to change the installation
to C:\WebSphere MQ Integrator 2.1.
2. The most important step to note is that you should choose the Broker only
installation option (see Figure 5-12 on page 154) or Full install if you want to
use a Control Center on this machine.
153
Figure 5-12 Broker only install
3. Click Next through the next several windows until the installation starts. The
installation may pause at the NNSYRules and NNSYFormatter Installation
window. Go ahead and install this support by clicking Next.
4. If you have already registered, you can bypass the registration window
without completing it again.
5. Most likely, WebSphere MQ Integrator will prompt you for a reboot. Close
down any other applications that you have running and proceed with the
reboot.
6. We are going to use a separate user to run the broker service. Therefore, you
need to go back to Start -> Settings Control Panel -> Administrative Tools
-> Computer Management.
7. Expand Local Users and Groups. Right-click the Users folder and add a
New User.
8. For the service user ID, use NT4_BK1 with the same password. Click Create
then Close.
9. Right-click the new user and select Properties. Click the Member Of tab and
add the user to the Administrators, mqbrkrs and the mqm groups.
154
Figure 5-13 Groups membership for broker user
10. The easiest way to create a broker on Windows 2000 is to first create the
queue manager. By creating the queue manager yourself, you can, for
example, specify appropriate values for logging. This procedure is well
described in other places. For a quick refresher, go to Start -> Programs ->
IBM MQSeries V5.2.1 -> MQSeries Services. Select Action -> New ->
Queue Manager. Name the queue manager NT4_BK1_QMGR (you do not have
to use this name, but it is suggested for consistency with our installation). Fill
out the other fields as needed for your environment. To be consistent with our
installation, set Listener to run on port 1415. Finish using the wizard and start
the new queue manager from the MQSeries Services applet by right-clicking
NT4_BK1_QMGR and selecting All Tasks -> Start.
11.At this point, you are ready to create the broker itself. Go to Start ->
Programs -> IBM WebSphere MQ Integrator 2.1 -> Command Assistant
-> Create Broker. From the GUI that opens, you will be able to run the
mqsicreatebroker command. If you prefer to use the command line instead,
just do it from any new command window.
155
12. Name the broker NT4_BK1 and specify the new user ID you just created,
NT4_BK1, with the correct password. Set the queue manager name to
NT4_BK1_QMGR or whatever name thelocal MQSeries queue manager you are
using has.
Figure 5-14 Creating a broker menu 1
13. Click Next. Specify the data source to use, that is, the ODBC data source
that we previously created. The name that we used was WMQIBKDB. Use the
database service user ID and password that we specified previously. We used
wmqi_db. Leave the last two checkboxes empty for this installation.
14. Click Next and verify the command (the passwords are hidden).
156
15. If the command string is correct and complete, click Finish to create the
broker.
It is important to check the system and application error logs once the create
broker command finishes. If there are no error messages in the log files, then
you should be able to go to the Services applet and see a new entry that says
IBM MQSeries Broker NT4_BK1.
16. Set the service to start up automatically and then start it. Once again, you
should check the application and system logs to ensure that there are no
messages. To verify which elements are installed in the WebSphere MQ
Integrator environment locally, open a command prompt and issue the
command mqsilist.
BIP8099I: NT4_BK1
NT4_BK1_QMGR
BIP8071I: Successful command completion.
Figure 5-17 mqsilist output example
17. You are ready to begin using your new SQL Server-based broker in your
WebSphere MQ Integrator network.
5.4.2 Using the SQLServer broker

So that this newly created broker can be seen by remote configuration
managers, you must create channels that will be used between the local broker
queue manager and the remote queue manager used by the Configuration
Manager. The assumption is that you have successfully configured the remote
configuration manager that we have used throughout this book. In this section,
we will only discuss the steps required to connect to our local broker.
157
We will configure the channels using the MQSeries Explorer as an example, but
you can use the command line version.
1. Click Start -> Programs -> IBM MQSeries V5.2.1 -> MQSeries Explorer.
2. The first step is to define a transmission queue. Under your queue manager
for your broker, right-click Queues -> New -> Local Queue.
3. For the Queue Name, use NT3_CM_QMGR and for the Usage, use Transmission
(see Figure 5-18).
Figure 5-18 Create Transmission Queue General tab
4. Click the Extended tab and change the Maximum Message Length to
100000000.
5. Click the Triggering tab and set Trigger Control to On. Set Trigger Type to
First and set the Initiation Queue Name to SYSTEM.CHANNEL.INITQ. The field
Trigger Data should be set to TO.NT3_CM_QMGR, which is the name of the
sender channel that we will create here.
6. Click OK and verify that your queue is added to the display by refreshing the
screen.
7. Expand the Advanced folder and right-click the Channels folder. Select New
-> Sender Channel.
158
8. Under the General tab (see Figure 5-19), set the Channel Name to
TO.NT3_CM_QMGR, the Description to whatever you want, the Transmission
Protocol to TCP/IP, the Connection Name to your the remote machine name
with the port in () and the Transmission Queue to NT3_CM_QMGR.
Figure 5-19 Create Sender Channel General tab
9. Now click the Extended tab. Change the Maximum Message Length to
100000000.
159
Figure 5-20 Create Sender Channel Extended tab
10.Click OK and verify that the channel appears in the right-hand pane. You may
need to refresh the screen for it to appear.
11. Now it is time to define a receiver channel. Right-click the Channels folder
again and select New -> Receiver Channel.
12.Under the General tab, set the Channel Name to TO.NT4_BK1_QMGR, the
Description to whatever you want and the Transmission Protocol to TCP/IP
(Figure 5-21).
160
Figure 5-21 Create Receiver Channel General Tab
13.Click the Extended tab and set the Maximum Message Length to 100000000
(Figure 5-22).
161
Figure 5-22 Create Receiver Channel Extended tab
14. Click OK and verify that the channel was created.

15. Once you have defined the corresponding channels and transmission queue
on the queue manager that is supporting your Configuration Manager, as
outlined in 3.9, Consolidating Configuration Managers on page 128, then
you can start your channels by right-clicking them and selecting Start. You
could also rely on the triggering mechanism for channels.
5.4.3 Verification of the installation

If no errors are encountered, you can now add the broker to the topology in the
Configuration Manager and deploy the topology. Once the deploy of the topology
is successful, you can assign message flows to the broker.
162
Chapter 6.
New MRM features explored

WebSphere MQ Integrator V2.1 introduces enhanced support for a much wider
range of message types within its own message repository, the MRM. Tagged
and delimited messages are now supported, and there is broader support for
XML and the familiar Customer Wire Format (fixed length type messages).
This chapter introduces the new support and shows examples of how to define
messages exploiting the new features using the Control Center. It assumes that
you already have the Control Center, a broker and the Configuration Manager
installed and working.
This chapter also discusses the Graphical Debugger Interface, a debugging
utility which allows you to see the message content at various points throughout
your flow. This chapter shows an example of how to configure and run it, and
what the output should look like.
163
6.1 Converting a delimited message to XML

This chapter explores the new MRM support for tagged and delimited messages
by demonstrating how to transform a comma separated variable message into
an XML message, and then by transforming a tagged message into an XML
message.
WebSphere MQ Integrator 2.1 has enhanced support for message formats in the
MRM, including tagged and delimited formats. When a message set is defined,
you can add one or more physical formats to the message; these are different
ways the elements can be represented in actual messages.
In the following example, we define a new message set, adding both a delimited
physical format and an XML format (note that this is MRM-defined XML rather
than generic). Using this message set and a simple message flow, we are able to
transform a comma separated variable (CSV) message into an XML format
message. A CSV format is a typical format for data exported from a spreadsheet.
Example 6-1 Example of a comma separated variable message
Fred,Bloggs,fred@somewhere.com,London
The following steps will be described:

1. Creating a new message set
2. Adding a tagged/delimited physical format
3. Adding an XML physical format
4. Creating some string elements
5. Creating a new compound type
6. Adding elements to the compound type
7. Creating a new message
8. Adding the compound type to the message
9. Reordering the elements in the type
10.Creating a new message flow
11.Configuring the MQInput and MQOutput nodes
12.Configuring the Compute node to transform the message
13.Deploying the message set and flow
14.Testing the flow with a CSV message
164
The above steps are then repeated for a tagged message format; only the
differences are shown for clarity. We also show use of the message flow
debugger with a tagged message.
6.1.1 Creating a new message set

It is assumed that you have WebSphere MQ Integrator 2.1 installed on Windows
NT (or 2000) along with its prerequisites MQSeries and DB2. You may perform
these tasks from a remote workstation running the Control Center or from the
same system as the Configuration Manager.
Start by launching the Control Center and accessing the Message Sets tab. Then
right-click the Message Sets folder of the navigation tree to bring up the context
menu. Select Create -> Message Set.
Figure 6-1 Creating a new message set
Give the new message set a name; this name needs to be unique within the
Configuration Manager. Leave the default value for the other fields in this window
and click Finish, as shown in Figure 6-2.
Chapter 6. New MRM features explored
165
Figure 6-2 Naming the new message set
The message set will now be shown in your workspace; note especially the
identifier which has been created automatically: this is used to reference the
message set in the message flow. It does appear in a drop-down list for
completion in some Control Center fields, but it is vital that you make sure you
are using the correct one, because the identifiers for different message sets may
be similar.
166
Figure 6-3 The newly created message set
If you click the Run Time tab, you will see that the Parser value is set to MRM, as
shown in Figure 6-4. This is the default and indicates that this message set will
use the MRM. It is important to make the distinction between MRM-defined XML
and generic (or self-defining) XML. This example uses defined XML, which
allows the MRM to perform most of the work required for message
transformation. Defining XML messages in the MRM has the advantage that you
can use the drag-and-drop features of a Compute node when building ESQL
statements for a transformed output message.
Figure 6-4 MRM parser value
167
6.1.2 Adding the physical formats to the message set

The next step is to add the physical formats; let us start with the tagged/delimited
format. Right-click the message set name, then select Add -> Physical Format
-> Tagged/Delimited Format.
Figure 6-5 Adding a physical layer
Give the format a name (in this example, TDS1). After it is created, you will see a
new tab appear with the name of the format. Select this tab, then set and check
the identifier. For ease of use, we recommend making the identifier the same as
the format name. This avoids the problems that can arise if the wrong value is
entered in another part of the message set or in an MQInput node of a message
flow.
At the same time, the delimiter character (a comma) can be entered, and the
changes applied. Note that the messaging standard defaults to UNKNOWN. This is
correct, because we are not using one of the pre-defined industry standard
formats (such as SWIFT) in this example.
168
Figure 6-6 The TDS physical format
Repeat the previous step to add an XML physical layer format. Remember to set
the identifier to the same value as the format name, in this example XML1, as
shown in Figure 6-7. Take care to choose appropriate format names, because
once they are added, formats cannot be deleted from the message set.
Note: You could name and identify your XML physical format as XML if you
wish; this is suggested as a good installation standard, so that if you have
existing MRM messages which specify XML as their RFH2 format, they will
pick up the new XML physical format. However, the use of XML1 here illustrates
that we are specifying an identifier (which we set) and not simply selecting
XML from a pre-defined Control Center list of formats.
169
Figure 6-7 The XML format in the MRM
6.1.3 Creating message elements and types

Next, we will create some elements, in this case four string fields. Right-click the
Elements folder, then select Create -> Element. Name the elements
FIRST_NAME, LAST_NAME, EMAIL_ADDR and LOCATION. You must create one
element at a time. It is again recommended that you set the element identifier to
the same value as the element name. Use the type STRING.
It is not necessary to specify a length value for the element, since we are parsing
variable length delimited messages in this example.
170
Figure 6-8 Creating an element
When you are finished defining all four elements, your Elements folder in the
Control Center should look as shown in Figure 6-9. Do not be concerned about
the order in which the elements appear in the element list; you can re-order the
elements later, in the compound type definition.
171
Figure 6-9 The list of elements
Next, we create a compound type to use in constructing the message. Right-click

the Types folder, then select Create -> Compound Type. A compound type is
similar to a structure. It is used to group elements. Compound types can be used
to build higher level compound types. The highest level compound type is then
used to define the message in the next step. For this simple message type, there
is only one compound type.
172
Figure 6-10 Creating a compound type
Name the compound type; again, we recommend setting the identifier to the
same value, in this example LIST. Set the type content to Closed, as shown in
Figure 6-11. This means that all fields in the message must be defined in the
message type tree structure. An open type content can be useful if you only need
to parse the message partially. The remainder part of the message, for which no
elements are defined, is then considered a BLOB.
173
Figure 6-11 Naming the compound type
Next, we need to add the elements to the compound type. Right-click the
compound type LIST and select Add -> Element.
174
Figure 6-12 Adding elements to the type
The elements previously created are displayed (see Figure 6-13). Select all of
them (hold the CTRL key down while selecting each row in turn) and click Finish.
Figure 6-13 Element names
At this point, your message set should look like that shown in Figure 6-14.
175
Figure 6-14 The compound type
6.1.4 Creating a message using the compound type

Now we can create a message which refers to this compound type. Right-click
the Messages folder, then select Create -> Message. Give the message a name
(in this example, TEST) and select the compound type LIST from the drop-down
menu, as shown in Figure 6-15.
176
Figure 6-15 Creating the message
At this point, you should check in the elements and types of the message set.
Select any element, right-click it and select Check in. The Control Center will
check in the other elements for you at the same time. The check-in process will
store all definitions in the Configuration Managers repository and link the types
to the physical formats that we had defined previously. When the check-in
process is complete, you will see tabs for the new formats when you select
elements or types.
To complete the definition of our message type and set the details of the physical
formats, check out the LIST type and click the TDS1 tab. Change the Data
Element Separation to Variable Length Elements Delimited, because in this
example we want to use variable length comma separated variable data, as
shown in Figure 6-16. Set the delimiter (to a comma) here also, because
otherwise you will get an error when deploying.
177
Figure 6-16 Modifying the type TDS1
Re-order the element fields within the compound type by using the reorder
option in the context menu of the compound type LIST. A window will appear as
shown in Figure 6-17. Set the order to FIRST_NAME, LAST_NAME, EMAIL_ADDR and
LOCATION, in that order, by moving the fields up or down the list as needed, and
click Finish when they are correct.
Figure 6-17 Reordering the elements
178
Check in the type again, as well as the message set, if necessary. Remember to
note the message set identifier, because it needs to be set in the MQInput Node.
The next stage is to develop a message flow to transform a delimited message
into an XML message using the MRM.
6.2 Creating a message flow to convert CSV to XML

Note: It is assumed that the reader has a basic familiarity with the Control
Center and with developing message flows; if not, please refer to the IBM
Manual Using the Control Center SC34-5602.
Create a new message flow (call it CSV_TO_XML). Drag an MQInput node, a

Compute Node and an MQOutput node into the new message flow and wire
them up, connecting the out terminal of each node to the in terminal of the next
one.
6.2.1 Configuring the MQInput node

Set the properties of the MQInput node (use a right-click). Under the Basic tab,
set the name of the input queue (such as WMQI.IN). Select the Default tab and
complete the fields very carefully, as shown in Table 6-1.
Table 6-1 MQInput node properties
Property Name
Value
Description
Message Domain
MRM
Message domain, and

which parser to use.
Message Set
DNTBFL807M001
Use the identifier for your

message set here.
Message Type
TEST
The identifier of the

message (not the
compound type).
Message Format
TDS1

physical format.
Except for Message Type, the MQInput node presents a drop-down box for each
property, as shown in Figure 6-18. For the Message Format, if the name of the
physical format is not the same as the identifier, you should not select the
presented name, but instead type in the identifier.
179
Also, these default values are only used if the input message has no MQRFH2
header. If it does, the same fields in the MQRFH2 should have the values shown
in Figure 6-1.
Figure 6-18 The message flow so far
With this configuration of the MQInput node, the MRM parses input messages
using the delimiter, and populates the MRM message tree, in this case with four
string elements which will be named FIRST_NAME, LAST_NAME,
EMAIL_ADDR and LOCATION.
6.2.2 Configuring the Compute node

The Compute node can then be configured to transform the message to XML by
specifying the new message format for its output message. Compute nodes are
the only type of nodes that modify the message. They construct an output
message, which can be based on some or all of the input message.
180
The Output Message refers to the output of the Compute node and is not
necessarily the final output message from the flow. The actions of the Compute
node are performed by ESQL statements. These can be coded manually or
generated by selecting options in the properties window, or created using a bit of
both methods.
If all the elements are to be transformed to XML and included in the output
message without any other transformation, then you can select Copy Entire
Message in the Compute node properties. Then click the ESQL tab and add this
one additional statement:
Set OutputRoot.Properties.MessageFormat = XML1;
This instructs the MRM (which is the default message domain) to construct the
output message (from the Compute node) using the message format XML1
(which we defined in our message set as an XML physical layer).
Set the MQOutput node to use a queue (such as WMQI.OUT); the queue
manager name can be left to default to the broker queue manager, and other
fields can be left to their default for now.
Selecting individual fields from the input message

This message flow is now perfectly usable for copying all the fields, but for this
example we now configure it to select the MRM fields individually, since it is
possible to select individual fields in the message for transformation. In this case
select Copy Message Headers in the Compute node properties.
1. Next, add the message layouts to both the input and output areas. Click the
Add button on the Inputs side, select the message set and message type.
2. Click the Add button again on the output side and select the same message
set and message type, as shown in Figure 6-19. This simply uses the MRM
definitions to provide a drag and drop method for creating ESQL; it can also
be useful for database tables (on the output side). It is one of the advantages
of defining your messages to the MRM.
181
Figure 6-19 Adding a message to the Compute node
3. Select Use as Message Body on the output side. This generates ESQL to
copy the message set identifier and message identifier, but does not copy any
other fields. You do that by dragging and dropping fields from the input to the
output message in the Compute node properties. After doing this for the first
three fields (leaving out LOCATION in this example), the node properties look
like those shown in Figure 6-20.
182
Figure 6-20 Selecting fields to copy
4. Click the ESQL tab to manually add the two statements at the end of the
ESQL, as shown in bold in Example 6-2:
Example 6-2 Compute node ESQL to transform fields to XML with the MRM
DECLARE I INTEGER;
SET I = 1;
WHILE I < CARDINALITY(InputRoot.*[]) DO
SET I=I+1;
END WHILE;
SET "OutputRoot"."MRM"."FIRST_NAME" = "InputBody"."FIRST_NAME";
SET "OutputRoot"."MRM"."LAST_NAME" = "InputBody"."LAST_NAME";
SET "OutputRoot"."MRM"."EMAIL_ADDR" = "InputBody"."EMAIL_ADDR";
SET OutputRoot.Properties.MessageSet = 'DNTBFL807M001';
SET OutputRoot.Properties.MessageType = 'TEST';
-- Enter SQL below this line. SQL above this line might be regenerated,
causing any modifications to be lost.
Set OutputRoot.Properties.MessageFormat = 'XML1';
Set OutputRoot.Properties.MessageDomain = 'MRM';
183
Message Format refers to the physical format in the message set, which we
called XML1. The message domain would default to MRM, but it is a good
practice to explicitly specify it to avoid confusion with the generic XML
domain.
5. Set the MQOutput node to use a queue such as WMQI.OUT (if you have not
already done this) and then check in your message flow.
6.3 Deploying the message set and flow

1. Select the Assignments tab in the Control Center and check out the broker
and the execution group you want to use. Assign the message set to the
broker and the message flow to the execution group. Check in the broker and
execution group.
Figure 6-21 The assigned message flow and set
2. Deploy the changes to the broker (using either a Delta or a Complete deploy).
184
When adding message sets to a broker, it can be necessary to perform a

complete deploy. However, be careful if you are sharing a broker with other
developers, as the process may take a significant amount of time and may
deploy other changes. Check the Log tab in the Control Center to determine
when the deploy has completed successfully.
If you have made any mistakes in your development so far, the deploy may
not be successful. The log file or the Windows Event Viewer should help you
locate the cause of any problems. When an error is detected in a
tagged/delimited format, the error is recorded in a file named TDS1.log, which
is in the log directory of WebSphere MQ Integrator.
3. The message flow is now running in the broker. If you have not already done
so, create some MQSeries queues using MQSeries Explorer or the command
line utility runmqsc. You may want to create a couple of extra queues that can
be used to send failure messages to. You will then need to update the
message flow by connecting the failure terminals to MQOutput nodes which
use these queues, as shown in Figure 6-18 on page 180.
Figure 6-22 MQSeries Explorer showing local queues
The input count of 1 on the WMQI.IN queue is due to the execution group having
opened this queue for input.
185
6.4 Testing the message flow

1. To generate a test message on the WMQI.IN queue, right-click the queue
name in MQSeries Explorer and select Put Test Message. Enter a simple
four part delimited message, separated by commas, and click OK.
Figure 6-23 Creating a test message
2. There should now be an output message on WMQI.OUT (refresh the queue

display in MQSeries Explorer to check this). If you right-click and select
Browse Messages, you can look at the message contents. You should see a
message like the one shown in Figure 6-24.
186
Figure 6-24 Output message
You have now transformed a comma delimited message into XML using the
MRM. To format the XML message for readability, you could display the data in
Internet Explorer, or another XML-enabled program. Note that the names of the
XML tags are exactly the same as the names of the elements in the MRM. This
may not be what your applications expect, so let us have another look at the XML
physical format definition to control the generation of the XML message.
6.5 Changing XML names in the output

Let us assume that you would like to generate an XML message similar to the
one shown in Example 6-3. The XML name for the element LAST_NAME is now
SURNAME and the element FIRST_NAME has now become GIVEN_NAME.
Example 6-3 Different XML tag names
<?xml version="1.0"?>
<MRM xmlns="www.mrmnames.net/DNTBFL807M001">
<TEST>
<GIVEN_NAME>Fred</GIVEN_NAME>
<SURNAME>Bloggs</SURNAME>
<EMAIL_ADDR>fred@somewhere.com</EMAIL_ADDR>
</TEST>
</MRM>
You can display XML messages easily using the program RFHUTIL, which is part
of SupportPac IH03. SupportPacs can be downloaded from the following Web
site:
http://www-4.ibm.com/software/ts/mqseries/txppacs/txpm1.html
187
This program allows formatted and parsed displays.

Example 6-4 shows the same data shown in Example 6-3, after it has been
parsed by the RFHUTIL program.
Example 6-4 Parsed XML
MRM.(XML.attr)xmlns='www.mrmnames.net/DNTBFL807M001'
MRM
MRM.TEST
MRM.TEST.GIVEN_NAME='Fred'
MRM.TEST.SURNAME='Bloggs'
MRM.TEST.EMAIL_ADDR='fred@somewhere.com'
The output XML tag names can be customized at the element level in the
message. Go to the Message Sets tab in the Control Center and select the
required element. Check out the element, select the XML1 tab, and change the
name, as shown in Figure 6-25.
Figure 6-25 Changing XML names
You can also change the XML tags and attributes on the element properties. You
need to check out the LIST type before doing this, as shown in Figure 6-26.
188
Figure 6-26 Changing XML names or attributes
In Chapter 7, Exploring the new XML features on page 205, we will take a
closer look at the functionality of the XML physical layer and the possible
customization of XML elements and tags.
The XML headers such as DOCTYPE and VERSION can be modified by
checking out the message set and selecting the XML1 tab, as shown in
Figure 6-27.
189
Figure 6-27 Modifying XML header information
You can add further physical layers to the same message set; for example, if you
wanted to output the data as a fixed structure, you could add a Custom Wire
Format layer to the message set, configure it, and refer to this format name in a
Compute node.
You may want to create a new message set for each new pair of formats; this
avoids the constraints of one format definition affecting another. For example, a
delimited format expects an ordered set (meaning that the elements must be in
order in the message), whereas a tagged format could accept an unordered set
(since the tags can identify the values regardless of the order).
Note: It may seem that the ResetContentDescriptor node would transform a
messages format into another format, since you can set the values as
properties, but this is not the case. You must use a Compute node to
transform a message (or part of a message) from one MRM format to another.
190
6.6 Converting a tagged message to XML

In this section, we describe how to transform a tagged message into XML. The
tagged messages structure is as shown in Example 6-5. The tag is followed by
an equal sign (=) and the fields are separated by a semi-colon (;).
Example 6-5 Sample tagged message
Given=John;Surname=Doe;Email=jdoe@nowhere.com;Location=Earth;
The process is similar to the one shown in the previous example, so only the
differences are shown. You could also simply modify the message set and
message flow created for the CSV transformation, rather than create new ones.
Using the same procedures as in the previous example, perform these steps:
1. Create a message set (for example TAGGED_TEST).
2. Add physical formats for tagged/delimited and XML.
3. Create string elements.
4. Create a compound type.
5. Add elements to the compound type.
6. Create a message (using the compound type).
7. Reorder the elements.
Check in the message set, elements and types. We are now ready to configure
the message set to process the tagged data correctly.
6.6.1 Configuring a message set for tagged data

1. Check out the LIST type (or whatever name you gave the compound type).
2. Change the type composition setting to Unordered set. This allows the tags
to occur in any order. The type composition setting can be left to Ordered set
if the tags must be in order and you want an error to be generated if they are
not.
3. Set the type content to Open. This permits message fields other than the
ones defined in the message set to exist without causing errors.
Note: The Control Center online help is the best place to find more detailed
explanations of the various message set fields.
191
The type definition should then look like the one shown in Figure 6-28. Note
that the tagged physical format has been called TAG, both for its name and
identifier, and the XML physical format (not visible in this window) has been
given the name and identifier of XML. Default values for these formats were
used up to this point.
Figure 6-28 Changing the LIST type settings
4. Now click the TAG tab and set the Tag Data Separator to = (an equal sign),
the Data Element Separation to Tagged Delimited and the Delimiter to ; (a
semi-colon). Be careful not to add any spaces after the delimiter unless you
wish these to become part of the delimiter string. Apply the changes.
192
Figure 6-29 Setting the tagged properties
This configures the message set to process tagged data with a delimiter
(rather than fixed length fields) and with a separator between the tag and the
data. An equals sign separates each tag from its data. Each tagged field is
delimited with a semi-colon from the next field.
5. Now expand the LIST type to show the elements within it and check out each
element in turn. For each element, click the TAG tab to set the tag names.
6. Given the message structure shown in Example 6-5 on page 191, we set the
name of the tag for each element. Under the XML tab, you can then provide
the name of the XML tag that you want to assign to each element. Table 6-2
on page 194 provides an overview of all the names.
193
Table 6-2 Element values

Element
Tag
XML name
FIRST_NAME
Given
First
LAST_NAME
Surname
Last
EMAIL_ADDR
Email
Email_Address
LOCATION
Location
Location
Figure 6-30 shows the TAG page for the element FIRST_NAME.
Figure 6-30 Setting the tag values
Figure 6-31 shows the XML page for the same element FIRST_NAME.
194
Figure 6-31 Setting XML names
7. Check in all the elements and the compound type.
6.6.2 Testing the transformation of a tagged message

1. Create a new message flow with an MQInput, Compute and MQOutput node.
Configure the MQInput with the correct values under the default tab, selecting
in particular the TAG format, as shown in Figure 6-32.
Note: The message set, format and the other fields shown here could be
set in the message header (MQRFH2) rather than (or as well as) be coded
in the MQInput default properties. This would be the normal way to control
the way the message was processed. However, for the purposes of our
simple examples, we have used the node default properties rather than set
up an RFH2 header.
195
Figure 6-32 The MQInput node properties
2. Configure the Compute node to Copy entire message and add the two
ESQL lines to set the message format and domain. In this example, the
output message format has an identifier of XML. The properties window
should look like the one shown in Figure 6-33.
Figure 6-33 Compute node properties
3. Now wire the three nodes together and set the MQSeries input and output
queue names as for the previous example.
196
4. Assign the new (or modified) message set to the broker and the message
flow to an execution group. Make sure that you do not have two message
flows running from the same input queue (you can either stop one flow or
remove it from the execution group). Perform a deploy (a complete deploy
may be needed for a new message set).
5. Create a test tagged message on the input queue (for example using
MQSeries Explorer), which uses tags, as shown in Example 6-6.
Example 6-6 Tagged message
Given=John;Surname=Doe;Email=jdoe@nowhere.com;Location=Earth;
The output message is generated in XML format, as shown in Example 6-7.

Example 6-7 XML version
<IBM xmlns="www.mrmnames.net/DNUMQ4G07G001">
<TEST>
<First>John</First>
<Last>Doe</Last>
<Email_Address>jdoe@nowhere.com</Email_Address>
<Location>Earth</Location>
</TEST>
</IBM>
Note that we configured the message set XML tab to suppress the DOCTYPE
declaration and to set the XML root name to IBM (these changes are not required
for the example to work).
The simplest way to view XML messages in a parsed format is to use the
RFHUTIL program to read the queue; this program can also write messages to
queues from files, or from messages previously read. It is part of SupportPac
IH03 and can be downloaded free of charge from the IBM MQSeries Web site.
Try changing the order of the tags in the input message; you will see that it still
works correctly because we specified Unordered set. If we had specified an
ordered set, then changing the input tag order would generate an error.
However, the output message element order reflects the input order. If you want
to predetermine the output order, you can change the Compute node to select
fields individually and the order of assignment of these to the output message will
determine their order in the resulting XML message.
Figure 6-34 shows the Compute node properties that are required to generate
the XML tags in a fixed order regardless of their input order.
197
Figure 6-34 Selecting the output field order
6.7 Using the debugger to examine the message tree

One of the new features in MQSeries Integrator 2.0.2 (and later) is the Message
Flow Debugger. This can be very useful for examining the order and contents of
fields in the message tree before and after a Compute node.
1. To use the debugger, first check in and deploy your message flow normally.
2. Before placing a test message in the input queue, click the Debugger button
in the message flow view. Select Debug Actions-> Open Message Flow
from the top level menu, as shown in Figure 6-35.
198
Figure 6-35 Preparing to debug
3. Expand the tree of brokers and execution groups until you can select your
flow (see Figure 6-36).
Figure 6-36 Selecting a flow
199
4. The message flow appears in the debugging window. You now set
breakpoints where you want the debugger to get control (so you can examine
the message). Do this by right-clicking the connections between nodes. In
this example, we have set breakpoints before and after the Compute node
(see Figure 6-37).
Figure 6-37 Setting breakpoints
5. Select Debug Actions -> Start Debugging. This causes the Control Center
to deploy a modified version of the message flow to the broker. This contains
plug-in nodes for each breakpoint that you set. You will receive a pop-up
message confirming that deployment has been initiated. Check the log view
to confirm completion.
6. Put a test message in the input queue such as the one shown in Example 6-8.
Example 6-8 Tags in different order
Email=jdoe@nowhere.com;Location=Earth;Surname=Doe;Given=John;
Note that the tags have deliberately been set in a different order than desired
for the XML.
200
7. The debugger breakpoint plug-in node intercepts the message as it passes

through the flow and stops processing at that point. The current position in the
flow is indicated by the breakpoint icon (a round dot) turning from blue to red,
Figure 6-38 Breakpoint encountered
8. You can examine the message tree, including any headers, by expanding the
appropriate part of the message content display. You can also modify the field
values (for example changing the name Doe to Smith). To proceed to the next
breakpoint, select Debug Actions -> Step Into or click the Step Into icon.
9. The message flow stops at the next breakpoint and you can see the message
tree after the Compute node; notice the different order of the fields and the
effect of manually changing the data value for one of the fields. Select Step
Into once more and the message will be displayed at the end of the message
flow. You do not need to manually add a breakpoint here for this to work.
10.Notice that the destination list has been completed by the MQOutput node.
Select Run To Completion to commit the message to the queue.
201
Figure 6-39 The final breakpoint
11.Select Debug Actions -> Stop Debugging unless you want to continue with
another input message. Examine the output message with RFHUTIL; you
should see an XML message like the one shown in Example 6-9.
Example 6-9 Output message after debugging
<IBM xmlns="www.mrmnames.net/DNUMQ4G07G001">
<TEST>
<First>John</First>
<Last>Smith</Last>
<Email_Address>jdoe@nowhere.com</Email_Address>
<Location>Earth</Location>
</TEST>
</IBM>
12.If you want to transform XML to tagged messages, you can demonstrate this
with the message set that you have created, using the XML format as the
input and the tagged format as the format set in the Compute node. Place an
202
XML message on the input queue and it will be generated as tagged on the
output.
6.7.1 Importing the Web materials message sets and flows

The message sets and flows for this chapter are supplied as Web materials and
have therefore been exported to XML flat files.
Use this command to import the message sets:
mqsiimpexpmsgset -i -n MQSIMRDB -u db2admin -p db2admin -f DLM_TEST.mrp
Change MQSIMRDB to the name of your Configuration Manager ODBC data

source, if different. Use the appropriate DB2 user ID and password (here shown
as db2admin) for your MRM database.
For the tagged message set import, use the file name TAGGED_TEST.mrp.
Important: The mqsiimpexpmsgset command must execute on the same
Windows NT system on which the Configuration Manager is running. When
you have successfully imported a message set, you must stop the Control
Center and the Configuration Manager and restart them. Your new message
set will then be available to add to your workspace.
To import the message flows, use the Control Center; select File -> Import to
Workspace, then specify the file names TAG_TO_XML.xml or
CSV_TO_XML.xml, which are the exported message flows.
The mqsiimpexpmsgset command has a new operand of -x <xml format name>.
This can be used to add an XML physical format when importing a message set.
This operand is not needed when the exported message set already contains an
XML format. Please see the readme file for WebSphere MQ Integrator 2.1 for
details of when to use the -x operand.
203
204
Chapter 7.
Exploring the new XML

features
In this chapter, we will explore the enhanced support for XML messages. We will
start by importing a DTD, which is a new feature of WebSphere MQ Integrator.
Next, we will look at how we can work with the XML messages that conform to
this DTD. Those XML messages can have attributes and multiple occurrences of
an element.
Because the complete path to an element could be very long, a new ESQL
feature has been introduced: reference variables. These variables can be seen
as short-cuts or abbreviations for long message paths.
Finally, we will also have a look at how the generic XML parser can work with the
sample type of XML message and point out the differences.
205
7.1 Importing an XML DTD and using it in a flow

WebSphere MQ Integrator 2.1 has extended support to include XML options
such as attributes. These new options can be defined manually in the MRM
message set, but it may be more convenient to import an XML DTD, as this is
now possible. Also, quite often, message definitions are published as DTDs by
external organizations or standard bodies. A good example is Open Application
Group Business Object Documents (OAG BODs).
In the following example, we define a new message set, add an XML layer (note
that this is MRM-defined XML rather than generic) and import a DTD. Using this
message set and a simple message flow, we are able to manipulate XML
messages, including setting the XML attributes in a Compute node.
We then look at how to process multiple message elements in a Compute node
and show some differences between the ESQL for MRM XML and the generic
XML.
Tip: The readme file that comes with WebSphere MQ Integrator has some
information about the MRM; this file should be read carefully.
7.1.1 Creating a DTD

An XML DTD (document type definition) is a formal statement of which elements
may appear in an XML message. A DTD lists all the elements, attributes and
entities that the XML document (or message) uses, and the context in which it
uses them.
DTDs are typically used to validate incoming XML documents, but WebSphere
MQ Integrator does not currently support this. However, you can still create MRM
message set definitions by importing a DTD.
In addition to using existing DTDs, it may be faster to create a new DTD to
describe your message, and then import it, than to manually create MRM
elements. DTDs have several options to describe the format of XML elements
and attributes; these are described in XML reference books, or on the Web. For
example, the following URL has information about XML and DTDs:
http://www.xml.com/pub/a/98/10/guide2.html#DOCTYPEDEF
206
DTDs can be transported with the actual XML message, but may also be stored
separately. For the purpose of this example we created a small separate DTD:
Example 7-1 Sample DTD
<!ELEMENT
<!ELEMENT
<!ATTLIST
<!ATTLIST
<!ELEMENT
<!ELEMENT
<!ELEMENT
<!ELEMENT
people (person)+>
person (name, email*)>
person location CDATA #REQUIRED>
person age CDATA #IMPLIED>
name (first,last)>
first (#PCDATA)>
last (#PCDATA)>
email (#PCDATA)>
This DTD defines the people element as consisting of one or more persons.
Each person has a name and zero or more e-mail addresses. Location is an
attribute of person and is required. Age is an attribute of person and is optional.
Each name consists of first and last names (in that order). The first, last and
email elements are PCDATA (Parsed Character Data).
Attributes are associated with elements and appear in the same XML tag as the
element; they can be used for values that occur only once per element. They are
an alternative to using child elements, and XML designers must choose which
method to use. Example 7-2 shows a valid XML message that conforms to this
DTD.
Example 7-2 Sample XML message
<people>
<person location="London" age="35">
<name>
<first>Fred</first>
<last>Bloggs</last>
</name>
<email>fred@nowhere.com</email>
</person>
</people>
Chapter 7. Exploring the new XML features
207
7.1.2 Creating the message set and adding an XML format

Refer to Section 6.1.1, Creating a new message set on page 165 for details on
how to create a new message set and add a physical format.
1. Create a new message set and name it CONTACTS, or any other suitable
name.
2. Add an XML physical format to the new message set and name this format
XML. The format identifier will default to XML also.
3. Check in the message set.
7.1.3 Importing the DTD

1. Create your DTD in a text file. You can cut and paste the sample shown in
Example 7-1. We created a file called example.dtd. This file should be on the
same system as the Control Center.
2. Right-click the message set name and select Import to Message Set ->
DTD.
Figure 7-1 Importing a DTD
208
3. Enter the fully qualified file name of the DTD file that you want to import. If you
prefer, you can browse the file directories to select the file. When you have
entered or selected the file, the name will be displayed as shown in
Figure 7-2:
Figure 7-2 Name of the DTD file
4. Click Next >> to make the importer parse the DTD.

If there any syntactical errors in the DTD an error message dialog is displayed
and the import terminates. Correct the errors and try again.
5. Assuming the file is parsed correctly, the importer displays a list of the
elements contained in the DTD. All these elements are imported as elements
into the message set. However, you can select any of the listed elements to
be imported as messages. In our example, we selected the people element
by clicking it, as shown in Figure 7-4.
This element is chosen because it is the top-level element in the XML tree.
This corresponds to the MRM message type. Selecting an element to add as
a message is an essential step when importing a DTD.
Note: You can generate (or export) a DTD file from an existing message set
definition by selecting the generate -> DTD option in the Control Center.
209
Figure 7-3 List of elements
6. Click >> to add people as an MRM message.
Figure 7-4 Selecting people as message
7. Click Finish to complete the import.
210
Figure 7-5 Completed import
You now have the imported definitions displayed in your message set. Note that
this behavior is different from that using the C or COBOL importer, where the
import function in the Control Center writes the definitions directly to the
Configuration Managers repository. When the import of the C structure is
completed, you need to add the defined message to the workspace. This also
means that the message is verified and correct. The DTD importer adds a
message set to the workspace of the Control Center and not to the Configuration
Managers repository. The result is that some important validation is not
performed. That will only be done when the message definition is checked in. At
that time, the Control Center will communicate with the Configuration Manager
and the Configuration Manager will actually perform the final validations.
211
Figure 7-6 Imported message definitions
7.1.4 Examining the imported message set definitions

1. Check in the people message. This will check in the other elements and types
automatically.
This step is important as it will check that all the element names and
identifiers are acceptable to the MRM. If any duplicates have been created,
you must manually amend these until you are able to check in the message.
This problem will not present itself in our small example DTD, however.
This may also be a reason to create separate message sets, so as to avoid
any name collisions. If you want to import, for example, two OAG BOD DTDs
in the same message set, then you will have elements with the same name,
because every BOD has a common area. Instead of manually removing the
doubles, it is much easier to simply create another message set.
2. Add the new types to your workspace by right-clicking the Types folder and
selecting Add to Workspace -> Compound Types.
212
Figure 7-7 Adding types to the workspace
A list of the compound types appears, as shown in Figure 7-8.
213
Figure 7-8 The list of types
3. Select all of these. You can select multiple rows by holding down the CTRL
key while selecting each row, then click Finish.
This action adds the types to your workspace so that you can examine and
modify them; it does not add them to the message set, because they are
already there.
You can also add the imported elements to the workspace in a similar way.
Right-click the Elements folder and select Add to Workspace -> Elements.
4. Select the elements; they then appear in your workspace. Again, they are
already part of the message set. You are simply making them accessible to
the Control Center.
214
Figure 7-9 Adding the elements
7.1.5 Correcting some of the XML names

This step may not be required, depending on the maintenance level of
WebSphere MQ Integrator 2.1. But if you are using the initial release without any
CSDs applied, you will need to amend some of the XML names that were
generated by the import process.
1. Check out the people message and click the XML tab.
2. Look at the XML name field. If the XML name is m_people, change this value
to people and apply the change. If it is already correctly set, leave it as is.
Check it back in.
Note: The message type identifier in the MRM remains m_people; this
change only affects the XML name.
Figure 7-10 shows the import generated value before correction.
215
Figure 7-10 Correcting the XML name for the message
3. Now expand the Types folder and check out person_attType, age and
location.
4. Click the XML tab and examine the XML names for these attributes. If the
XML name for the age attribute is person_age then change this to age. Do the
same for the location attribute, changing person_location to location.
Note: The MRM element names used in ESQL remain person_location
and person_age; we are amending only the external XML name.
Figure 7-11 shows the age attribute after correcting the XML name. Note that
the XML name appears and is changed in two places.
The other XML names should all be correct; you only need to amend the XML
names for the message type and any attributes, but it is a good idea to check
the others if you have problems with parsing or generating XML messages.
With later releases, these amendments should not be required.
216
Figure 7-11 Corrected XML name for age
Table 7-1 summarizes the values that were generated by the importer and
values that should have been set.
Table 7-1 XML names
Type name
Imported XML name
Correct XML name
people (message)
m_people
people
location (type)
person_location
location
age (type)
person_age
age
Notice that two compound types have been generated for person; one
contains the attributes (person_attType) and the other contains the child
elements (person_cmType).
217
Attributes and child XML elements are grouped in two types, because they
have different sequencing requirements. Attributes can be in any order.
Therefore, the type person_attType has Simple Unordered Set as value for
the field Type Composition. XML elements should appear in a certain order.
Therefore, the type person_cmType has Sequence as value for the field Type
Composition.
5. Check in the types that were checked out. We now have a good message
type.
7.2 Using the message set in a flow

1. Create a new message flow (call it CONTACT_FLOW). Drag an MQInput
node, a Compute Node and a MQOutput node into the new message flow and
wire them up, connecting the out terminal of each node to the in terminal of
the next.
2. Set the properties of the MQInput node by right-clicking the Basic tab, and
set the name of the input queue (such as WMQI.IN). Select the Default tab
and complete the fields as shown in Table 7-2.
Table 7-2 MQInput node properties
Property Name
Value
Description
Message Domain
MRM
Message Domain (and the

parser to use).
Message Set
DNUMQ4G07O001
Use the identifier for your

message set here.
Message Type
m_people
The MRM identifier of the

message type.
Message Format
XML

physical format.
7.2.1 Configuring the Compute node

We now use a Compute node to examine and amend an XML message as it
passes through the message flow. We look for a location attribute equal to London
and change it to Boston. The other elements will be passed through.
In a similar way to that shown in Section 6.2.2, Configuring the Compute node
on page 180, you can add the message layout to the Compute nodes properties
for input and output. This enables the use of drag and drop to manipulate
elements.
218
1. The message set name is CONTACTS and the message name is people.
Select the checkboxes Use as message body and Copy message headers.
The properties page now looks like that shown in Figure 7-12.
2. Expand the message tree on the input and output side. Drag and drop the
following elements in this sequence from the input side to the same
element/attribute name on the output side:
person_age
person_location
first
last
email
This sequence matches the order in which the elements were defined in the
DTD, and therefore the order of the elements in the message set. When
constructing the output message, the MRM expects to process the elements
in the same order; if they are assigned out of sequence, an error occurs, as
shown in Section 7.2.5, Some possible errors on page 227.
219
Figure 7-13 The message tree
3. To generate the message field tree layout for the input and output message,
just click the Add button and select the CONTACTS message set and people
message.
4. After dragging and dropping the five fields, the mappings area should be
similar to the one shown in Figure 7-14. You can correct any mistakes by
deleting the mappings and re-creating them.
Figure 7-14 The field mappings
220
The generated ESQL, including the statements needed for copying the
message header, is shown in Example 7-3.
Example 7-3 Generated ESQL code
DECLARE I INTEGER;
SET I = 1;
SET I=I+1;
END WHILE;
SET "OutputRoot"."MRM"."person"."person_age" =
"InputBody"."person"."person_age";
SET "OutputRoot"."MRM"."person"."person_location" =
"InputBody"."person"."person_location";
SET "OutputRoot"."MRM"."person"."name"."first" =
"InputBody"."person"."name"."first";
SET "OutputRoot"."MRM"."person"."name"."last" =
"InputBody"."person"."name"."last";
SET "OutputRoot"."MRM"."person"."email" = "InputBody"."person"."email";
SET OutputRoot.Properties.MessageSet = 'DNUMQ4G07O001';
SET OutputRoot.Properties.MessageType = 'm_people';
-- Enter SQL below this line.
When analyzing the statements, it becomes clear that there is no difference in

the way you address attributes and elements. They all appear to be fields of a
grouping structure.
5. Next, add these additional lines manually at the bottom of the ESQL. These
specify the message domain and format for the output message.
Set OutputRoot.Properties.MessageFormat = 'XML';
This message flow can now be checked in; currently coded, it will not modify
the message contents, but it is advisable to test everything developed up to
now.
7.2.2 Testing the message flow

1. Create a text file with a sample XML message. You can cut and paste the
sample message shown previously in Example 7-2. Remove all white space
outside of tags and carriage returns from the file. Using Windows Notepad,
the data should appear on a single line if word-wrap is turned off.
2. Deploy the new message set and message flow to the broker, making sure
they are fully checked in first. Refer to Section 6.6.2, Testing the
transformation of a tagged message on page 195 for details on how to
221
perform this. Make sure you do not have two flows using the same input
queue.
3. The easiest way to repeatedly test the message flow is to use the RFHUTIL
program from SupportPac IH03. This program can read a message from a file
and then put it to a queue. It can also get a message from a queue and
display it in various ways.
Use RFHUTIL to read the message file, then make sure that there are no
extraneous spaces outside of tags by viewing the data display tab (please
refer to the documentation that comes with the SupportPac for details on how
to use this program). Send the data to queue WMQI.IN (or whatever you have
configured the input queue name to be).
The message flow should process the message and generate an output XML
message on the queue WMQI.OUT; get the message from this queue using
RFHUTIL. It should look like that shown in Example 7-4:
Example 7-4 Output XML message
<MRM xmlns="www.mrmnames.net/DNUMQ4G07O001">
<people>
<person age="35" location="London">
<name>
<first>Fred</first>
<last>Bloggs</last>
</name>
</person>
</people>
</MRM>
Notice that the MRM has inserted a tag into the message but that it is
otherwise identical to the input message. In the next section, we will modify
the message in the Compute node.
7.2.3 Modifying the message in the Compute node

1. Check out the message flow and open up the Compute node properties. Add
these three lines of ESQL to the bottom of the ESQL tab:
If "InputBody"."person"."person_location" = 'London' then
Set "OutputRoot"."MRM"."person"."person_location" = 'Boston';
end if;
You can use the drag and drop statement and field assignment feature to help
construct these ESQL lines by dragging statements and element names into
the ESQL code where they are needed.
222
Restriction: If you have WebSphere MQ Integrator 2.1 without any CSDs

applied, the add mapping button will generate incorrect MRM ESQL, such as:
"MRM"."t_people_cmType"."person"."t_person_cmType"."name".
2. Check in the message flow and test it again with the example message.
3. The output message now has the location set to Boston; test it again with a
different location set in the input message to make sure the conditional logic
is working correctly.
Notice that the name used to refer to attribute fields in ESQL is not the same
name as used for the generated XML name in the tags, whereas the other
elements have their ESQL name matching their XML tag names, as shown in
Table 7-3.
Table 7-3 XML names versus MRM names
Parsed XML format
MRM ESQL name
MRM.people.person.(XML.attr)location
"MRM"."person"."person_location"
MRM.people.person.name.first
"MRM"."person"."name"."first"
MRM.people.person.email
"MRM"."person"."email"
We have now created a message set from a DTD and used it to process and
manipulate an XML message, with the MRM parsing the input and generating the
output message.
The remainder of this chapter looks at variations and caveats along with common
problems and how to diagnose them; this will help you in case you were not able
to make this example work the first time.
7.2.4 Problem solving with this flow

If the message flow has a problem with a message, this message may get rolled
back into the input queue. If you examine the backout count with MQSeries
Explorer, you can see whether the message flow has been attempting to process
the same message over and over without success. You can avoid this rollback by
setting the MQinput node properties (Advanced -> Transaction mode) to No.
However, this does not help diagnose the problem. One way to do this is to insert
Trace nodes into the flow and also to wire up the failure terminals.
Details on how to use Trace nodes and format and read the user trace file can be
found in the IBM manual Using the Control Center, SC34-5602.
223
We set up our Trace nodes with properties as shown in Figure 7-15:
Figure 7-15 Trace node properties
This writes the message tree and exception list to the user trace file. You could
instead choose to specify a file destination. However, the user trace allows us to
see WebSphere MQ Integrator errors as well as our message data in one place.
With Trace nodes and extra MQOutput nodes for failure queues, the message
flow now looks as shown in Figure 7-16.
Figure 7-16 Message flow with Trace nodes
User tracing for the CONTACT_FLOW message flow itself is activated with this
line command, issued on the broker system.
mqsichangetrace zpat -u -e default -f CONTACT_FLOW -l debug -r -c50000
Replace zpat with the name of the broker; default is the name of the execution
group to which the message flow is deployed. The message flow is then tested
and the trace log can be read and formatted with these commands (again
substituting your broker and execution group names). Delete any prior log and
.txt files before re-running the following commands.
224
mqsireadlog zpat -u -e default -o CONTACT_FLOW.log

mqsiformatlog
-i CONTACT_FLOW.log -o CONTACT_FLOW.txt
notepad CONTACT_FLOW.txt
The following is the user trace of a valid MRM parsed message

Example 7-5 User trace after MQInput
UserTrace BIP4060I: Data '(
(0x1000000)Properties = (
(0x3000000)MessageSet
= 'DNUMQ4G07O001'
(0x3000000)MessageType
= 'm_people'
(0x3000000)MessageFormat
= 'XML'
(0x3000000)Encoding
= 546
(0x3000000)CodedCharSetId = 437
(0x3000000)Transactional
= FALSE
(0x3000000)Persistence
= FALSE
(0x3000000)CreationTime
= GMTTIMESTAMP '2001-11-28 19:41:19.733999'
(0x3000000)ExpirationTime = -1
(0x3000000)Priority
= 0
(0x3000000)ReplyIdentifier = X'000000000000000000000000000000000000000000000000'
(0x3000000)ReplyProtocol
= 'MQ'
(0x3000000)Topic
= NULL
)
(0x1000000)MQMD
= (
(0x3000000)SourceQueue
= 'WMQI.IN'
= FALSE
(0x3000000)Encoding
= 546
(0x3000000)CodedCharSetId
= 437
(0x3000000)Format
= '
'
(0x3000000)Version
= 2
(0x3000000)Report
= 0
(0x3000000)MsgType
= 8
(0x3000000)Expiry
= -1
(0x3000000)Feedback
= 0
(0x3000000)Priority
= 0
= 0
(0x3000000)MsgId
= X'414d51207a7061742020202020202020dbde043c52f00100'
(0x3000000)CorrelId
= X'000000000000000000000000000000000000000000000000'
(0x3000000)BackoutCount
= 0
(0x3000000)ReplyToQ
= '
'
(0x3000000)ReplyToQMgr
= 'zpat
'
(0x3000000)UserIdentifier
= 'zpat
'
(0x3000000)AccountingToken =
X'16010515000000f89fb4741851496443170a32e803000000000000000000000b'
(0x3000000)ApplIdentityData = '
'
(0x3000000)PutApplType
= 11
(0x3000000)PutApplName
= 'C:\MQSeries\bin\rfhutil.exe '
225
(0x3000000)PutDate
= DATE '2001-11-28'
(0x3000000)PutTime
= GMTTIME '19:42:51.310'
(0x3000000)ApplOriginData
= '
'
(0x3000000)GroupId
= X'000000000000000000000000000000000000000000000000'
(0x3000000)MsgSeqNumber
= 1
(0x3000000)Offset
= 0
(0x3000000)MsgFlags
= 0
(0x3000000)OriginalLength
= -1
)
(0x1000008)MRM
= (
(0x1000001)person = (
(0x3000001)person_location = 'London'
(0x3000001)person_age
= '35'
(0x1000001)name
= (
(0x3000012)first = 'Fred'
(0x3000012)last = 'Bloggs'
)
(0x3000012)email
= 'fred@nowhere.com'
)
)
)
The important part of this user trace is the MRM tree at the end. If this does not
appear, then the broker has been unable to parse the message on input and the
log file should contain an error code, which may indicate the reason for it.
Conversely, if the input message has been successfully parsed but the output
message is not generated, examine the user trace after the Compute node. The
MRM tree here is used to construct the output message and any errors in it,
including sequence errors which can cause a failure.
Example 7-6 User trace after Compute node, MRM portion only
(0x1000008)MRM
= (
(0x1000000)person = (
= '35'
(0x3000001)person_location = 'Boston'
(0x1000000)name
= (
)
(0x3000012)email
)
)
226
7.2.5 Some possible errors

While the new XML support is easy to use, there are a few possible problems to
watch out for.
Invalid input XML

Remove the <people> and </people> tags from the example message as shown
in Example 7-2 on page 207, and put the message into the input queue. This
XML message, although well-formed, is not valid for this message set. The user
trace has an empty MRM tree and contains the following error message (see
Example 7-7).
Example 7-7 Trace with invalid XML
2001-11-28 15:07:21.430000
1944 Error
BIP2628E: Exception condition
detected on input node 'CONTACT_FLOW.WMQI.IN'.
The input node 'CONTACT_FLOW.WMQI.IN' detected an error whilst processing a
message. The message flow has been rolled-back and, if the message was being
processed in a unit of work, it will remain on the input queue to be processed
again. Following messages will indicate the cause of this exception.
Check the error messages which follow to determine why the exception was
generated, and take action as described by those messages.
2001-11-28 15:07:21.430000
1944 ImbTraceNode::evaluate
2001-11-28 15:07:21.430000
1944 MtiImbParser::parseFirstChild ,
startMessageContent has been passed a different messageName to what has already
been specified
This XML message would have been parsed easily by the generic XML parser.
Creating output elements out of sequence

Because the message type has been defined as an ordered set, the output
elements must be created in the same sequence in the Compute node as they
should appear in the message. For example, if you assign last before first in the
Compute node, the MRM tree will appear in the order shown in Example 7-8 on
page 228.
227
Example 7-8 Order not matching message set

(0x1000008)MRM
= (
(0x1000000)person = (
= '35'
(0x3000001)person_location = 'Boston'
(0x1000000)name
= (
)
(0x3000012)email
)
)
This will cause a failure in the MQOutput node when the broker tries to build the
physical message from the message tree. Example 7-9 shows what error
messages you might see in the user trace.
Example 7-9 User trace with sequence error
2001-11-28 15:53:27.416999
1944 Error
BIP5286E: Message Translation
Interface Writing Errors have occurred.
Errors have occurred during writing.
Review further error messages for an indication to the cause of the errors.
2001-11-28 15:53:27.447000
1944 Error
BIP2628E: Exception condition
detected on input node 'CONTACT_FLOW.WMQI.IN'.
The input node 'CONTACT_FLOW.WMQI.IN' detected an error whilst processing a
message. The message flow has been rolled-back and, if the message was being
processed in a unit of work, it will remain on the input queue to be processed
again. Following messages will indicate the cause of this exception.
Check the error messages which follow to determine why the exception was
generated, and take action as described by those messages.
2001-11-28 15:53:27.447000
1944 ImbMqOutputNode::evaluate
2001-11-28 15:53:27.447000
1944 MtiImbParser::subSyncWithDictionary ,
DNUMQ4G07O001, first
If you see this sort of message, it is caused by the MRM encountering an

element name which should have preceded an element already processed in the
XML tree. This does not occur when the attributes of the same element name
appear in a different order. You will remember that the attribute list compound
type was defined as an unordered set.
One way to avoid out of sequence fields in a message tree is to initialize them or
use the CREATE keyword at the start of the ESQL in the correct order.
228
Other log files

When a physical format is processed during the deploy, log files are created in
the WebSphere MQ Integrator log directory. These include a text version of the
XML wire format.
The default directory name is:
C:\Program Files\IBM\WebSphere MQ Integrator 2.1\log\
If the format is named XML, then you should see three files named XML.txt,
XML.trc and XML.log. You do not have to examine these, but they may indicate
the reason for any deploy time error. Similar log files are produced for other wire
formats.
Reading the text format of the XML is a good way to quickly scan imported DTDs
to check that the XML names are as expected, especially when a large number
of fields exist.
Since these log files can be overwritten by other physical formats using the same
name in different message sets, you should rename or copy them somewhere
else if you want to refer to them at a later date.
7.3 Some more advanced features

7.3.1 Processing multiple persons in a single message
So far, we have assumed that only one person element is present in the input
message, but our DTD specified that multiple occurrences of the element person
are valid. So our input message might look like that shown in Example 7-10:
Example 7-10 XML message with multiple person elements
<people>
<person location="London" age="35">
<name>
<first>Fred</first>
<last>Bloggs</last>
</name>
</person>
<person location="Edinburgh" age="44">
229
<name>
<first>John</first>
<last>Smith</last>
</name>
<email>John@somewhere.com</email>
</person>
</people>
If left unchanged, the Compute node would only generate a single output person
element as before. To allow for more than one person, we can amend the ESQL
in the Compute node as follows:
1. Edit the ESQL and make a copy of the five automatically generated field
assignment statements that the mappings created.
2. Delete the mappings; this removes their generated ESQL.
3. Paste the statements back, but in the user modified ESQL area, below the
line, and then modify them to operate in a loop with an array subscript.
The code shown in Example 7-11 is the complete ESQL from the Compute node;
this version will iterate through multiple occurrences of the person element and
therefore the output message will also contain multiple person elements. You can
see where the variable J has been used as an array subscript.
The first loop is the WebSphere MQ Integrator generated one from using the
Copy the message header option, but this does not copy the body. Then the Use
as message body option generates the assignments for the message set identifier
and message type. We then set the output message format and domain, and
iterate through the person elements, performing our processing on each one in
turn.
This iteration is implemented within a single message; the flow would be invoked
again if multiple MQSeries messages were involved.
Example 7-11 Processing multiple person elements
DECLARE I INTEGER;
SET I = 1;
SET I=I+1;
END WHILE;
230
DECLARE J INTEGER;
SET J =1;
WHILE J <= CARDINALITY("InputBody".*[]) DO
SET "OutputRoot"."MRM"."person"[J]."person_age" =
"InputBody"."person"[J]."person_age";
SET "OutputRoot"."MRM"."person"[J]."person_location" =
"InputBody"."person"[J]."person_location";
SET "OutputRoot"."MRM"."person"[J]."name"."first" =
"InputBody"."person"[J]."name"."first";
SET "OutputRoot"."MRM"."person"[J]."name"."last" =
"InputBody"."person"[J]."name"."last";
SET "OutputRoot"."MRM"."person"[J]."email" = "InputBody"."person"[J]."email";
If "InputBody"."person"[J]."person_location" = 'London' then
Set "OutputRoot"."MRM"."person"[J]."person_location" = 'Boston';
end if;
SET J = J + 1;
END WHILE;
If you want to generate separate output messages for each loop of an input
person element, you can use the new PROPAGATE statement. This causes the
message tree to be immediately sent on the out terminal, without the node
terminating. The message tree is then cleared and so needs to be fully set up in
each loop. As per our test message from Example 7-10 on page 229, two
MQSeries messages are created, one for each person element.
When using PROPAGATE, you would normally end the node ESQL with RETURN
FALSE; to suppress the automatic send of the message tree at the end of the
node. It is actually good practice to explicitly code RETURN TRUE; at the end of the
ESQL in all the Compute nodes when you do not explicitly code a PROPAGATE
statement.
Example 7-12 Generating multiple messages
DECLARE J INTEGER;
SET J =1;
DECLARE I INTEGER;
SET I = 1;
SET I=I+1;
END WHILE;
SET "OutputRoot"."MRM"."person"."person_age" =
231
SET "OutputRoot"."MRM"."person"."person_location" =
SET "OutputRoot"."MRM"."person"."name"."first" =
SET "OutputRoot"."MRM"."person"."name"."last" =
SET "OutputRoot"."MRM"."person"."email" = "InputBody"."person"[J]."email";
PROPAGATE;
SET J = J + 1;
END WHILE;
RETURN FALSE;
7.3.2 Using generic XML

The new MRM features and the DTD import relate to MRM-defined XML, but you
can still use generic XML. You might want the input message to be MRM-defined
but the output message to be generic XML. In this case, you do not need to
specify an output message set or format, but simply the message domain of XML.
Amending the Compute node to generate a generic XML message requires the
ESQL shown in Example 7-13 (only the ESQL below the line is shown). The Use
as message body option is also deselected. The previous if-then logic has been
omitted for clarity but could easily be included if necessary.
Example 7-13 ESQL for generic XML output
Set OutputRoot.Properties.MessageDomain = 'XML';
SET OutputRoot.XML.(XML.XmlDecl)='';
SET OutputRoot.XML.(XML.XmlDecl).(XML.Version)='1.0';
DECLARE J INTEGER;
SET J =1;
SET "OutputRoot"."XML"."people"."person"[J].(XML.attr)age =
SET "OutputRoot"."XML"."people"."person"[J].(XML.attr)location =
SET "OutputRoot"."XML"."people"."person"[J]."name"."first" =
SET "OutputRoot"."XML"."people"."person"[J]."name"."last" =
SET "OutputRoot"."XML"."people"."person"[J]."email" =
"InputBody"."person"[J]."email";
SET J = J + 1;
END WHILE;
232
It is worth contrasting the way the XML attributes are generated in MRM XML
and generic XML.
With MRM-defined XML, an attribute is set with ESQL code like this:
SET "OutputRoot"."MRM"."person"[J]."person_age" =
The MRM knows that this field is an attribute and will generate the appropriate
XML automatically, whereas with generic XML, you need to be more explicit, like
this:
SET "OutputRoot"."XML"."people"."person"[J].(XML.attr)age =
Also, it is necessary to explicitly generate the XML header with the following
code:
Even with generic XML, the order of creating parts of the XML message is
important to avoid the generation of invalid XML.
It is also important to create any new message headers such as the MQMD or
MQRFH2 before creating body elements in the ESQL; otherwise, the message
parser may simply treat them as additional body elements.
For more information on generic XML and ESQL, refer to the IBM manual ESQL
Reference, SC34-5923. This manual is supplied with WebSphere MQ Integrator
V2.1.
7.3.3 Using ESQL reference variables

As shown in Example 7-13, ESQL statements can become lengthy. A new ESQL
feature is reference variables; these can be used to simplify the navigation of
complex message trees. Their use is not confined to working with the MRM or
XML, but we will show how they can simplify ESQL by amending our example
which outputs MRM XML messages.
Reference variables can be used as a short notation for fully qualified field
names and can also act as cursors or pointers into an array of element instances.
This avoids the need for array index variables and makes the ESQL code easier
to read and understand.
233
Important: The following note is provided in the readme file that comes with
WebSphere MQ Integrator 2.1.
Changes were made to the syntax of the CREATE, MOVE and SET
statements primarily to avoid ambiguity of meaning. These changes were not
fully reflected in the manual ESQL Reference, SC34-5923-01.
The readme file goes on to document the correct syntax.
The code sample shown in Example 7-14 is the complete ESQL from the
Compute node after having been amended to use reference variables. Some
points to note:
Elements need to exist before they can be referred to, so use the CREATE or
SET statement to make sure they exist (but do so in sequence, if required).
MOVE is used to increment the reference to the next element, but you cannot
use MOVE unless the element exists, so use CREATE for any new element
first.
Avoid creating a new output element after processing the last input element
by testing the LASTMOVE operation result.
Use the user trace facility or the debugger to examine the MRM tree before
and after the Compute node to make sure that the results are as expected.
Example 7-14 Using reference variables
DECLARE I INTEGER;
SET I = 1;
SET I=I+1;
END WHILE;
DECLARE ptrin REFERENCE to "InputBody"."person"[1];
CREATE FIELD "OutputRoot"."MRM"."person"[1] FROM ptrin;
DECLARE ptrout REFERENCE to "OutputRoot"."MRM"."person"[1];
WHILE LASTMOVE(ptrin) DO
/* while ptrin is within tree */
SET ptrout."person_age"
= ptrin."person_age";
SET ptrout."person_location" = 'Raleigh';
SET ptrout."name"."first"
= ptrin."name"."first";
234
SET ptrout."name"."last"
= ptrin."name"."last";
SET ptrout."email"
= ptrin."email";
MOVE ptrin NEXTSIBLING; /* move ptrin to next input person */
IF LASTMOVE(ptrin) THEN
/* if move was still inside tree */
CREATE NEXTSIBLING OF ptrout FROM ptrin; /* create next output person */
MOVE ptrout NEXTSIBLING; /* refer to next output person */
END IF;
END WHILE;
This code is only meant as an example. If you really want to amend only one
field, you should copy the input message at a higher level and then amend it.
SET ptrout = ptrin;
SET ptrout."person_location" = 'Raleigh';
Copying the entire structure all at once also has the advantage of ensuring that
the sequence of fields will be the same in the output message as it is in the input
message. As we have seen, it is essential to create fields in the correct sequence
when using a compound type defined as an ordered set (or sequence).
However, if you use the ESQL statement SET "OutputRoot" = "InputRoot"; and
then do not subsequently modify any of the message elements, the parser
directly copies the input bitstream to the output bitstream without regenerating it;
this means that attributes in the output wire format layer will not take effect.
Remember, when creating or modifying headers such as the MQMD, that a
message set definition for this (and other headers) is supplied with WebSphere
MQ Integrator and can be added to your workspace, then used with the drag and
drop feature of the Compute node.
It is possible for the Compute node to report a ESQL syntax error when the
statement is valid. For example, the following statement is flagged, but is correct:
SET OutputRoot.MQRFH2.mcd.Set = OutputRoot.Properties.MessageSet;
235
7.3.4 Importing the Web materials message set and flows

The message sets and flows for this chapter are supplied as Web materials. Use
this command to import the message set:
mqsiimpexpmsgset -i -n MQSIMRDB -u db2admin -p db2admin -f CONTACTS.mrp
Change MQSIMRDB to the name of your configuration manager ODBC data

source, if different. Use the appropriate DB2 user ID and password for that
database.
Important: The mqsiimpexpmsgset command must execute on the same
Windows NT system that the Configuration Manager is running on. When you
have successfully imported a message set, you must stop the Control Center
and the Configuration Manager and restart them. Your new message set will
then be available to add to your workspace.
To import the message flows, use the Control Center; select File -> Import to
Workspace, then specify the file name CONTACT_FLOW.xml which is the exported
message flow.
CONTACT_FLOW_basic, _generic, _propagate and _reference.xml are the other
variations of the same flow.
The example DTD and test message are also supplied.
236
Chapter 8.
Migration of solutions based

on New Era Of Networks
functionality
This chapter provides an overview of the New Era Of Networks support that
comes with WebSphere MQ Integrator. We look at how you can use existing New
Era Of Networks rules and formats with the new version and how to move from a
rules engine environment to a broker environment.
We list and discuss the migration steps associated with supporting New Era Of
Networks in general, and give a detailed step-by-step example for a New Era Of
Networks migration as it is necessary, when you upgrade from MQSeries
Integrator V2.0.1 to WebSphere MQ Integrator.
Furthermore, we show some of the enhanced functionality of working with New
Era Of Networks messages in the new WebSphere MQ Integrator environment,
in comparison to working in an MQSeries Integrator V2.0.1 environment.
Note that this chapter covers distributed platforms (Windows and UNIX) only. It
does not consider z/OS, where the broker component and New Era Of Networks
support is available as well.
237
8.1 New Era Of Networks support

In April of 1999, IBM introduced MQSeries Integrator V1.0 as an additional part
of the business integration family, complementing MQSeries and MQSeries
Workflow, followed by MQSeries Integrator V1.1 just two months later in June of
1999.
The first versions of the product were published fully compatible with NeoNet, a
product developed by New Era Of Networks, labeled by IBM using a different
brand: MQSeries Integrator.
The architecture of the early V1.x products is completely different from that of the
current V2.x products. MQSeries Integrator V1.x consists of the following
development and runtime components (see Figure 8-1:)
Formatter GUI
Rules GUI
Database to store meta-data
Rules Daemon, also called Rules Engine
Figure 8-1 MQSeries Integrator V1.x components
238
MQSeries Integrator V2.x implements significant improvements, but the early

versions did not offer a support for tagged and delimited messages (for example
S.W.I.F.T., Siebel, EDI, SAP). These formats, however, were supported by relying
on New Era Of Networks functionality.
Tagged and delimited messages are supported with WebSphere MQ Integrator
now. However, New Era Of Networks is still supported for compatibility reasons.
Customers may have a large investment in New Era Of Networks formats and
rules.
Whereas IBM is carrying on with its own MQSeries Integrator architecture (now
re-labeled as WebSphere MQ Integrator), New Era Of Networks is proceeding
with the development of e-Biz Integrator, which is the current product brand.
However, the improvements to this product are continuously included with
MQSeries Integrator and WebSphere MQ Integrator.
Table 8-1 on page 239 provides a summary of the supported New Era Of
Networks versions with MQSeries Integrator/WebSphere MQ Integrator. The
following sections give a brief overview of the enhancements that come with the
different versions.
Table 8-1 MQSeries Integrator - NEON compatibility matrix
MQSeries Integrator/
New Era Of Networks
MQSeries Integrator V1.0
New Era Of Networks V4.0.1
MQSeries Integrator V1.1, V2.0, V2.0.1
New Era Of Networks V4.1.1
New Era Of Networks V5.2
New Era Of Networks V5.6
8.1.1 MQSeries Integrator V1.0 and V1.1

Based on a real-time, rules-based message routing architecture, these early
MQSeries Integrator versions offered:
Dynamic message content transformation and formatting
Application-to-application message transformation
Support for custom built and predefined application libraries
Support in handling tagged and delimited formats (for example PeopleSoft
GL, SAP R/3, S.W.I.F.T.)
MQSeries Integrator V1.0 implements New Era Of Networks V4.0.1. and

MQSeries Integrator V1.1 implements New Era Of Networks V4.1.1.
Chapter 8. Migration of solutions based on New Era Of Networks functionality
239
8.1.2 MQSeries Integrator V2.0 and V2.0.1

Version 2.0 of MQSeries Integrator offers a completely different system
architecture compared to MQSeries Integrator V1.x. Based on dedicated system
components (Control Center, Configuration Manager, Broker, User Name
Server), it is possible to build more complex and distributed development and
runtime environments split between a variety of physical platforms.
Working on messages is based on a logical message model, where the logical
and physical description of messages is stored in a message repository.
The V1.x functionality of the MQSeries Integrator (New Era Of Networks support)
comes embedded through an MQSeries Integrator rules broker, a generic server
process that supports messages, whose logical and physical description has
been defined outside the message repository in the New Era Of Networks
environment via the New Era Of Networks Formatter GUI and the New Era Of
Networks Rules GUI.
Version 2.0.1 of MQSeries Integrator comes with some improvements to the
native functionality. There were no significant changes to the implemented New
Era Of Networks support. Both versions implement New Era Of Networks V4.1.1.
The integration of the New Era Of Networks functionality in these versions of
MQSeries Integrator is most visible as the availability of two message processing
nodes called NeonFormatter and NeonRules. As we will show in 8.4, Working
on New Era Of Networks messages on page 289, these nodes make it possible
to continue to use your existing rules and formats. However, message flows that
process New Era Of Networks messages cannot really exploit the other
functionality of MQSeries Integrator.
8.1.3 MQSeries Integrator V2.0.2

With MQSeries Integrator V2.0.2, the New Era Of Networks support has been
enhanced over previous versions of MQSeries Integrator and is based on New
Era Of Networks V5.2.
Part of the enhanced functionality is the implementation of explicit Map objects.
Map objects are defined in the NEONFormatter User Interface and provide a
mechanism for explicitly mapping input message fields to output message fields.
These Map object definitions are accessible from within the newly introduced
NEON nodes: NEONTransform, NEONMap, NEONRulesEvaluation. The major
difference here is that you can now process New Era Of Networks messages in a
message flow and exploit the rest of the functionality of MQSeries Integrator,
such as Database nodes and Compute nodes.
240
8.1.4 WebSphere MQ Integrator

WebSphere MQ Integrator implements New Era Of Networks V5.6 functionality.
From a WebSphere MQ Integrator perspective, the use of this new New Era Of
Networks version has some implications for configuration.
The integration of New Era Of Networks within WebSphere MQ Integrator is
shown in Figure 8-2. The Configuration Manager has, of course, the task of
managing its Message Repository and its configuration database. The
Configuration Manager also has a read-only view of the New Era Of Networks
database. As a consequence, when you use the Control Center to build message
flows that process New Era Of Networks messages, you can actually see the
structure of the message and use it as if it were an MRM message.
However, to maintain or create new New Era Of Networks formats and rules, you
still need to use the New Era Of Networks interface programs, which can be
launched from within the Control Center.
NNSY gui
Rules and Formats

Development
Message Flow
Development
NN
SY
NNSY
Database
Config
Manager
MRDB
La
un
ch
Java Client
Control
Center
CMDB
Runtime
Broker
BKDB
ODBC Connection
Figure 8-2 New Era Of Networks architecture in WebSphere MQ Integrator
241
The broker itself has, of course, the task of managing its broker database, but it
also has a connection to the New Era Of Networks database which is required
when the broker needs to know about the New Era Of Networks rules and
formats.
This architecture no longer refers to the Rules Engine or Daemon, as shown in
Figure 8-1 on page 238.
8.2 Summary of changes

There are a few changes, improvements and enhancements that have been
made by supporting New Era Of Networks with the different versions of
MQSeries Integrator V2.x, affecting:
Configuration
Environment
Functionality
8.2.1 Configuration
Besides the installation of the New Era Of Networks product code and the
installation of the database management system, setting up the New Era Of
Networks support requires a few configuration steps, which are similar with all
versions of MQSeries Integrator/WebSphere MQ Integrator.
These steps are:
Creating a database for use with New Era Of Networks
Depending on the database vendor:
Creating user defined segments (Sybase and SQLServer)

Creating tablespaces (DB2 and Oracle)
Defining an ODBC-connection to the database (DB2)
Installing the database schema
Creating a database connection file
Depending on your requirements:
Setting up authorizations to the database

Setting up a client/server connection to the database
Setting up development and runtime environment
242
MQSeries Integrator V2.0 and MQSeries Integrator V2.0.1

With MQSeries Integrator V2.0 and V2.0.1, most of the configuration steps have
to be performed manually, except for the installationof the database schema,
which is provided by a script, called inst_db.

With MQSeries Integrator V2.0.2, the initial configuration procedure is more
comprehensive and is supported by the installation application inst_db. Running
inst_db:
Creates a configured and prepared database for use with the New Era Of
Networks tools.
Creates an ODBC connection to the New Era Of Networks database (if you
run DB2).
Creates a database connection file called neonreg.dat.
As with the previous version 2.0.2, WebSphere MQ Integrator provides a more
comprehensive inst_db configuration application that covers most of the
configuration steps above. You just have to provide a couple of parameters to run
the installation application that sets up a proper database environment for use
with the New Era Of Networks tools.
8.2.2 Environment
New Era Of Networks makes use of dedicated environment settings and a
database connection file in a development and runtime environment.
The database connection file includes information on how to access the New Era
Of Networks database. The New Era Of Networks applications (eg. NNFie,
NNRie, Visual Tester, msgtest, apitest, ...) and the runtime environment (Rules
Engine, WebSphere MQ Integrator Broker) refer to the definitions in this file. The
name and the contents of the database connection file have changed with the
versions.
The environment variables used with New Era Of Networks have changed from
version to version. However, all MQSeries Integrator versions make use of the
environment variable NN_CONFIG_FILE_PATH, which points to the directory
where the database connection file is located.
243

Besides the database connection file sqlsvses.cfg and the environment variable
NN_CONFIG_FILE_PATH, the early versions of MQSeries Integrator refer to
the configuration file MQSIRuleng.mpf for runtime information by the New Era Of
Networks Rules Engine.
sqlsvses.cfg: a database connection file, used with the early versions of
MQSeries Integrator.
NN_CONFIG_FILE_PATH: points to the database connection file
sqlsvses.cfg.
MQSIRuleng.mpf: the MQSeries Integrator V1.x runtime environment
(mqsiruleng.exe) uses the configuration file MQSIruleng.mpf, which includes
information on how to access the New Era Of Networks database (database
name, database user and password) to locate the defined formats and rules
and some other information needed for runtime (input queue, no hit queue,
failure queue, etc.).
MQSI_PARAMETERS_FILE: the MQSI_PARAMETERS_FILE system
environment variable points to the directory that contains the New Era Of
Networks Runtime settings (MQSIruleng.mpf file).
This configuration file has to be used with MQSeries Integrator V2.0 and
V2.0.1 only. It is not necessary for later versions. Table 8-4 on page 348 lists
the different parameters of this configuration file and the equivalents in a
WebSphere MQ Integrator environment.

With MQSeries Integrator V2.0.2, the database connection file, previously called
sqlsvses.cfg, is renamed neonreg.dat. This file has to be located in the directory,
referenced by the environment variable NN_CONFIG_FILE_PATH.
The MQSeries Integrator V1.x runtime configuration file MQSIRuleng.mpf is not
needed any longer.
NN_CONFIG_FILE_PATH: points to the directory where the database
connection file neonreg.dat is located.
NEON_ROOT: newly introduced to point to the directory where the New Era
Of Networks files are located. This variable has to be set manually.
WebSphere MQ Integrator introduces a new database configuration file:
nnsyreg.dat. The definitions of the sessions in this file are different than in
previous versions.
244
Database connection file

With WebSphere MQ Integrator, the database connection file is called
nnsyreg.dat. This file may be located in any directory, as long as this directory is
referenced by the environment variable NN_CONFIG_FILE_PATH.
A typical database connection file with WebSphere MQ Integrator for use with
DB2 looks like this:
Example 8-1 Database connection file used with WebSphere MQ Integrator
Session.sys_inst_db
NNOT_SHARED_LIBRARY
NNOT_FACTORY_FUNCTION
NN_SES_SERVER
NN_SES_USER_ID
NN_SES_PASSWORD
=
=
=
=
=
dbt26db250
NNSesDB2Factory
NEON
neonadmin
password
Session.inst_db
NNOT_SHARED_LIBRARY
NN_SES_SERVER
NN_SES_USER_ID
NN_SES_PASSWORD
=
=
=
=
=
dbt26db250
NNSesDB2Factory
NEON
neonadmin
password
Session.nnfie
NNOT_SHARED_LIBRARY
NN_SES_SERVER
NN_SES_USER_ID
NN_SES_PASSWORD
=
=
=
=
=
dbt26db250
NNSesDB2Factory
NEON
neonadmin
password
Session.MQSI_PLUGIN
NNOT_SHARED_LIBRARY
NN_SES_SERVER
NN_SES_USER_ID
NN_SES_PASSWORD
=
=
=
=
=
dbt26db250
NNSesDB2Factory
NEON
neonadmin
password
WebSphere MQ Integrator changes the name for the NEON_ROOT variable to

NNSY_ROOT and introduces the environment variable NNSY_CATALOGUES:
NNSY_ROOT:
Replaces NEON_ROOT(used with MQSeries Integrator V2.0.2) and points to

the directory containing the files for New Era Of Networks support.
Default on Windows
c:\Program Files\IBM\Websphere MQ Integrator 2.1\nnsy
Default on AIX
/usr/lpp/nnsy
245
Default on Solaris and HP-UX

/opt/nnsy
NNSY_CATALOGUES:
This points to the directory where the New Era Of Networks catalogues files
are located.
Default on Windows
c:\Program Files\IBM\Websphere MQ Integrator 2.1\nnsy\NNSYCatalogues
Default on AIX
/usr/lpp/nnsy/NNSYCatalogues
Default on Solaris and HP-UX

/opt/nnsy/NNSYCatalogues
8.2.3 Functionality
The implemented New Era Of Networks functionality has been significantly
enhanced with the later versions of MQSeries Integrator V2.0.2 and WebSphere
MQ Integrator. In particular, the introduction of the NEONMSG domain extends
the abilities to work with NEON messages in an MQSeries Integrator/WebSphere
MQ Integrator environment.

With MQSeries Integrator V2.0 and V2.0.1, New Era Of Networks messages are
supported by a parser referencing the message domain NEON.
The NEON parser translates wire format messages in the NEON domain into
logical message trees within MQSeries Integrator on input and regenerates the
message on output. The message received by the parser flattens all the fields in
the message to a single vertical level.
The NEON parser cannot be used to create an output message in a message
flow.
Two primitives or message processing nodes are provided that can be used in
message flows to invoke the NEON parser:
NeonFormatter:
This node takes as input a message defined using the NEONFormatter GUI
and reformats it to another message which is also defined in the
NEONFormatter GUI.
NeonRules:
246
This node takes as input a message defined using the NEONFormatter GUI
and applies the rules to it that are defined using the NEONRules GUI.
Possible actions are the reformat, the putqueue and the propagate actions.

MQSeries Integrator V2.0.2 introduces the message domain NEONMSG,
supported by an additional parser, which provides more comprehensive
processing of New Era Of Networks messages that belong to this domain. It
comes with some changes to the Graphical User Interfaces and to the
representation of Literals.
NEONMSG
The NEONMSG parser is able to construct two-dimensional logical message
trees from New Era Of Networks messages. Access to New Era Of Networks
messages is made available to other nodes used in a message flow.
Three new New Era Of Networks nodes were introduced to implement the
NEONMSG domain:
NEONTransform
This node has exactly the same role as the deprecated NeonFormatter node.
However, the NeonFormatter node produced a bit stream that you could not
handle in another message processing node. The new NEONTransform
produces a message tree, with which you can work in a Compute node, for
example.
NEONMap
This node is similar to the NEONTransform node. It also produces a message

tree. The node will transform a message according to a mapping
specification. A mapping object describes which input fields are mapped on
which output fields. In the NEONTransform node, the output operations (such
as UPPER_CASE) are also executed. The NEONMap node does not do this.
NEONRulesEvaluation
This node has exactly the same role as the deprecated NeonRules node.
However, like the other new NEON nodes, it works on a message tree and
passes a message tree along its output terminals. It is this node that will allow
you to simulate the rules engine in a broker.
It is recommended that you use the new NEON nodes for new message flows.
However, for compatibility reasons and migration purposes, the previous nodes
(NeonFormatter and NeonRules) and the NEON domain are still available for
use.
247
Graphical User Interface

With MQSeries Integrator V2.0.2, the Formatter GUI and the Rules GUI are
accessible directly from within the Control Center. When you have selected the
Message Sets tab, the menu bar offers three New Era Of Networks options:
Formatter
Rules
Visual Tester
The NEONFormatter GUI includes the newly introduced mapping functionality,

which allows you to more easily map fields in an input format to fields in an output
format (drag and drop).
The NEONRules GUI has changed and is available as an MMC (Microsoft
Management Console) snap-in.
The New Era Of Networks Formatter GUI is able to import and export formats
directly via the GUI.
Literals
Literals can now be binary values as well as string values. In earlier versions, this
distinction is not made and literals were uniformly represented as binary values.
Important: You have to consider this when you import literals form an earlier
version into a V2.0.2 New Era Of Networks database or later, because there
can be code page translation issues.
WebSphere MQ Integrator comes with changes to:
MQSeries Integrator V1.1 Rules Daemon
Log files
Mqsireload
Documentation
MQSeries Integrator V1.1 Rules Daemon

The MQSeries Integrator V1.0 and V1.1 Rules Daemon (MQSIRuleng) is not
supplied anymore in its original form with WebSphere MQ Integrator. Refer to
8.4.6, Scenario 6: Simulating the rules engine on page 343 for a message flow
that simulates a rules engine.
248
Log files
With WebSphere MQ Integrator, the log files used with earlier versions have
been renamed to:
NNSYStatus.Log (previously NEONetStatus.Log)
NNSYMessageLog.nml (previously NEONMessageLog.nml)

WebSphere MQ Integrator comes with updated versions of the New Era Of
Networks Formatter GUI and the New Era Of Networks Rules GUI suitable to the
schema of the New Era Of Networks database.
Important: Previous versions of the New Era Of Networks GUIs are not
compatible and should not be used with a WebSphere MQ Integrator
installation.
mqsireload
The command mqsireload has been added to provide a refresh for brokers and
execution groups. It replaces mqsinrfreload (reloading New Era of Networks
rules and formats), which has no functionality anymore with WebSphere MQ
Integrator.
The command mqsireload enables you to request the execution groups in the
broker to reload the Rules and Formats database dynamically.
8.3 Migration of the New Era Of Networks environment

The different New Era Of Networks versions use different schemas with their
databases and different environments. Therefore, it is necessary to migrate the
New Era Of Networks support also when you upgrade your MQSeries Integrator
environment to a higher version.
Basically, it is possible to migrate a New Era Of Networks environment directly
from any MQSeries Integrator version to any other MQSeries Integrator version,
up to WebSphere MQ Integrator. For example, when migrating from MQSeries
Integrator V2.0.1 to WebSphere MQ Integrator, you do not have to migrate to
MQSeries Integrator V2.0.2 first and in a second step to WebSphere MQ
Integrator. You can do all this in one step.
249
If you run user exits with earlier versions of New Era Of Networks, you have to
recompile those for use with WebSphere MQ Integrator as multi-threaded
objects, which must be linked with multi-threaded (thread-safe) libraries. Refer to
New Era Of Networks Formatter Programming Reference V5.6, SC34-6086 for
instructions on how to do this.
8.3.1 Migration steps

Regardless of the version you currently work with, the recommended migration
steps for your New Era Of Networks environment are:
1. Check the consistency of your existing New Era Of Networks database using
the consistency checker from your current MQSeries Integrator/ New Era Of
Networks version.
2. Check the New Era Of Networks environment for export.
3. Export your New Era Of Networks rules and formats.
4. Uninstall the current New Era Of Networks environment.
5. Install the new version.
6. Set up the New Era Of Networks environment for import.
7. Import the rules and formats exported in step 3 into a newly created and
instantiated New Era Of Networks database using the tools shipped with the
new version of WebSphere MQ Integrator.
8. Check the consistency of your new New Era Of Networks database using the
consistency checker shipped with the new MQSeries Integrator/New Era Of
Networks version.
9. Set up the New Era Of Networks environment for runtime and development.
10.Recompile User Exits (optional).
Important: The export of rules and formats (step 3 of the migration steps) has
to be done before you uninstall your current New Era Of Networks support.
Step 1: Consistency check

Prior to exporting formats and rules from your existing New Era Of Networks
database, it is recommended that you check the consistency of the definitions in
the database. You do this by running the consistency checker tools for formats
and rules separately.
250
The consistency checker lists objects that are out of synchronization for any
reason as invalid. It checks whether the records have corresponding features in
the database. All formats and rules in an inconsistent state generate a report
indicating the problem.
The results of the consistency check are documented in report files created in
the current directory. By default, the name of the log files refers to the version of
the consistency checker you are running, for example formatcc110.log. You can
redirect the output to a different file and path if you like.
After running the consistency checker, review the log files (formatccxxx.log and
ruleccxxx.log) and check whether any problems are reported. A guide to
interpreting the results in the reports files can be found in MQSeries Integrator
System Management Guide, SC34-5505 shipped with the MQSeries
Integrator/WebSphere MQ Integrator version you currently use.
Most of the checks verify the internal structure of the rules to confirm that they
were properly created. However, some checks verify that user-typed data was
correctly entered.
The consistency checker depends on the version of the installed New Era Of
Networks database. Therefore, in step 1, you have to use the version that
matches the version of the New Era Of Networks database from which you are
exporting. You will use a different version of the consistency checker in step 8,
after you have imported the formats and rules in step 7.
Table 8-2 lists the versions of the consistency checker for checking formats and
rules used with the different MQSeries Integrator versions.
Table 8-2 Consistency checker versions
Consistency checker
Corresponding New Era Of Networks

database
formatcc40; rulecc40

WebSphere MQ Integrator V2.1
251
The input parameters that you need to run the consistency checker and the
environment in which you run the command depend on:
The type of database you use with New Era Of Networks (DB2, Oracle,
Sybase, SQLServer)
The platform you run it on (Windows NT/2000, UNIX)
To check the consistency of formats and rules for a DB2 database used with a
V1.1, V2.0 and V2.0.1 MQSeries Integrator installation on Windows NT, you
need to perform the following steps:
1. Open a DB2 command window:
db2cmd
2. Switch to the directory where the formatcc/rulecc files are located:

cd c:\Program Files\IBM\MQ Integrator 2.0\neonsoft\bin
3. In the DB2 command window, type the following:

formatcc110 <db-user> <password> <database name or alias>
rulecc110
<db-user> <password> <database name or alias>
Refer to Table 8-2 on page 251 for running the commands with other MQSeries
Integrator versions.
For further details on using the consistency checker, refer to the MQSeries
Integrator System Management Guide, SC34-5505.
Important:
Note that there might be a problem when running the rulecc110 command.
You may see a message similar to the following:
The system cannot find the file specified...
Edit the file rulecc110.cmd or rulecc110.sh and correct the following entries:
@type rulecc410.sql >> temp.sql
to:
@db2 -f temp.sql -l rulecc410.log -t
to:
db2 -f temp.sql -l rulecc110.log -t
Then run the command again.
252
Step 2: Checking the New Era Of Networks environment for

export
Using the import and export utilities NNFie and NNRie in step 3 to export New
Era Of Networks formats and rules assumes that you have a properly defined
database connection file and that your environment variable
NN_CONFIG_FILE_PATH points to the directory where the database
connection file is located.

The database connection file defines sessions used by New Era Of Networks
applications, for example apitest, msgtest, Visual Tester, NNFie, NNRie, and so
on. A session specifies database connection information such as database
name, database user ID, and password.
Depending on the MQSeries Integrator/New Era Of Networks version you run,
the database connection files have different names:
sqlsvses.cfg for MQSeries Integrator V1.x and V2.0 and V2.0.1
neonreg.dat for MQSeries Integrator V2.0.2
nnsyreg.dat for WebSphere MQ Integrator V2.1
Also, the structure of the session definition has changed from earlier versions of
MQSeries Integrator to , as shown in Example 8-2 and Example 8-3.
Example 8-2 NNFie session definition in MQSeries Integrator
nnfie:NEON:db2admin:password:
Example 8-3 NNFie session definition in WebSphere MQ Integrator

Session.nnfie
NNOT_SHARED_LIBRARY
NNOT_FACTORY_FNCTION
NN_SES_SERVER
NN_SES_USER_ID
NN_SES_PASSWRD
=
=
=
=
=
dbt26db250
dbt26db250
NEON
db2admin
password
The utility NNFie, used for the import and export of formats, uses nnfie or
Session.nnfie as a key to search the database connection file. Similarly, the utility
NNRie used for an import and export of rules uses nnrmie/nnrie (DB2/other
databases) or Session.nnrmie/Session.nnrie respectively as a key.
Make sure that you have proper definitions for both sessions in the database
connection file, suitable for your database environment.
253
Finally, check that your NN_CONFIG_FILE_PATH environment variable points to

the directory where the database connection file is located.
Step 3: Exporting the New Era Of Networks rules and formats

The utilities NNFie and NNRie create export files for formats and rules that can
be interchanged between dissimilar platforms. We use these files for migration
purposes too, when all application groups and their associated message types
and rules have to be exported. The tools are typically also used to move formats
and rules from one environment to another, from the development environment to
the production environment, for example.
Since NNFie and NNRie refer to dedicated session entries in the database
connection file, the command you need to run NNFie and NNRie is identical in all
databases.
However, as with the consistency checker, you need to have the correct version
of these tools with your database, depending on the version of MQSeries
Integrator/New Era Of Networks support you use (see Table 8-3 on page 254):
Table 8-3 NNFie- and NNRie-utility versions used with MQSeries Integrator
NNFie and NNRie utilities
MQSeries Integrator version
NNFie40.exe, NNFie40.ksh
NNRie40.exe, NNRie40.ksh
NNFie411.exe;NNFie411.ksh
NNRie411.exe; NNRie411.ksh

NNFie520.exe; NNFie520.ksh
NNFie560.exe; NNFie560.ksh
WebSphere MQ Integrator V2.1
Since NNFie and NNRie are used for export and import, the direction of the
operation has to be defined by the following parameter:
-e (for export)
-i (for import)
According to Table 8-3 on page 254, to export formats and rules from a
V1.1/V2.0 and V2.0.1 database on any platform, you would type the following
commands:
NNFie411 -e <export file name>
NNRie411 -e <export file name>
254
Note that the user running the NNFie and NNRie commands must be allowed to
create new files in the current directory.
Important: Due to possible database problems, it is not recommended that
you run NNFie and NNRie simultaneously.
If you do not redirect the output and/or define your own export file names, NNFie
and NNRie create export files in the current directory called NNFie.exp and
NNRie.exp, which can be used for import. Since the export format is platform and
database neutral, the exported files can be used for import into any New Era Of
Networks target database (for example, export from DB2 and import into Oracle).
You can verify the contents of the export files by checking the NNFie.log and the
NNRie.log, created in the current directory. Any export failures are recorded in
these files. Additionally you should see the NEONMessageLog.nml file (up to
MQSeries Integrator V2.0.2) or the NNSYMessageLog.nml file (WebSphere MQ
Integrator), in which you can also find more details about a possible failure.
If you experience problems with NNFie and NNRie, or you would like to know
how to use these commands for generating conflict reports or inventory export
files, refer to the New Era Of Networks Rules and Formatter Support for
WebSphere MQ Integrator System Management Guide, SC34-6083.
Hint: The utilities NNFie and NNRie might not always include the version
identifier with their names (for example NNFie for Version 411 is simply called
NNFie.exe).
If you have problems running the commands, or you are not sure if you have
the correct version available, you can use the utility nnident, which identifies
the version of the file that you define as input parameter.
For example, running the following command on a Windows platform:
c:\IBM\MQ Series Integrator 2.0\bin\nnident NNFie.exe
returns the version of the utility NNFie:

NEONET_Version R4_11_116:SRC:Thu Nov 18 10:22:30 MST 1999
NEONET_Version R4_11_116:SRC:Thu Nov 18 10:22:32 MST 1999
255
Step 4: Uninstalling the current New Era Of Networks

environment
When the formats and rules are successfully exported, the current New Era Of
Networks environment must be removed, since it is not possible to run two
different versions of New Era Of Networks support in parallel.
You uninstall the New Era Of Networks product code by using the facilities for
your operating system:
Windows NT/2000 -> Start->Settings->Control Panel->Add/Remove
Programs
AIX -> SMIT or smitty
SUN Solaris -> pkgrm
HP-UX -> swremove
Refer to the MQSeries Integrator Installation Guide for the platform you use for
detailed instructions on how to uninstall the New Era Of Networks environment.
When you have removed the New Era Of Networks installation, make sure that
the environment variables have been removed properly too. On Windows
NT/2000, a reboot of the machine is recommended to make sure that registry
entries are cleaned up.
Important: Note that step 4 only refers to an uninstallation of the New Era Of
Networks components, which is performed separately from an uninstallation of
your MQSeries Integrator environment.
Before you uninstall your current MQSeries Integrator software, make sure
that you have followed the migration process for the MQSeries Integrator
components as well.
Step 5: Installing the new version of the software

Depending on the WebSphere MQ Integrator environment you plan, you must
install the New Era Of Networks product code shipped with your WebSphere MQ
Integrator license on Windows NT/2000 and, optionally, on one or more of the
other supported UNIX (and/or z/OS) platforms.
If you also plan to change or upgrade your database management system used
with New Era Of Networks, you additionally have to install and upgrade the
database environment(s) on your machine(s).
256
Windows NT/2000
In addition to the WebSphere MQ Integrator components Control Center and
Configuration Manager the NEONFormatter GUI, the NEONRules GUI and the
Visual Tester run on Windows NT/2000.
The installation of the New Era Of Networks product code on Windows NT/2000
is automatically launched when you install WebSphere MQ Integrator.
Alternatively, it is possible to install the New Era Of Networks product code
separately from WebSphere MQ Integrator, for setting up a New Era Of Networks
GUI front-end only, for example.
UNIX
On the supported UNIX-platforms (AIX, Solaris, HP-UX), the installation of the
New Era Of Networks product code is a separate step from the installation of the
WebSphere MQ Integrator product code. You need to install the New Era Of
Networks code before installing the WebSphere MQ Integrator product itself.
Otherwise, you cannot select the New Era Of Networks integration package that
is part of the WebSphere MQ Integrator product.
Step 6: Setting up the New Era Of Networks environment for

import
Now that you have installed the product code, you have to decide on which
platform the New Era Of Networks database has to be created. Most likely, you
will install the New Era Of Networks database on the database server that is
used for your WebSphere MQ Integrator environment. However, regardless of
the platform and the database product you use, you will create the new New Era
Of Networks database using an installation application, called inst_db.
As with all later versions of MQSeries Integrator, this application creates:
A properly configured and instantiated database for use with New Era of
Networks
A nnsyreg.dat database configuration file in the local directory
Optional with DB2 on Windows: an ODBC connection to that database
257
Important: Note that, when upgrading, it is not recommended that you use the
old New Era Of Networks database with the new product code, simply by
re-instantiating the identical database. You are urgently advised to create a
new New Era Of Networks database.
If you do not, database inconsistency can be the result and a missing

prerequisite message (warning BIP8659) will be displayed during installation.
If you ignore this message, and continue with the installation, the upgraded
version of New Era Of Networks supplied with WebSphere MQ Integrator will
not be installed, and you will have to run the installation again.
Running inst_db
If you use DB2, you need to create a user group NNSYGRP on your machine
prior to running the inst_db application. The application inst_db grants DB2ADM
privileges to this group when invoked.
For details, refer to our migration example in Chapter 8.3.2, Example migration
from MQSeries Integrator to WebSphere MQ Integrator on page 264.
The inst_db application creates a New Era Of Networks database and installs the
schema in the database. During the installation process, you specify the name of
the database, the name of the database user ID and some further connection
information. You have the opportunity to adjust the size of the database before it
is created. Run inst_db according to the database and platform you use.
When you invoke inst_db, it comes up with a sequence of dialogs, varying with
your database environment. You must specify:
The type of database you use: Oracle, DB2, Sybase, SQL Server.
What kind of installation you want to perform: Basic or Advanced.
Further parameters necessary to create the database, such as database user
ID, password, and database name.
Extending the database connection file

The inst_db application creates a database connection file, called nnsyreg.dat, in
the directory where you run it.
The database connection file initially contains two entries (Session.sys_inst_db
and Session.inst_db) for use with the New Era Of Networks database.
258
This file must be called nnsyreg.dat. Any number of database sessions may be
defined in this file. The NNOT_SHARED_LIBRARY and
NNOT_FACTORY_FUNCTION parameters of each session must be set to the
appropriate values for the desired DBMS type.
As with previous versions of MQSeries Integrator, you need to add two further
sessions to the database connection file to be able to run the import utilities
NNFie and NNRie successfully in step 7. The sessions you need to add are
called:
Session.nnfie (for use with NNFie)
Session.nnrmie (for use with NNRie and DB2)
Session.nnrie (for use with NNRie and other databases)
Add these entries to the database connection file and save the file in the current
directory.
Setting the NN_CONFIG_FILE_PATH

The environment variable NN_CONFIG_FILE_PATH must point to the directory
where the database connection file is located. Set this variable to the correct
value. You are now ready to import the formats and rules in step 7.
Step 7: Importing the rules and formats

As with running NNFie and NNRie for exporting the formats and rules in step 3,
you run these utilities for an import by specifying the -i option with the export
files created as input parameters.
As with the export procedure, you need the correct version of these files as given
in Table 8-3 on page 254.
To import the formats and rules exported in step 3, you need to execute the
following commands:
NNFie560 -i NNFie411.exp
NNRie560 -i NNRie411.exp
Tip: If you have problems running the import commands as shown, try to
explicitly specify one of the defined sessions in the database connection file
and a full qualified path to the database configuration file. Note that the
session parameter nnfie used with this command differs from the entry in the
database connection file, which is actually Session.nnfie.
For example:
NNFie -i <exportfile> -s "nnfie" -c "c:\mqsi21\nnsy\bin\nnsyreg.dat"
259
After running the import commands, you should look for the NNFie.log, the
NNRie.log and the NNSYMessageLog.nml files if any problems occurred during
the import.
Note:
When using NNFie and NNRie with DB2, pre-existing user permissions are
not maintained when importing your New Era Of Networks database. To
maintain existing permissions, you can update the permissions table
before or after you import your formats.
New Era Of Networks support with WebSphere MQ Integrator treats literals
as binary or string value. With earlier versions, this distinction is not made
and literals are uniformly represented as binary values. Therefore, when
importing formats from earlier versions into WebSphere MQ Integrator, you
should run NNFie with option -p if you wish to override the default migration
for literals from binary to string. You can also change the literal values to
have a string or binary value by using the New Era Of Networks Formatter
GUI, shipped with WebSphere MQ Integrator after import.
Step 8: Checking the consistency of your new New Era Of

Networks database
When you have imported your formats and rules successfully, you should check
again the contents of the new New Era Of Networks database by running the
consistency checker, to ensure that all imported data is valid.
Remember that you must use the correct version of the consistency checker as
explained in step 1 (see Table 8-2 on page 251). As in step 1, the results of the
consistency check are documented in report files (formatcc560.log and
rulecc560.log) created in the current directory.
Review the log files and see whether any problems were reported. A guide to
interpreting the results in the report file can be found in the MQSeries Integrator
System Management Guide, SC34-5505.

runtime and development
Some of the settings necessary to run a New Era Of Networks development and
runtime environment were already given in step 6. However, there are some
additional settings which are necessary, depending on the tools you use.
260
NN_CONFIG_FILE_PATH
Regardless of the platform where you run the New Era Of Networks environment
(Windows or UNIX), New Era Of Networks support makes use of the
NN_CONFIG_FILE_PATH environment variable to locate the database
connection file nnsyreg.dat.
NNSY_ROOT
NNSY_ROOT has to point to the directory where the New Era Of Networks
component is installed. The defaults on the platforms are:
Windows:
c:\Program Files\IBM\WebSphere MQ Integrator 2.1\nnsy

AIX:
export NNSY_ROOT=/usr/lpp/nnsy
Solaris and HP-UX:
export NNSY_ROOT=/opt/nnsy
NNSY_CATALOGUES
NNSY_CATALOGUES must point to the directory where the New Era Of
Networks catalogue files are located. The defaults on the platforms are:
Windows:
c:\Program Files\IBM\WebSphere MQ Integrator 2.1\nnsy\NNSYCatalogues

AIX:
export NNSY_CATALOGUES=/usr/lpp/nnsy/NNSYCatalogues
Solaris and HP-UX:
export NNSY_CATALOGUES=/opt/nnsy/NNSYCatalogues
ICU_DATA
ICU_DATA is automatically set during the installation of the WebSphere MQ
Integrator product code and points to the following directory:
Windows:
c:\Program Files\IBM\WebSphere MQ Integrator 2.1\nnsy\share\icu\data

AIX:
export ICU_DATA=/usr/lpp/nnsy/share/icu/data
Solaris and HP-UX:
export ICU_DATA=/opt/nnsy/share/icu/data
261
PATH
The installation procedure on Windows adds the following entries to the PATH
environment variable:
c:\Program Files\IBM\WebSphere MQ Integrator 2.1\nnsy\gui
c:\Program Files\IBM\WebSphere MQ Integrator 2.1\nnsy\bin

Basically, the database connection file nnsyreg.dat is needed on all machines
(Windows and UNIX) that need to connect the New Era Of Networks database.
Depending on the use of the machine for development and/or production
purposes, you need to add some further entries to the database connection file.
In a development environment, where you probably run the Visual Tester utility,
you need to add a session called Session.new_format_demo.
If you run the Configuration Manager on the machine, you have to add a session
called Session.MQSI_CONFIG .
In a runtime environment, where you use the newly introduced NEON nodes
(NEONTransform, NEONMap, NEONRules Evaluation) in message flows, the
database connection file for the broker needs a session entry called
Session.MQSI_PLUGIN.
Windows NT/2000
In addition to the Control Center and the Configuration Manager, you run the
Graphical User Interfaces (Formatter, Rules and Visual Tester) shipped with New
Era Of Networks on Windows.
Therefore, you need a database client connection to the platform where the New
Era Of Networks database is installed. This presumes, of course, that a suitable
database client software is installed on the Windows machine.
The database client connection you have to define depends on the database you
use. To connect to a DB2 database from a Windows client, for example, you need
to define an alias for the New Era Of Networks database on the Windows
machine, associated with an ODBC driver to connect to the database server.
262
Note: If you intend to deploy message flows that use New Era Of Networks
nodes to a broker (NEONTransform, NEONMap, NEONRules Evaluation), you
should copy the New Era Of Networks message properties file
NEONMIF20.properties from your broker installation to your Control Center
platform. This will allow exceptions thrown by the New Era Of Networks nodes
at deploy time to be displayed in the Control Center log.
The property file can be found on the broker machine in the following
directory:
AIX:
/usr/opt/mqsi/messages
Solaris and HP-UX:

/opt/mqsi/messages
The file should be transferred in ASCII mode into the WMQI_HOME/tool

directory on the Windows machine running the Control Center.
Step 10: Recompiling user exits (optional)

User exits from previous versions have to be recompiled as multi-threaded
objects (thread-safe libraries).
Due to the change in naming conventions (NNSY replaces NEON), the following
adjustments have to been made to the following files:
1. Update customized code that uses the
Current C++ Header File:
-----------------------NEON.h
NEONETRELEASE.h
INFR/NEONObjects.h
NNGLOBAL/NEONDefinedMessageProperties.h
following header files:

Updated C++ Header File:
-----------------------NNSY.h
NNSYRFRELEASE.h
INFR/NNSYObjects.h
NNGLOBAL/NNSYDefinedMessageProperties.h
Example
#include <INFR/NEONObjects.h> changes to
#include <INFR/NNSYObjects.h>
2. Update the following global compiler names:
Current Global Compiler Name
Updated Global Compiler Name
------------------------------------------------------USING_NAMESPACE(NEON)
USING_NAMESPACE(NNSY)
NEON_NAMESPACE
NNSY_NAMESPACE
263
3. Update all user makefiles to reflect the name change in the

following libraries:
Current Library Name:
--------------------cfg13
dbt22base
dbt22db250
dbt22mqc
dbt22mqs
dbt22msodbc
dbt22oldbas
dbt22oldmqs
dbt22oldses
dbt22oldsesmqs
dbt22or806
dbt22sql65
dbt22syb11
dbt22tools
gpi12parm
gpi12plugin
infr20
infr20msgs
ndo15
ndo15tools
nnt52cmpmgr
nnt52cmpmgt
nnt52fexten
nnt52fmgr
nnt52plgmgr
nnt52rmgr
nnt52rulfmt
oti22
Updated Library Name:

--------------------cfg16
dbt26base
dbt26db250
dbt26mqc
dbt26mqs
dbt26msodbc
dbt26oldbas
dbt26oldmqs
dbt26oldses
dbt26oldsesmqs
dbt26or806
dbt26sql65
dbt26syb11
dbt26tools
gpi16parm
gpi16plugin
infr21
infr21msgs
ndo16
ndo16tools
nnt56cmpmgr
nnt56cmpmgt
nnt56fexten
nnt56fmgr
nnt56plgmgr
nnt56rmgr
nnt56rulfmt
oti26
8.3.2 Example migration from MQSeries Integrator to WebSphere MQ

Integrator
This migration example assumes that we have a successful running MQSeries
Integrator V2.0.1 environment with a broker on AIX and a New Era Of Networks
installation using a DB2 database. Now we want to migrate this environment to
WebSphere MQ Integrator with New Era Of Networks support, keeping DB2 as
our database.
The New Era Of Networks database is called NEON, and the object owner is
called neonadm, using the password neonadm .
264
We follow the recommended migration steps given in 8.3.1, Migration steps on

page 250. Since we do not have customized user exits, the optional step 10 is
not relevant in our example.
Figure 8-3 shows the environment on the two machines that needs to be
migrated to WebSphere MQ Integrator V2.1.
MQSeries
Integrator V201
NEON GUI
programs
DB2 Client
connection
Windows 2000
broker
DB2
MQSeries
Integrator V201
NEON
database
AIX
Figure 8-3 MQSeries Integrator V2.01 environment to be migrated
Step 1: Running a consistency check

To make sure that our current New Era Of Networks database holds consistent
data, we start with a consistency check by using the consistency checker valid for
our MQSeries Integrator V2.0.1 environment.
We decide to run the consistency checker on the platform where the New Era Of
Networks database is installed. In our example, the runtime environment is
installed on AIX and so is the New Era Of Networks database. You can run the
consistency checker from a Windows machine using a database client
connection.
1. We switch to the directory where the consistency checker executables are
located and make this our current directory.
2. We run the consistency check for our formats with the correct versions of this
utility (formatcc110.ksh and rulecc110.ksh), shipped with MQSeries Integrator
V2.0.1, as a user having the privileges to create new files in this directory.
Using DB2 in our example, we must specify the database user (neonadm),
the password (neonadm) and the name of the New Era Of Networks database
(NEON) with this command:
formatcc110.ksh neonadm neonadm NEON
265
The consistency checker creates a log file in the current directory, called
formatcc110.log.
3. Assuming the consistency check for our formats yielded good results, or we
have solved the problems, we run the consistency checker for the rules in a
similar manner. Using DB2 in our example, we again have to specify the
database user, the password and the name of the New Era Of Networks
database with this command:
rulecc110.ksh neonadm neonadm NEON
The command creates a log file in the current directory, called rulecc110.log.
We again review the log file to check whether any problems were reported.
Important: Note that there might be a problem when running the rulecc110
command. You may see the message:
The system cannot find the file specified...
Edit the file rulecc110.cmd or rulecc110.ksh and correct the following entries:
to:
@db2 -f temp.sql -l rulecc410.log -t
to:
db2 -f temp.sql -l rulecc110.log -t
Then run the command again.

export
Before we can export the formats and rules from our New Era Of Networks
database in step 3, we must check the settings in the database configuration file,
used with MQSeries Integrator V2.0.1 (sqlsvses.cfg) and the current setting of our
environment variable NN_CONFIG_FILE_PATH.
The database connection file must have properly defined entries for two sessions
used with the export/import utilities NNFie and NNRie that we use in step 3.
The session nnfie is used by NNFie and the session nnrmie is used by NNRie
(with DB2).
266
Our sqlsvses.cfg file is as shown in Example 8-4:

Example 8-4 Current settings in the database connection file sqlsvses.cfg
# Format of lines for the various supported database types:
# DB2:
# sessionname:dbname or alias:db-user-id:password:
# (note that the fifth field is blank, so the last colon is required)
new_format_demo:NEON:neonadm:neonadm:
nnfie:NEON:neonadm:neonadm:
nnrmie:NEON:neonadm:neonadm:
Important: Note the colon at the end of every line!
Step 3: Exporting formats and rules

Now we are ready to export the formats and rules from our MQSeries Integrator
V2.0.1 New Era Of Networks database. We export the formats by running NNFie
and the rules by running NNRie with option -e.
Remember that we need to use the correct version of these utilities as given in
Table 8-3 on page 254. The correct executables for an MQSeries Integrator
V2.0.1 environment on AIX are NNFie411.ksh and NNRie411.ksh.
We type in the command to run the NNFie utility with option -e and give the
exportfile a meaningful name (the default name for the exportfile is NNFie.exp).
NNFie411.ksh -e formats_20011114
When the export has finished, we can verify the export by checking the
NNFie.log file in the current directory. Any export failures are recorded in this file
and/or in the NEONMessageLog.nml file.
After exporting the formats we export the rules using the NNRie utility in a similar
manner, by running the command NNRie with option -e.
NNRie411.ksh -e rules_20011114
When the export has finished, we again verify the export by checking the
NNRie.log file in the current directory. Any export failures are recorded in this file
and/or the NEONMessageLog.nml.
267
Step 4: Uninstalling the current New Era Of Networks

installation
When we have saved our formats and rules, the current New Era Of Networks
environment has to be removed.
On AIX, we remove the New Era Of Networks installation via SMIT (or smity):
SMIT -> Software Installation and Maintenance -> Software
Maintenance and Utilities -> Remove installed Software
On Windows NT/2000, we remove the New Era Of Networks installation using
Start -> Settings -> Control Panel -> Add/Remove Programs
Step 5: Setting up the New Era Of Networks support with

For further steps in our example, we assume that:
The MQSeries Integrator environment on our Windows and AIX platforms has
been properly migrated to a WebSphere MQ Integrator environment
The New Era Of Networks product code has been installed on Windows and
AIX properly, according to the WebSphere MQ Integrator Installation Guides
for these platforms
A supported DB2 server installation is available on AIX, and that a compatible
DB2 Client Application Enabler is installed on Windows
WebSphere MQ Integrator provides an inst_db application that creates the

physical resources and the schema required for the New Era of Networks Rules
and Formatter support.
Prerequisites with DB2

Running inst_db with DB2 requires DB2ADM privileges to the database instance,
in which the database has to be installed. The script refers to a group NNSYGRP
and grants DB2ADM privileges to this group. That is why we have to define this
group prior to running inst_db.
Running inst_db
Following the prerequisites, we have created a group, NNSYGRP, on our AIX
machine. We decide to install the new New Era Of Networks database into the
existing database instance.
268
1. We log on as a DB2 instance owner (db2inst1).

2. We switch to the directory where the inst_db application is located and make
this our current directory:
cd /usr/lpp/nnsy/install.sql_rulfmt56/inst_db
3. We invoke the application:

inst_db
The application comes up with a sequence of dialogs. We specify:

The database we run with New Era Of Networks (Figure 8-4 on page 269)
The type of installation we want to perform (Figure 8-5 on page 270)
The parameters necessary to create the database (Figure 8-6 on page 271)
Figure 8-4 inst_db - dialog 1
In dialog 1, we select 1 for DB2.
269
In dialog 2, we select 1 for Basic. Choosing 2 for Advanced would allow us to

customize the size of the database.
270
In dialog 3, we define the following parameters:

1. Instance/object owner account: db2inst1
2. Instance/object owner account password: db2inst1
3. Database server name: rs617002
4. Database server TCP/IP port: 50000
271
This is the TCP/IP port on which the database server is listening for
connections. The default is 50000. Check the current setting in the file
/etc/services.
5. Database name: NEON
6. Install or refresh the database: 1 for install
Important: Note that, if you refresh the schema, it is an absolute requirement
that the schema be refreshed using the same installation mode (that is, Basic
or Advanced) that was used to originally install it.
We start the installation process by entering 0 (for process component).

When the first part of the installation has finished, a second dialog appears,
asking for the parameters necessary to create the database connection file
(nnsyreg.dat). In this second step, the schema is installed in the database.
We define the following parameters:
272
1. Object owner account: neonadm

This is the account that owns the database objects (tables, tablespaces, and
so on). If no value is provided, the instance owner account will be used.
2. Instance/object owner account password: neonadm
We start the installation process by entering 0 (for process component).
When the Installation successfully completes, the following message appears:
Installation completed SUCCESSFULLY.
Note: After running the inst_db installation, the DB2ADM privilege can be
removed from NNSYGRP because the DB2ADM privilege is automatically
granted to all users in NNSYGRP.
273
Windows
On Windows NT/2000, we run the NEONFormatter GUI, the NEONRules GUI
and the Visual Tester.
Since the New Era Of Networks database is running on our AIX machine, we
have to set up a DB2 client connection to this new database.
We define the client connection using the Client Configuration Assistant started
by selecting:
Start->Programs->DB2 for Windows NT->Client Configuration Assistant
274
Once started, click the Add button and the Add Database SmartGuide window
appears. We select the following options:
Panel 1. Source:
Select Manually configure a connection to a database
Figure 8-9 Setting up a DB2 client connection 1
275
Panel 2. Protocol:
Select TCP/IP as the network protocol.
276
Panel 3. TCP/IP:
Specify the name of the host machine where the database instance is running
and the port on which the instance is listening. We get the port number from
the file /etc/services on AIX.
277
Panel 4. Database:
Specify NEON as the name of the database.
278
Panel 5. ODBC:
Select Register this database for ODBC and select also the As a system
data source radio button.
Having defined all connection parameters, we finally test the connection:
279
When the test is successful, we are able to work with our New Era Of Networks
GUIs, giving the correct connection parameters at start-up (see Figure 8-16):
User ID: neonadm
Password: neonadm
DBMS: ODBC - DB2 (ODBC)
Driver: NEON
Figure 8-16 NEONFormatter GUI
280

import
Before we can work with the NNFie and NNRie utilities to import our formats and
rules, we must set up a database connection file on the machine where we run
the utilities. Since we want to import the formats and rules, this time from our
Windows machine, we go to the following directory and copy the shipped
example database connection file to the default directory:
cd c:\Program Files\IBM\Websphere MQ Integrator 2.1\examples\neon
copy nnsyreg.dat c:\Program Files\IBM\Websphere MQ Integrator
2.1\nnsy\install.sql_rulfmt56\inst_db
As with our MQSeries Integrator V2.0.1 environment, we need to create two

further sessions to this file to be able to run the import command successfully:
Session.nnfie for use with NNFie

Session.nnrmie for use with NNRie
After completing this step, our nnsyreg.dat file looks like this:
Session.sys_inst_db
NNOT_SHARED_LIBRARY
= dbt26db250
= NNSesDB2Factory
NN_SES_SERVER
= NEON
NN_SES_USER_ID
= neonadm
NN_SES_PASSWORD
= neonadm
Session.inst_db
NNOT_SHARED_LIBRARY
= dbt26db250
= NNSesDB2Factory
NN_SES_SERVER
= NEON
NN_SES_USER_ID
= neonadm
NN_SES_PASSWORD
= neonadm
Session.nnfie
NNOT_SHARED_LIBRARY
= dbt26db250
= NNSesDB2Factory
NN_SES_SERVER
= NEON
NN_SES_USER_ID
= neonadm
NN_SES_PASSWORD
= neonadm
281
Session.nnrmie
NNOT_SHARED_LIBRARY
= dbt26db250
= NNSesDB2Factory
NN_SES_SERVER
= NEON
NN_SES_USER_ID
= neonadm
NN_SES_PASSWORD
= neonadm
Now we set the environment variable NN_CONFIG_FILE_PATH to the directory

where our nnsyreg.dat file is located:
Figure 8-17 Setting the NN_CONFIG_FILE_PATH environment variable 1
282
Figure 8-18 Setting the NN_CONFIG_FILE_PATH environment variable 2
We are now ready to import our formats and rules into the newly created New
Era Of Networks database.
Step 7: Importing the rules and formats

As we ran the NNFie and NNRie commands for exporting the formats and rules,
we now run these utilities by specifying the option -i with the export files created
in step 3. This time we run the command from our Windows machine.
1. We switch to the directory where the NNFie and NNRie utilities are located:
cd c:\Program Files\IBM\Websphere MQ Integrator 2.1\nnsy\bin
2. We run the NNFie utility with options -i and -p (we want to import our literals
as string) and with the name of our import file as we called it in step 3:
NNFie -i formats_20011114 -p
This command imports our formats into the newly created New Era Of
Networks database. After importing the formats, we check the
NEONMessageLog.nml file for a report of the import procedure.
283
3. After successfully importing the formats, we are ready for an import of the
rules using the NNRie utility in a similar manner:
NNRie -i rules_20011114
We again check the NEONMessageLog.nml file for a report of the import

procedure.
Step 8: Checking the consistency

To ensure that our data has been imported properly, we perform a consistency
check by using the consistency checker shipped with our WebSphere MQ
Integrator installation.
We run the consistency checker on the AIX platform where the New Era Of
Networks database is created. We could also run the consistency checker from
the Windows machine in a DB2 command window.
1. We switch to the directory where the Consistency Checker executables are
located and make this our current directory:
cd /usr/lpp/nnsy/install.sql_rulfmt56/scripts/db250
2. We look for the correct version of the consistency checker files.

With WebSphere MQ Integrator on AIX, these files are called formatcc560.sh
and rulescc560.sh.
3. We run the consistency check for our formats with a user having the privileges
to create new files in this directory.
Using DB2 in our example, we have to specify the database user, password
and name of the New Era Of Networks database with this command:
formatcc560.sh neonadm neonadm NEON
The command creates a log file in the current directory, called

formatcc560.log. We review the log file to check whether any problems were
reported.
Assuming the consistency check for our formats was fine, we run the
Consistency Checker for the rules in a similar manner.
rulecc560.sh neonadm neonadm NEON
The command creates a log file in the current directory, called rulecc560.log.
We review the log file to check whether any problems were reported.
284
Step 9: Setting up our new New Era Of Networks environment

for runtime and development
Now that we have imported our formats and rules and we are able to connect to
the runtime environment from our Windows machine, we have to finish our
runtime and development machines by completing the environment setup.
Runtime environment on AIX

To configure the runtime environment on AIX, we need a database connection
file and some additional environment variables.

Inst_db has created a new database connection file on our AIX machine, which is
called nnsyreg.dat. This file initially is located in the
/usr/lpp/nnsy/install.sql_rulfmt56/inst_db directory and contains two entries
(Session.sys_inst_db and Session.inst_db) for use with our New Era Of Networks
database:
Figure 8-19 Initial database connection file created by inst_db
We need to add some further session entries to that file. To be prepared to run
New Era Of Networks utilities (apitest, NNFie, etc.) on AIX, we add the following
sessions:
Session.new_format_demo
285
NNOT_SHARED_LIBRARY
NN_SES_SERVER
NN_SES_USER_ID
NN_SES_PASSWORD
=
=
=
=
=
dbt26db250
NNSesDB2Factory
NEON
neonadm
neonadm
Session.nnrmie
NNOT_SHARED_LIBRARY
NN_SES_SERVER
NN_SES_USER_ID
NN_SES_PASSWORD
=
=
=
=
=
dbt26db250
NNSesDB2Factory
NEON
neonadm
neonadm
Session.nnfie
NNOT_SHARED_LIBRARY
NN_SES_SERVER
NN_SES_USER_ID
NN_SES_PASSWORD
=
=
=
=
=
dbt26db250
NNSesDB2Factory
NEON
neonadm
neonadm
We add the session Session.MQSI_PLUGIN to allow the broker to connect to the

New Era of Networks Rules and Formats database.
Session.MQSI_PLUGIN
NNOT_SHARED_LIBRARY
NN_SES_SERVER
NN_SES_USER_ID
NN_SES_PASSWORD
=
=
=
=
=
dbt26db250
NNSesDB2Factory
NEON
neonadm
neonadm
Environment settings
We check or set the following environment variables. These environment
variables need also to be defined in the profile of the broker.
NNSY_ROOT:
This points to the directory where the New Era Of Networks product code
component is installed:
export NNSY_ROOT=/usr/lpp/nnsy
NN_CONFIG_FILE_PATH:
This points to the directory where the database configuration file nnsyreg.dat
is located:
export NN_CONFIG_FILE_PATH=/usr/lpp/nnsy/install.sql_rulfmt56/inst_db
NNSY_CATALOGUES:
This points to the directory where the New Era Of Networks catalogues-files
are located:
286
export NNSY_CATALOGUES=/usr/lpp/nnsy/NNSYCatalogues
ICU_DATA
This points to the following directory:

export ICU_DATA=/usr/lpp/nnsy/share/icu/data
Development in Windows
To configure the development environment in Windows, we need a database
connection file and some additional environment variables.

Some more sessions are needed in the database connection file. Note that the
user ID and password are always set to the same values here. However, it should
be clear that this is not required. Of course, you need to make sure that any other
user ID is defined on the database server and that it has the appropriate
authorities to access the database.
Session.new_format_demo, needed for Visual Tester and the command line
utilities (apitest, msgtest, ruletest, etc.):
Session.new_format_demo
NNOT_SHARED_LIBRARY
= dbt26db250
= NNSesDB2Factory
NN_SES_SERVER
= NEON
NN_SES_USER_ID
= neonadm
NN_SES_PASSWORD
= neonadm
Session.nnfmgr (for use with the format remover utility NNFmtRmv):

Session.nnfmgr
NNOT_SHARED_LIBRARY
= dbt26db250
= NNSesDB2Factory
NN_SES_SERVER
= NEON
NN_SES_USER_ID
= neonadm
NN_SES_PASSWORD
= neonadm
Session.add_date_fmt (to create a custom date and time format):

Session.add_date_fmt
NNOT_SHARED_LIBRARY
= dbt26db250
= NNSesDB2Factory
NN_SES_SERVER
= NEON
NN_SES_USER_ID
= neonadm
287
NN_SES_PASSWORD
= neonadm
Session.MQSI_CONFIG (This must be defined to allow the Configuration

Manager to connect to the New Era of Networks Rules and Formatter
database. It only needs to be defined in the nnsyreg.dat file which the
Configuration Manager uses, not in nnsyreg.dat files which are used solely by
brokers):
Session.MQSI_CONFIG
NNOT_SHARED_LIBRARY
= dbt26db250
NNOT_FACTORY_FUNCTION = NNSesDB2Factory
NN_SES_SERVER
= NEON
NN_SES_USER_ID
= neonadm
NN_SES_PASSWRD
= neonadm
Environment settings
As with our runtime environment, we have to check the settings of the following
environment variables:
NNSY_ROOT:
This points to the directory where the New Era Of Networks component is
installed. On Windows, this is done automatically during installation:
c:\Program Files\IBM\WebSphere MQ Integrator 2.1\nnsy
NN_CONFIG_FILE_PATH:
This points to the directory where the database configuration file nnsyreg.dat
is located.
c:\Program Files\IBM\WebSphere MQ Integrator
2.1\nnsy\install.sql_rulfmt56\inst_db
NNSY_CATALOGUES:
This points to the directory where the New Era Of Networks catalogues-files
are located:
c:\Program Files\IBM\Websphere MQ Integrator
2.1\nnsy\NNSYCatalogues
ICU_DATA:
This is set automatically during the installation of theWebSphere MQ

Integrator product code on Windows and points to the following directory:
c:\Program Files\IBM\Websphere MQ Integrator
2.1\nnsy\share\icu\data
PATH:
c:\Program Files\IBM\Websphere MQ Integartor 2.1\nnsy\bin
288
c:\Program Files\IBM\Websphere MQ Integartor 2.1\nnsy\gui
Message properties file

Since we intend to deploy message flows with New Era Of Networks nodes to the
broker, we copy the New Era Of Networks message properties file from our
broker installation on AIX to our Control Center installation on Windows.
We do this by downloading the file NEONMIF20.properties from the directory:
/usr/opt/wmqi/messages
on AIX, in ASCII mode, to:
c:\Program Files \IBM\Websphere MQ Integrator 2.1\tool
on our Windows machine.
8.4 Working on New Era Of Networks messages

This section provides some examples of working with New Era Of Networks
messages in an MQSeries Integrator V2.0.1 environment compared to working
on those messages in a WebSphere MQ Integrator environment.
The samples demonstrate that the New Era Of Networks support/integration has
been enhanced significantly with the latest versions of MQSeries Integrator
(V2.0.2 and higher).
WebSphere MQ Integrator supports two domains for New Era of Networks
messages: NEONMSG and NEON. Parsers are provided to interpret these
messages on receipt by a message flow. The two domains are supported by
message processing nodes (NEONMap, NEONRulesEvaluation, and
NEONTransform for NEONMSG domain, and NeonFormatter and NeonRules for
the NEON domain).
The nodes that process messages in the NEONMSG domain provide more
comprehensive processing.
You must use the New Era of Networks Graphical User Interfaces to define the
messages to both domains, and to define the processing rules that are used by
the New Era of Networks nodes. The interfaces provided are the New Era of
Networks Formatter and the New Era of Networks Rules. These are accessible
from the Control Center.
289
The message processing model in WebSphere MQ Integrator is comprised of

three stages: first, the incoming message is parsed, then it is processed, and
finally it is reserialized into an output format. The processing stage takes place
on a logical message model: a tree structure that holds the data content of the
message in a way that is independent of the wire format.
The NEON parser cannot reserialize an output message: a message in the
NEON domain is simply reformatted from one wire format to another.
The NEONMSG parser can translate wire format messages in its domain into
WebSphere MQ Integrator message trees on input, and regenerate the message
as a New Era of Networks format on output. However, it can only reserialize
messages defined as outputs in the New Era of Networks Rules and Formats
database, or messages defined as input formats in the New Era of Networks
Rules and Formats database, that have not been modified by the message flow.
In this section, we look at the following scenarios:
Scenario 1 shows a simple reformat procedure in an MQSeries Integrator V2.0.1
environment, compared to the same procedure in a WebSphere MQ Integrator
environment. In Scenario 1a (MQSeries Integrator V2.0.1), we use the
NEONFormatter node in the NEON domain. In Scenario 1b (WebSphere MQ
Integrator), we use the newly introduced NEONMap node in the NEONMSG
domain for this procedure.
Scenario 2 gives an example of the enhanced functionality introduced with the
NEONMSG domain in a WebSphere MQ Integrator environment, using the
NEONTransform and the NEONMap node.
Scenario 3 is an extension to Scenario 1. We use the message from Scenario 1
and transform the message into generic XML. In an MQSeries Integrator V2.0.1
environment, we show two alternatives. Alternative 1 uses the deprecated
NEONRules node, Alternative 2 uses a sequence of two NEONFormatter nodes.
In the WebSphere MQ Integrator environment, we work with a combination of
NEONFormatter and NEONTransform node, bridged by a
ResetContentDescriptor node.
Scenario 4 is a second scenario in which the deprecated NEONRules node is
used with the SWIFT message. The message is transformed from SWIFT to
generic XML and, depending on the country code that the message includes, it is
routed to different destination queues. The routing information is defined in the
NEONRules environment. We migrate this scenario to a WebSphere MQ
Integrator environment, according to the migration steps, and show how it works
in the new environment.
290
Scenario 5 shows more of the enhanced NEON integration. An output format,

defined in the NEON domain, is added to the current workspace of the
WebSphere MQ Integrator Control Center as NEON Message Set, similar (but not
identical) to message sets defined in the MRM. The SWIFT message is received
in the NEONMSG domain, and it is reformatted from a given input format to a
given output format in the NEON environment. The NEON output format is added
as NEON Message Set and some of the fields defined in the NEON message set
are referred in a database node, used in the message flow, for inserting the
related values into a database by a database node, thereby storing information
gained from a NEON message in a database.
In Scenario 6, we show a message flow that simulates the behavior of the rules
engine.
Sample message
In our scenarios, we work with a simple SWIFT message. According to the
SWIFT conventions, our message consists of the following logical blocks:
{1:
{2:
{3:
{4:
{5:
Basic Header Block}

Application Header Block}
User Header Block}
Text Header Block}
Trailer Block}
In the real world, blocks 2-4 and their elements are optional and thus do not
necessarily have to appear in a message. In our example, however, we will have
all blocks with this message available. The sample message we work on looks
like this:
{1:F01BANKBEBBAXXX2222123456}
{2:I100BANKDEFFXXXXU}
{3:{113:9601}{108:abcdefgh12345678}}
{4::20:PAYREF- TB54302:32A:910930USD2000,:50:EDWARDS BANK LILLIPUT POOL
EDORSET:59:/123-456-789BUGS BUNNY WABBIT ELMER FUDD -}
{5:{MAC:41720873}{CHK:123456789ABC}}
8.4.1 Scenario 1: A simple reformat procedure

Scenario 1 demonstrates a simple reformat procedure, where the SWIFT
message given above is received by an MQInput node and is reformatted from a
given input format to a given output format.
Scenario 1a works in a MQSeries Integrator V2.0.1 environment and makes use
of the deprecated NEON domain; Scenario 1b shows how to work on this task in
the new NEONMSG domain in a WebSphere MQ Integrator V2.1 environment.
291
In both cases, input format and output format are predefined in the New Era Of
Networks environment using the integrated New Era Of Networks Formatter GUI.
The input format SWIFTDataIn reflects the logical structure and the physical
layout of the SWIFT message we receive. The output format GenericDataOut
removes tags and brackets from the input message and extracts the business
data, preparing the message for further use by any application in the following
steps.
Scenario 1a
The input format SWIFTDataIn and the output format GenericDataOut are
predefined in the New Era Of Networks environment using the New Era Of
Networks Formatter GUI (see Figure 8-20 on page 293), which you can invoke
with MQSeries Integrator V2.0.1 by clicking Start -> Programs -> IBM
MQSeries Integrator 2.0 -> Neon Support - NEONFormatter.
In working with SWIFT messages need, special format conditions should be
considered when defining the input format:
All SWIFT messages conform to a defined block structure. Each block of a
message contains data of a particular type and is used for a particular
purpose.
Each block of message begins and ends with a curly bracket (or brace)
character, "{" and "}" respectively. All main blocks are numbered, and the
block number followed by a colon (:) are always the first characters within
any block.
Only block 1 (the Basic Header block) is mandatory for all messages. Blocks
2-5 are optional and depend upon the nature of the message and the
application in which the message is being sent or received.
Blocks 1, 2 and 3 relate to header information, block 4 contains the text of the
message, and block 5 contains trailer information.
Blocks 3, 4 and 5 may contain sub-blocks (that is, blocks within blocks) or
fields delimited by field tags, depending on the nature of the message.
292
Figure 8-20 Scenario 1a: NEONFormatter GUI showing input format SWIFTDataIn and
output format GenericDataOut
The message flow (Figure 8-21 on page 294) consists of:

An MQInput node (Get SWIFT Message), which reads the message from an
MQSeries input queue and refers to the input format SWIFTDataIn in the
NEON domain
293
A NeonFormatter node (Reformat SWIFT), which reformats the message

according to the defined target/output format.
An MQOutput node (GENERIC-OUT), which writes the reformatted message
to an output queue.
Figure 8-21 Scenario 1a: a simple reformat procedure with the NEONFormatter node
The Message Type property of the MQInput node (Get SWIFT Message) is set to
the name of the input format (SWIFTDataIn) defined in the New Era Of Networks
environment (Figure 8-22 on page 295). Since we want to invoke the NEON
parser with this message, we additionally have to set the message domain to
NEON in this node.
Referencing the NEON domain causes the bitstream of the message body to be
passed to the integrated New Era Of Networks Formatter engine. The Formatter
engine uses the value of the Message Type to interpret the message according
to the predefined input format SWIFTDataIn and maps and transforms the
message to the output format defined in the TargetFormat attribute of the
NEONFormatter node (GenericDataOut).
Note: For a simple one step reformat process we do not need to define a rule
via the NEONRules GUI as in a native NEON environment and thus it is not
necessary to set a value for Message Set in the MQInput node.
294
Figure 8-22 Scenario 1a: MQInput node
Figure 8-23 Scenario 1a: NEONFormatter node
After running the message flow, the reformatted message in the output queue is
ready for use with any application interpreting this data:
F01BANKBEBBAXXX2222123456I100BANKDEFFXXXXU9601abcdefgh12345678PAYREFTB54302910930USD2000,EDWARDS BANK LILLIPUT POOL EDORSET/123-456-789BUGS
BUNNY WABBIT ELMER FUDD -41720873123456789ABC
295
We will use this data extract as input in Scenario 2.
Scenario 1b
In Scenario 1b, we look at the same reformat procedure in a WebSphere MQ
Integrator V2.1 environment, where the NEONFormatter node and the NEON
domain are still available for compatibility reasons. Therefore we run the
message flow from Scenario 1a in the WebSphere MQ Integrator V2.1
environment without any changes, which would be suitable for our simple
reformat process.
However, we could also decide to build this message flow by using either of the
new NEONMap (Figure 8-24 on page 297) or NEONTransform node
(Figure 8-25 on page 297) in the NEONMSG domain to be able to work with the
enhanced functionality given in this domain. Messages in the NEONMSG
domain can be used in message flows, exactely like messages that belong to the
other supported domains. This is a significant improvement over messages in the
NEON domain. We will not make use of these enhancements in this scenario, but
will refer to those in Scenario 2.
Let us go back to the NEONMap and NEONTransform nodes we might choose
in this scenario. Both nodes offer the mapping stage of a reformat procedure able
to reformat an input format to an output format. However, the NEONMap node
does not perform any output operation defined with the output format (for
example, transforming lower case input data to upper case output data). Given
this limitation for NEONMap nodes, full data transformation is supported by the
NEONTransform node only.
Which of the nodes we use basically depends on the business case. In some
cases, it might be useful to have the data from an input message simply mapped
to an output message, keeping the attributes of the data as they are. In our
simple reformat scenario, we could use either of the New Era Of Networks
nodes, since we have no significant output operations defined with the message.
The message flow and the definitions of the nodes barely differ from those in
Scenario 1a.
Both the NEONMap and the NEONTransform node are defined to reformat this
message into the target format SWIFTDataOut and, since we still use the
predefined input format in the New Era Of Networks environment
(SWIFTDataIn), we define exactly the same input format (given as Message
Type attribute) for this message flow.
296
The difference here is the message domain, which is set to NEONMSG to invoke the
NEONMSG parser with this message. But again, as long as we simply reformat
the message as given in this scenario, there is no difference between using the
NEON domain or using the NEONMSG domain with this message.
Figure 8-24 Scenario 1b: using a NEONMap node
Figure 8-25 Scenario 1b: using a NEONFormatter node
297
Figure 8-26 Scenario 1b: MQInput node
Figure 8-27 Scenario 1b: NEONTransform node
A further enhancement with the NEONMap and the NEONTransform nodes is

the ability to adress Map objects defined in the New Era Of Networks
environment.
Map objects (introduced with New Era Of Networks V5.2 and available with
MQSeries Integrator V2.0.2 and higher) contain mapping definitions and
transform operations that can be used during the reformatting process.
Usually, there is exactly one default or one custom mapping defined with an
output field, which is performed during the reformat operation. Map objects,
however, allow you to apply different predefined mapping and transform
operations on one field in an output format, depending on the current reformat
situation. In other words, having the same output format, we are able to map the
values of different input fields to the identical output field combined with different
output operations to this field, depending on the situation.
298
Access to Map objects, defined by the NEONFormatter GUI, is given via the Map
object and Map version attributes of these nodes, with the limitation that output
operations are not supported with the NEONMap node. This functionality is not
supported with the NEONFormatter node.
Important: Map version is for further use and is not operational in the current
release.
8.4.2 Scenario 2: Exploiting WebSphere MQ Integrator functionality

for messages in the NEONMSG domain
In Scenario 1b, we have seen that the NEONTransform node and the NEONMap
node in a WebSphere MQ Integrator environment are basically used to enable
reformat procedures as the NEONFormatter node does in an MQSeries
Integrator V2.0.1 environment. The enhanced functionality that comes with these
nodes, however, allows you to transform a New Era Of Networks message from
the NEONMSG domain to XML and thus to integrate the XML-structured output
into message flows for further processing steps quite easily.
Messages that belong to the NEONMSG domain are parsed by the newly
introduced NEONMSG parser. The NEONMSG parser translates wire format
messages in the NEONMSG domain into logical message trees on input, and
regenerates the message on output. This process is not supported by the NEON
parser and messages in the NEON domain.
A NEONMSG message can be handled by all IBM-supplied message nodes,
with the exception of the NEONFormatter and the NEONRules nodes. The whole
message can be stored in a database, headers can be added to or removed from
the message as it passes through the message flow. The message contents can
be manipulated by the Compute, Filter, Database, DataDelete, DataInsert,
DataUpdate and Warehouse nodes.
In Scenario 2a, we take the output data from Scenario 1a and transform this data
into XML, using a NEONMap node.
As a variation to using a NEONMap node in scenario 2a, we use a
NEONTansform node for the same procedure in scenario 2b, to show the
difference between both nodes.
299
Scenario 2a
Assuming we have a New Era Of Networks message containing data already
prepared for interpretation, as given with the output of Scenario 1a shown in
Example 8-5, we can now easily transform this data into XML format data by
using either the NEONMap node or the NEONTransform node.
Example 8-5 Input message for scenario 2a
F01BANKBEBBAXXX2222123456I100BANKDEFFXXXXU9601abcdefgh12345678PAYREFTB54302910930USD2000,EDWARDS BANK LILLIPUT POOL EDORSET/123-456-789BUGS
To achieve this, we have to:

Define a flat or compound input format for this message
Define a flat or compound output format for this message
Build a message flow that:
Receives the data in the NEONMSG domain

Defines the input format constructed
Defines the output format constructed
Defines XML as output target domain
We start with the definition of a compound input format SWIFT-IN3 for
interpreting this data in the New Era Of Networks environment using the New Era
Of Networks Formatter GUI, as shown in Figure 8-28 on page 301.
300
Figure 8-28 Scenario 2a: NEONFormatter showing input format SWIFT-IN3
The next step is to define an adequate output format. We define a simple flat
output format SWIFTOUT, as shown in Figure 8-29 on page 302.
301
Figure 8-29 Scenario 2a: NEONFormatter showing SWIFT-OUT output format
Now that we have defined the input and output formats in the New Era Of
Networks environment, we construct the message flow in the WebSphere MQ
Integrator environment, as shown in Figure 8-30.
302
Figure 8-30 Scenario 2a: message flow
The MQInput node (Figure 8-31) defines the input format SWIFT-IN3 that we use
with this message as Message Type attribute of the node. Since we use the
NEONMap node, we need to define the NEONMSG domain as domain attribute.
The NEONMap node (Transform SWIFT to XML) defines the target format to
which the input information must be mapped and defines the output domain as
XML.
303
Figure 8-32 Scenario 2a: NEONMap node
After running the flow, the resulting message looks like the one shown in
Figure 8-33. The tool used to display and parse the message contents is the
MQSeries Integrator V2 Test Tool, which is available as a SupportPac and can be
downloaded from:
http://www-4.ibm.com/software/ts/mqseries/txppacs/ih03.html .
304
Figure 8-33 Scenario 2a: XML output without considering output operations
Scenario 2b
A variation on using the NEONMap node is using the NEONTransform node with
this flow (Figure 8-34 on page 306). The properties of the participating nodes are
identical; the difference is only that we use a NEONTransform node instead of a
NEONMap node.
305
Figure 8-34 Scenario 2b: using a NEONTransform node
Using a NEONTransform node allows you to apply output operations on the

output data. In this case, we have defined LOWER CASE Output Operations with
suitable output fields in the output message. The resulting message looks as
shown in Figure 8-35.
Figure 8-35 Scenario 2b: XML output considering output operations
306
8.4.3 Scenario 3: Transforming New Era Of Networks message to

XML
In Scenario 3, we extend the message flow from Scenario 1. The New Era Of
Networks message will be transformed into a generic XML format for further
use. The difference between this and Scenario 2 is that we work on the
SWIFTmessage as it is originally formatted when it arrives at the input queue,
with tags complementing the data.
Scenario 3a shows how to work on this message in an MQSeries Integrator
V2.0.1 environment, and Scenario 3b shows how this can be done in a
WebSphere MQ Integrator environment.
Scenario 3a
The problem with a SWIFT message is that we have tags with the message and
that we want to extract the pure data from it.
The original message is shown in Example 8-6.
Example 8-6 Input message for Scenario 3a
{1:F01BANKBEBBAXXX2222123456}
{2:I100BANKDEFFXXXXU}
{3:{113:9601}{108:abcdefgh12345678}}
{4:
:20:PAYREF- TB54302
:32A:910930USD2000,
:50:EDWARDS BANK LILLIPUT POOL EDORSET:
59:/123-456-789BUGS BUNNY WABBIT ELMER FUDD
-}
We want to extract the pure data from this message,as shown in Example 8-7.
Example 8-7 Extracted data
F01BANKBEBBAXXX2222123456I100BANKDEFFXXXXU9601abcdefgh12345678PAYREFTB54302910930USD2000,/123-456-789EDWARDS BANK LILLIPUT POOL EDORSETBUGS
This can be achieved in different ways, of course. We show two alternatives.

Alternative 1 is a two step reformat procedure using the NEONFormatter to
define input and output formats and NEONRules to define the
reformat-sequence on the message. Alternative 2 uses a two-step
NEONFormatter solution without using NEONRules. Both alternatives work in an
MQSeries Integrator V2.0.1 environment.
307
Alternative 1, NEONFormatter and NEONRules nodes:

In step 1, the received SWIFT formatted message is read from the input
queue and parsed according to a predefined input format SWIFT-IN1 (which
is similar to SWIFTDataIn in scenario 1), extracting the block information in
the message:
F01BANKBEBBAXXX2222123456 (Basic Header Data)
I100BANKDEFFXXXXU (Application Header Data)
9601abcdefgh12345678 (User Header Data)
PAYREF- TB54302910930USD2000,EDWARDS BANK LILLIPUT POOL
EDORSET/123-456-789BUGS BUNNY WABBIT ELMER FUDD - (Text Bock Data)
41720873123456789ABC (Trailer Block Data)
The extracted block information is mapped to a predefined output format
SWIFT-OUT1, which works as an intermediate format.

In a second reformat procedure, the resulting message is interpreted
according to a predefined input format SWIFT-IN2, which splits the contents
of the message into its logical parts or elements, respectively:
ApplicationIdentifier
ApplicationUnitDataIdentifier
BankCode
etc.
The message, now split in its logical parts, is then mapped to a second
predefined output format XML-OUT. This output format predefines the
complete XML structure by combinations of XML tags and values gained from
the input message.
To define the input and output formats, we use the New Era Of Networks
Formatter:
308
Figure 8-36 Scenario 3a: NEON Formatter GUI showing input format SWIFT-IN1 and
output format SWIFT-OUT1
Since we need two reformat procedures, we need to define two input and two
output formats:
SWIFT-IN1 -> SWIFT-OUT1
SWIFT-IN2 -> XML-OUT
309
The definition of the XML output format implies an enormous definition effort.
Since the complete XML structure of the message is predefined, we need to
define a large number of:
Literals
Fields
Defaults
Output Controls
This is a very trying task if you do not have an XML adapter available.
Once we have built the input and output formats, we have to define the sequence
in which the formats have to be used for the reformat operations. This means we
have to define that SWIFT-IN1 has to be used first, followed by SWIFT-OUT1,
then SWIFT-IN2, then XML-OUT.
This is done again in the New Era Of Networks environment by using the New
Era Of Networks Rules GUI, where we define a combination of Application Group
and MessageType. An NEON Application Group is comparable to the Message
Set used with WebSphere MQ Integrator. We call this Application Group
SWIFTSampleScenario2. MessageType is the name of the initial input format
(SWIFT-IN1) with which we start our reformat operations.
In addition to Application Group and MessageType, we need to define a rule and
a subscription combined with this rule. The rule is a simple dummy rule that
checks whether there is a specific field with the message (here:
BasicHeaderData); the subscription describes the sequence of operations on a
message that must be performed when the rule hits. The rule definition is shown
in Figure 8-37. The subcription definition is shown in Figure 8-38.
310
Figure 8-37 Scenario 3a: NEONRules definition
Figure 8-38 Scenario 3a: NEONRules Subscription definitions
311
Application Group and MessageType information is needed to identify messages

in the New Era Of Networks domain and to know how to treat them, and is
comparable to the message set, message type and message information in an
MQSeries Integrator environment.
The message flow in this scenario consists of:
An MQInput node (Get SWIFT Message) that reads the message from an
input queue and refers to the input format SWIFT-IN1 in the NEON domain.
A NeonRules node (Apply NeonRules) that performs the steps defined using
the NEONRules GUI.
An MQOutput node (XML-OUT) that puts the reformatted message to an
output queue.
In addition to these nodes, we need to connect the failure terminal of the

NEONRules node to an MQOutput node (RULESFAIL) and the nohit terminal of
the NEONRules node to another MQOutput node (NOHIT). The complete
message flow is shown in Figure 8-39.
Figure 8-39 Scenario 3a: transforming NEON message to XML
The settings for the nodes used in this scenario are shown in the next figures.
312
Note that Message Set refers to the name of the Application Group and that
Message Type refers to the name of the predefined input format with which we
start the reformat sequence as specified in the Formatter GUI.
The NEONRules node has no properties to be considered. It is just an
instantiation of the NEON RulesEngine.
Figure 8-41 Scenario 3a: NEONRules node
After putting the reformatted message to the destination queue, the message is
313
Figure 8-42 Scenario 3a: resulting XML message
Another way to achieve the same result without using NEONRules is to define a
message flow with a sequence of two NEONFormatter nodes, as shown in
Figure 8-43.
The initial input format SWIFT-IN1 is defined in the MQInput node (Get SWIFT
Message) given as MessageType (see Figure 8-44 on page 315). The first
NEONFormatter node in the sequence (see Step1 of the SWIFT reformat,
Figure 8-45 on page 316) defines the intermediate output format (SWIFT-OUT1)
as target format and, additionally, defines the second input format (SWIFT-IN2)
to which the reformatted message from step1 is passed.
314
It is important to define the New Era Of Networks domain in this node, since the
message has to be parsed in the NEON domain. The second NEONFormatter
node (see Step 2 of the SWIFT reformat, Figure 8-46 on page 316) simply
defines the second output format (XML-OUT) to which the message has to be
reformatted before it is passed to the MQOutput node.
Figure 8-43 Scenario 3a (Alternative 2) Message flow
These are the properties of the nodes in the message flow:
Figure 8-44 Scenario 3a (Alternative 2) MQInput node
315
Figure 8-45 Scenario 3a (Alternative 2) NEONFormatter node
Figure 8-46 Scenario 3a (Alternative 2) NEONFormatter node
316
Scenario 3b
In Scenario 3b, we use a predefined XML output format in the New Era Of
Networks environment.This may be feasible with a short message, but it is too
problematic with a large message, where we would have to define hundreds of
literals, fields, output operations and output controls. With MQSeries Integrator
V2.0.1, an XML adapter may be a solution. With WebSphere MQ Integrator, we
can construct an output message using the new NEONTransform or NEONMap
nodes in the NEONMSG domain, without an XML adapter and without
predefining the XML output format.
Since we still work with a two step reformat procedure to extract our data, we use
a combination of NEONFormatter and NEONTransform/NEONMap node.
Working in both New Era Of Networks domains (NEON and NEONMSG), we
also need a ResetContentDescriptor node in this example.
The message flow is shown in Figure 8-47.
Figure 8-47 Scenario 3b: message flow
The MQInput node defines the initial input format SWIFT-IN1 in the NEON
domain, as shown in Figure 8-48.
317
The NEONFormatter node (implementing the first phase of the reformat)

specifies the first target format as SWIFT-OUT1 and the second input format,
Output Type, as SWIFT-IN2:
Figure 8-49 Scenario 3b: NEONFormatter node
318
The ResetContentDescriptor node resets the domain from NEON to NEONMSG:
Figure 8-50 Scenario 3b: ResetContentDescriptor node
The NEONMap node (we could use a NEONTansform node instead) defines the
second output format SWIFTOUT as the ultimate target format and the output
domain XML as the target domain.
Note that SWIFTOUT is a flat output format and defines only the output fields of
the message and not the XML tags, as in scenario 3a.
Figure 8-51 Scenario 3b: NEONMap node
319
The resulting message is shown in Figure 8-52.
Figure 8-52 Scenario 3b: Resulting XML message
8.4.4 Scenario 4: Routing a message using a NEONRules node

In scenario 4, we work on the same SWIFT message as with the other samples.
This time, depending on the Country Code provided in the message, we wish to
place the message on different output queues.
In Scenario 4a, we work in an MQSeries Integrator V2.0.1 environment. The
SWIFT message is received and transformed from SWIFT to XML, as in
Scenario 3. The necessary input and output formats are predefined in the NEON
environment. The routing information is defined in the NEON Rules environment.
320
In scenario 4b, as an alternative to using the NEONRules node, we modify the

flow using the NEONRulesEvaluation node in the NEONMSG domain.
Scenario 4a
The message flow in scenario 4a is shown in Figure 8-53.
Figure 8-53 Scenario 4a: message routing using NEONRules
The SWIFT message is received by an MQInput node (Get SWIFT Message),

which parses the message with the predefined input format SWIFT-IN1 in the
NEON domain, as shown in Figure 8-54.
In the NEONFomatter node (transforming SWIFT-IN1 to SWIFT-OUT1, as shown in

Figure 8-55) we specify the first (intermediate) output format SWIFT-OUT1 and the
second input format SWIFT-IN2 to reparse the message. Additionally, we refer to
the Application Group (SWIFTSampleScenario4), which is defined in the Rules
environment.
321
Figure 8-55 Scenario 4a: NEON Formatter node
The NEONRules node does not contain any significant definitions. It is just an
instantiation of the NEON rules engine, as shown in Figure 8-56. The node
transforms the message from SWIFT-OUT1 to SWIFT-IN2, converting the message
to XML, and routes it to its destination.
Figure 8-56 Scenario 4a: NEON Rules node
The putqueue terminal of the NeonRules node is connected to an MQOutput

node (Output to Destination List), which defines Destination List as output.
The Destination Mode is set on the Advanced tab of the MQOutput node, as
322
Figure 8-57 Scenario 4a: MQOutput node (Output To Destination List)
Since we use Destination List as output, queue definitions are not required in
the basic tab of the MQOutput node, as shown in Figure 8-58.
Figure 8-58 Scenario 4a: MQOutput node
The NEON Rules environment defines the routing conditions for the message as
rules. Figure 8-59 shows the definition of the rules.
323
Figure 8-59 Scenario 4a: Rule definitions in the NEON Rules environment
Rules exist for a number of countries, as shown in Example 8-8.

Example 8-8 Defined rules for the field Country Code
Country
Country
Country
Country
Code
Code
Code
Code
=
=
=
=
"BE"
"GE"
"UK"
"US"
Associated with the rules are a number of subscriptions. Figure 8-60 shows the
actions associated with the rule Country Code = "BE".
324
Figure 8-60 Scenario 4a: subscription definitions in the NEON Rules environment
All actions associated with the rules as subscriptions are listed in Example 8-9.
Example 8-9 Defined subscriptions and their actions
reformat
reformat
reformat
reformat
SWIFT-IN2
SWIFT-IN2
SWIFT-IN2
SWIFT-IN2
->
->
->
->
XML-OUT
XML-OUT
XML-OUT
XML-OUT
+
+
+
+
putqueue
putqueue
putqueue
putqueue
BELGIUM
GERMANY
UK
US
Scenario 4b
Within the NEONMSG domain, the NEONRules offer a broader functionality with
NEON messages. The putqueue and the new introduced route action cause the
LocalEnvironment (previously called Destination List) of the output message to
be appropriately configured for processing by an MQOutput or a RouteToLabel
node.
Within WebSphere MQ Integrator, we can build an alternative to the flow build
with MQSeries Integrator V2.0.1 by using some of the new functionality
introduced with the NEONMSG domain.
The completed message flow is shown in Figure 8-61.
325
Figure 8-61 Scenario 4b: message flow
The MQInput node (Get SWIFT Message, Figure 8-62) parses the SWIFT
message in the NEONMSG domain with an input format SWIFT-IN4 (quite similar
to SWIFT-IN1). It specifies the MessageSet SWIFTSampleScenario4b, which
refers to the Application Group in the NEONRules environment.
326
The NEONRulesEvaluation node does not contain any significant definitions, as

shown in Figure 8-63. It is just an instantiation of the NEON rules engine. The
node transforms the message from SWIFT-IN4 to SWIFTOUT as XML and applies
the routing rules.
Figure 8-63 Scenario 4b: NEONRules Evaluation node
The Label node (Figure 8-64) simply defines the label associated with this node.
The output terminal of the Label node is connected to an MQOutput node,
defining the queue BELGIUM as target queue of the message.
Figure 8-64 Scenario 4b: Label node (Label = BELGIUM)
The rules are defined in exactly the same manner as in Scenario 4a, as shown in
Figure 8-65 and Figure 8-66.
327
Figure 8-65 Scenario 4b: rule definitions
Figure 8-66 Scenario 4b: rule definition (Country Code = BE)
The subscriptions offer a broader range of functionality. In our example, we first

define a Transform action for the message from SWIFT-IN4 to SWIFT-OUT, as
328
Figure 8-67 Scenario 4b: subscription Step 1 (Transform to target format SWIFT-OUT)
In a second step, we route the message to Label BELGIUM and transform it from
NEONMSG to XML, as shown in Figure 8-68.
329
Figure 8-68 Scenario 4b: Subscription Step 2 (Route to Label)
The advantage in Scenario 4b is obvious: we do not have to have a predefined

XML format in the NEON environment to transform the domain of the message
from NEONMSG to XML, and we have a full integration of the NEONMSG
domain to the WebSphere MQ Integrator environment for use by any other nodes
and procedures.
8.4.5 Scenario 5: Further exploitation of WebSphere MQ Integrator

features for NEONMSG messages
In Scenario 5, the SWIFT message is received in the NEONMSG domain, and is
reformatted in a first step from a given input format (SWIFT-IN5) to a given output
format (SWIFT-OUT5) within the New Era Of Networks environment, by using the
appropriate nodes in a message flow. In a second step, the output format
(SWIFT-OUT5) is added to the current workspace of the WebSphere MQ
Integrator Control Center in the NEON Message Set. After having the message
reformatted from SWIFT-IN5 to SWIFT-OUT5, we refer to some of the fields in
330
the NEON Message Set in a database node, where we extract the values of
these fields and store them in a database. In parallel, the message is
transformed into generic XML and is passed to an MQOutput node for further
processes.
The input format SWIFT-IN5 and the output format SWIFT-OUT5 are defined in
the NEON domain, using the NEONFormatter (see Figure 8-69):
Figure 8-69 Scenario 5: NEONFormatter showing input format SWIFT-IN5 and output
format SWIFT-OUT5
331
The message flow for this scenario is shown in Figure 8-70.
Figure 8-70 Scenario 5: Message flow
The MQInput node (Get SWIFT Message, as shown in Figure 8-71) receives the
SWIFT message in the NEONMSG domain and instructs the NEONMSG parser
to parse the message according to the definitions, given with input format
SWIFT-IN5.
Figure 8-71 Scenario 5: MQInput node
One of the involved NEONTransform nodes (named Transform SWIFT-IN5 ->

SWIFT-OUT5 + XML, as shown in Figure 8-72) reformats the message into the
predefined output format SWIFT-OUT5 and resets the message domain from
NEONMSG to XML before it passes the message on to the MQOutput node.
332
Figure 8-72 Scenario 5: first NEONTransform node
The second NEONTransform node (named Transform SWIFT-IN5 -> SWIFT-OUT5,

as shown in Figure 8-73) simply reformats the message into the defined output
format, without resetting the message domain.
Figure 8-73 Scenario 5: second NEONTransform node
To be able to work with the NEON Message Set in the Database node we use in
this message flow, we need to define the following session entry in our database
connection file (nnsyreg.dat) for the NEON database. Note that this entry is
necessary only on the machine where you run the Configuration Manager. The
values in the session definition depend on the database you use.
333
Example 8-10 Session definition for use by the Configuration Manager

Session.MQSI_CONFIG
NNOT_SHARED_LIBRARY
NN_SES_SERVER
NN_SES_USER_ID
NN_SES_PASSWRD
=
=
=
=
=
dbt26db250
NNSesDB2Factory
<dbms instance>
<user>
<password>
After adding this session entry to our database connection file, we have to restart
the Configuration Manager and the Control Center for the information to be
picked up by the Configuration Manager.
In the Control Center we go to the Message Sets tab, right-click Message Sets
and add the NEON Message Set to our workspace by selecting:
Message Sets -> Add to Workspace -> Message Set -> NEON Message Set
Figure 8-74 Scenario 5: adding the NEON Message Set
When the NEON Message set has been added to the current workspace, we add
the NEON formats we want to work on, as Elements:
Elements -> Add to Workspace -> Element
In our case, we select the output format SWIFT-OUT5 (Figure 8-75).
334
Figure 8-75 Scenario 5: adding element SWIFT-OUT5
When the output format SWIFT-OUT5 has been added to the workspace, we are
able to work on this message set in other nodes, such as Compute nodes.
Note: You can only view NEON Message Sets. You cannot edit, change or
re-arrange the components in the Control Center. This still has to be done in
the NEON environment, using the NEONFormatter GUI.
335
Figure 8-76 Scenario 5: NEON Message Set SWIFT-OUT5
Now we work on the Database node (Store BankCode, CountryCode, etc., as

shown in Figure 8-77) and we refer to the NEON Message Set by clicking the
Add button on the input side (Figure 8-78).
336
Figure 8-77 Scenario 5: database node
In the Message field, we enter a name for our message. In this case, it is SWIFT.
Figure 8-78 Scenario 5: constructing the input side by defining the message (SWIFT)
337
Figure 8-79 Scenario 5: resulting entry in the database node after defining the message
name
The button Add element allows you to select elements (fields) from the NEON
Message Set (Figure 8-80).
Figure 8-80 Scenario 5: constructing the input side by selecting elements from the NEON
Message Set
338
Figure 8-81 Scenario 5: resulting input mesage
In our scenario, we choose the elements (fields) BankCode, BranchCode,

CountryCode, LocationCode and Text4 (containing customer information). On
the output side, we add the database (SAMPLE) and the database table
(SWIFT).
This table has the columns BANKCODE, BRANCHCODE, COUNTRYCODE,
LOCATIONCODE and CUSTOMERINFO. By selecting the Add Column button
(Figure 8-82 and Figure 8-83), we can add a reference to these columns to the
Database node.
339
Figure 8-82 Scenario 5: constructing the output to a database by defining database

(SAMPLE) and table (SWIFT)
Figure 8-83 Scenario 5: constructing the output to a database by defining the columns in
the SAMPLE database
When all columns are added, the Database node should look like the one shown
in Figure 8-84.
340
Figure 8-84 Scenario 5: resulting output defintion
Finally, we code the ESQL statement (Example 8-11 ) that puts the values of the
message into the database (Figure 8-85).
Example 8-11 ESQL insert statement
INSERT INTO DATABASE.DB2ADMIN.SWIFT (BANKCODE,COUNTRYCODE,
BRANCHCODE,LOCATIONCODE,CUSTOMERINFO) values
("Body"."BankCode","Body"."CountryCode","Body"."BranchCode","Body"."LocationCod
e","Body"."Text4");
341
Figure 8-85 Scenario 5: ESQL code to input selected data from the NEON message into
the SAMPLE database
When a message has been passed through this message flow, the XML
message is put to the defined output queue and parts of the message are written
into the database (Figure 8-86).
Figure 8-86 Scenario 5: Resulting contents of the SWIFT table
342
Note: You need to add a session entry Session.MQSI_PLUGIN to the

database connection file (nnsyreg.dat) on the machine where your broker is
running, to work with the NEON nodes:
Session.MQSI_PLUGIN
NNOT_SHARED_LIBRARY
NN_SES_SERVER
NN_SES_USER_ID
NN_SES_PASSWRD
=
=
=
=
=
dbt26db250
NNSesDB2Factory
<dbms instance>
<user>
<password>
After adding this session entry to your database connection file, you need to
restart the broker for the information to be picked up.
8.4.6 Scenario 6: Simulating the rules engine

In scenario 6, we look at a message flow that simulates the rules engine of
previous MQSeries Integrator and New Era Of Networks product versions.
The NEONRulesEvaluation node is the core node in a message flow that allows
it to behave similarly to the rules engine process. In the example shown in
Figure 8-87, we have a simple NEONRulesEvaluation node surrounded by
MQInput and MQOutput nodes. The properties of each are discussed below.
Figure 8-87 Migration message flow
MQInput node NNSY.IN

The MQInput node provides much of the information that was formerly in your
Rules Engine (RULENG) parameter file with MQSeries Integrator V1.11. Under
the Basic tab, we have the Queue Name (Figure 8-88). This obviously equates
InputQueueName in the parameter file.
343
Figure 8-88 MQInput node properties, Basic tab
The Default tab provides information on how to process the message if it does
not have an MQRFH (or the newer MQRFH2 header). The Message Set field
equates DefaultAppGroup and the Message Type equates DefaultMsgType that
was formerly in the rules engine (RULENG) parameter file.
The Message Domain should be defined as NEONMSG from the pull down menu
(Figure 8-89).
344
Figure 8-89 MQInput node properties, Default tab
Using an MQRFH or MQRFH2 header

There should be no reason to change your existing applications when using
WebSphere MQ Integrator. If you already use an MQRFH header then it will be
correctly parsed in the NEONMSG domain against the Message Type and
Application Group within the header. None of the fields on the Default tab of the
MQInput node will be used.
If you are building new applications, you are advised to use the MQRFH2 header
and, preferably, messages defined in the MRM. If, however, you are writing a new
application using an old message format defined using the New Era Of Networks
GUI, you may use the MQRFH2 header. In this instance, you must define the
domain as NEONMSG, using the <msd> field in the <mcd> folder.
The MQRFH2 is detailed in the WebSphere MQ Integrator Programming Guide,
SC34-5603.
NEONRulesEvaluation1 node
This is a NEONRulesEvaluation node, which has no properties set. It has five
output terminals which are discussed in NEONRulesEvaluation1 node on
page 345. In the message flow shown in Figure 8-87 on page 343, we have
connected up the failure, nohit and putqueue terminals.
345
NNSY.RULES.FAILED and NNSY.NOHITS

These nodes are both MQOutput nodes with just Queue Name configured under
the Basic tab. Once again, we have named the nodes to match the queues we
are using. The Queue Manager property on the Basic tab is left blank. It then
defaults to the brokers queue manager name.
Routing errors to a remote queue manager

If you centralize your error handling, you may want to route these errors to a
different queue manager. You can use a remote queue name in the Queue Name
field on the MQOutput node. Alternatively, if you do not use remote queue
definitions, you can use the Queue Name property together with the Queue
Manager property on the MQOutput node. WebSphere MQ Integrator will
attempt to resolve this to a transmission queue. Refer to your MQSeries systems
administrator for information on how your definitions are configured.
NNSY.PUTQUEUE.ACTION
This node is also an MQOutput node, but it is configured differently so that your
rules and subscriptions can decide where your output message goes.
The Basic tab is left blank with no values for the Queue Name or Queue Manager
Name properties.
The Advanced tab is configured with the Destination Mode property set to
Destination List from the drop-down menu. When a rule results in a putqueue
action, WebSphere MQ Integrator passes the queue name internally in the
message (in the LocalEnvironment folder of the message tree) for the MQOutput
node to process. Refer to Figure 8-90 for details.
346
Figure 8-90 MQOutput node properties for New Era Of Networks support
8.4.7 Other migration considerations

The basic flow described in 8.4.6, Scenario 6: Simulating the rules engine on
page 343, when deployed to a broker, replaces your rules engine (RULENG).
However, there are a number of other considerations to take into account to
ensure that all MQSeries Integrator V1.11 functionality is correctly configured in
WebSphere MQ Integrator V2.1.
Configuring WebSphere MQ Integrator to match your rules

engine
You need to consider how you have configured your existing rules engine
(RULENG) to behave and how the equivalent can be configured with WebSphere
MQ Integrator. Table 8-4 on page 348 discusses the various configuration
options and how each behavior can be configured in WebSphere MQ Integrator.
347
Table 8-4 Rules Engine (RULENG) parameter file values in WebSphere MQ Integrator
348
Rules Engine parameter
Configuration equivalent
CredentialsEnabled
This is configured on all the MQOutput

nodes. The default action of an MQOutput
node is to put using the authority of the
broker, which resolves to
CredentialsEnabled=0. If you have
configured CredentialsEnabled=1 then
you should select the Alternate User
Authority box in the Advanced tab of the
MQOutput nodes.
QueueManagerName
The queue manager name is configured

when you build a broker. If you have more
than one MQSIRuleng running against
different queue managers, you will need
more than one broker.
MaxBackoutCount
This parameter is configured on the input

queue (BOTHRESH), together with a
backout queue name (BOQNAME). If the
broker tries to process a message that
exceeds the backout count, it will put it on
the backout queue. To emulate
MQSIRuleng behavior, the backout queue
name should match the RulesEvaluate
failure queue.
InputQueueName
This is configured with the Queue Name

on the MQInput node. You can have
multiple input queues using multiple
MQInput nodes.
NoHitQueueName
The is configured by attaching the nohit

terminal of the NEONRulesEvaluation
node to an MQOutput node with the queue
name configured in the Basic properties.
FailureQueueName
This is configured by attaching the failure

terminal of the NEONRulesEvaluation
node to an MQOutput node with the queue
name configured in the Basic properties.
DefaultAppGroup
This is configured on the Message Set

parameter under the Default tab of the
MQInput node. You must also specify
Domain as NEONMSG.
Rules Engine parameter
Configuration equivalent
DefaultMsgType
This is configured on the Message Type

parameter under the Default tab of the
MQInput node. You must also specify
Domain as the NEONMSG.
MaxHandles
The number of MQSeries queue handles

used by the broker is managed internally
and is not configurable.
PurgeInterval
The number of MQSeries queue handles

used by the broker is managed internally
and is not configurable.
LogFileName
Errors are written to the console and to

stderr, stdout and NNSYMessageLog.nml
files.
LogLevel
This is configured in the brokers

nnsyreg.dat file as follows:
Broker.Logging
LogLevel=0
ServerName
This is configured in the brokers copy of

nnsyreg.dat with the NN_SES_SERVER
parameter.
UserId
The user ID and password come from the

broker task and are not configured in a
parameter file.
Password
The user ID and password come from the

broker stated task and are not configured
in a parameter file
DatabaseInstance
This is configured in the brokers copy of

nnsyreg.dat with the NN_SES_DB_NAME
parameter.
DatabaseType
The databse type is implied in the brokers

copy of the nnsyreg.dat file from the
NNOT_SHARED_LIBRARY and
NNOT_FACTORY_FUNCTION values.
349
Multiple databases and rules engines

A single broker can only use one rules and formats database schema.
Furthermore, a single queue manager can only run one broker.
You may have many rules engines accessing rules and formats in different
schemas and processing messages from many input queues. This might occur
for a number of reasons, such as workload separation, performance or change
management. If each database schema contains only a subset of the rules and
formats used by the organization, then you will need to plan your implementation
carefully.
Additional input queues

If all the rules engines access the same databases, but use different input
queues, you can simply add additional MQInput nodes in your message flow or
create separate message flows. If the additional rules engine instance was
created for performance reasons, then a WebSphere MQ Integrator broker can
be configured with additional execution groups. By assigning the message flows
to multiple execution groups, you will get the same level of parallelism.
Additional brokers
If you can justify the additional overhead, you can run more than one broker on a
single machine. Each broker requires its own queue manager and can be
configured to use a separate rules and formats database schema.
Merging database schemas

Rules and formats can be merged into a single database schema, provided your
object names do not conflict with each other. To do this, you will need to export all
rules and formats from your existing schemas and import them into a single
schema using NNFie and NNRie. This is the preferred method and offers the
greatest flexibility when using WebSphere MQ Integrator features.
350
Chapter 9.
Developing and deploying

custom nodes in Java
This chapter describes the process and requirements for developing and
implementing custom built Java plug-in nodes. We will show some example
programs for both standard plug-in nodes and input nodes based on the new
Java support in WebSphere MQ Integrator.
The examples in this chapter were developed, compiled and tested on Windows
2000 for simplicity, since the Control Center is only available for the Windows
platform. Therefore, most of the command examples are for a Windows
environment. There are, however, several Unix-based commands here for
reference. If you remove all native references from your Java code, you should be
able to deploy the same custom code on any platform that supports WebSphere
MQ Integrator brokers and the same JDK level.
351
9.1 What can you do with a Java plug-in?

With WebSphere MQ Integrator, there is new support for building custom plug-in
nodes and parsers in Java or C. There is also new support for input nodes written
in Java. This opens up the possibilities of dramatically expanding your message
integration capability. By writing your own custom plug-in and input nodes, you
can expand existing functions or develop new nodes that are designed for very
specific needs.
You may want to develop your own plug-in nodes so that a specific data element
in an XML document would determine where a message should be routed. You
may also want to change this same data element to another value based on
certain rules.
With custom input nodes, it is possible to have a program read a file from a
directory and bring it into the message flow. This eliminates the need to use an
MQSeries queue as the input of a message flow, allowing your architecture more
flexibility. Perhaps you want the input node to listen to a specific port for a data
stream; this is also possible. In the event that you would like to create a custom
output node, simple utilize a custom built Java plug-in node as the final step in
the message flow and write the data to your preferred location, such as a
database or directory.
By using the information in this chapter, the WebSphere MQ Integrator
Programming Guide, the javadoc which can be found in the JavaAPI directory of
your WebSphere MQ Integrator installation (please see
<install_dir>\docs\JavaAPI\index.html) and some Java programming knowledge,
you should be able to write your own custom plug-in and input nodes.
9.1.1 Plug-in nodes

In MQSeries Integrator Version 2.0.x, it was possible to build custom plug-in
nodes using C, but now with WebSphere MQ Integrator Version 2.1, it is also
possible for them to be written in Java. These programs are compiled and
packaged into a Java Archive File (JAR). These JAR files are loaded and cached
by the broker on start-up.
The support for building custom input nodes is new for this release for both C and
Java. We will describe the Java support here. Please refer to the WebSphere MQ
Integrator Programming Guide for more information about both possibilities.
The ability to write your own nodes in Java is made possible by extending
interfaces and packages that are shipped with the product. Specifically,
jplugin.jar contains the important classes and can be found in the classes
directory. If you would like to see the specific classes, unzip the .jar file in the
352
directory from the <install_dir>\classes directory. You should find several new
sub-directories creating the path /com/ibm/broker/plugin/. In the plugin directory,
you will see several classes that should match the classes found in the Java API
documentation, found in:
<install_dir>\docs\JavaAPI
(for Windows NT/2000)
<install_dir>/docs/JavaAPI
(for UNIX platforms including z/OS
There are two important interfaces that should be reviewed before attempting to
write a new plug-in node. In the javadoc, you will see a listing for
MbNodeInterface and MbInputNodeInterface. These interfaces are for standard
Java plug-in nodes and Java input nodes, respectively. The implementation and
skeleton code are described in the JavaAPI javadoc for reference.
9.1.2 MbInputNodeInterface
The input node interface is designed to shield the programmer from the internal
operations of WebSphere MQ Integrator input features. Though most of the
communication and specification has been encapsulated, you still need to follow
several procedures such as setting your new node to extend MbInputNode,
create the output terminal definitions (there is no need fo an input terminal) and
assemble the new message using MbMessageAssembly. If an error does occur
and you want WebSphere MQ Integrator to be aware of it for error handling,
throw a message to MbException. All other processing logic can be built to suit
your needs, for example, to monitor a directory, FTP, HTTP or a telnet session. In
Section 9.3, Implementing an input node on page 355, we will provide some
specific examples.
9.1.3 MbNodeInterface
The node interface is the standard interface definition for all plug-in nodes other
than input nodes. As with the MbInputNodeInterface, the developer has been
shielded from implementation details but must adhere to a general framework.
The important aspects to note are that your plug-in node must extend MbNode.
Unlike MbInputNode, you must define your input terminal at the same time you
define your output terminals. MbMessageAssembly and MbException are used
just like the previous interface. All other processing logic can be built to suit your
needs. You could use a plug-in node to process specific data formats or
implement specific application logic. Based on the content of the message, you
could route the message to one of multiple output terminals or even translate it
into entirely new content taken from multiple data sources. In Section 9.4,
Implementing a plug-in node on page 371, we will provide some specific
examples.
Chapter 9. Developing and deploying custom nodes in Java
353
9.2 Getting started

This section outlines several steps which will help you get your environment
configured so that you can quickly begin to develop and utilize custom plug-in
and input nodes.
9.2.1 System requirements

Developing custom nodes can be done on the same development workstation
that is configured to run a Control Center once a WebSphere MQ Integrator
installation has taken place. Verify the installation through the steps outlined in
the Getting Started section of the proper installation guide for your operating
system.
The only other software requirement is to have a Java Development Kit (JDK)
installed and the path pointing to the correct bin directory. You can verify your
JDK installation by opening a command prompt and typing Java -version. It is
recommended that you use the most current IBM JDK (at the time of writing this
redbook, this is JDK 1.3.0).
You may choose to develop your programs with an IDE or GUI development
environment such as VisualAge for Java, though a standard text editor will be
sufficient for these examples.
9.2.2 Programming requirements

In order for your new programs to see the required classes during compilation,
your classpath must include also the new Mb*.classes found in the jplugin.jar.
This can be done by setting your classpath to look at the directory:
<install_dir>\classes\jplugin.jar
(for Windows NT/2000)
<install_dir>/classes\jplugin.jar
(for UNIX platforms, including z/OS
9.2.3 Debugging and logging

When running your own custom node, it is possible to write events to the system
log by using the static method MbService. There are some examples of this in the
code snippets below.
Once you write a custom node and deploy it by restarting the broker, there are
some ways to view the activity of the node and broker in real time. These
instructions are for Windows NT/2000, but there are similar possibilities for Unix
and other operating systems.
354
In the Services control pane, set your broker to run with the local system account
(assuming you are logged in as a user that is a member of the Administrators
group) and select Interact with Desktop. When you restart the broker, you will
see two command windows open up. One of these windows will display standard
output sent from your Java plug-in nodes when executed. If you include such
lines as:
System.out.println("This is my debug message")
then you can see how your program is doing. This is only a temporary debugging
feature for development. You should not rely on these messages for a production
environment because the system standard out settings will most likely be
unusable and/or unpractical.
For a more permanent tracing and logging feature, you should instead have the
messages that you need written to a log file. By using the attributes (discussed
later) options in WebSphere MQ Integrator, you can set a tracing level such as 0,
1 or 2 and the path to where a file should be written. This way, you should be able
to write a custom node program once in Java, but generate a logging file on
many platforms if your dynamic path settings are correct.
Version 1.4 of Java (currently available in Beta at the time of this writing) provides
new Logging APIs. When it is available for wide release, you could interface to
these APIs to provide more robust logging capability, or continue to use your own
code.
9.3 Implementing an input node

This sample program is a simple, yet very powerful tool. It lets you read a file
from a system directory as the input to a message flow rather than from a
MQSeries queue.
You can begin to write your input node based on the code found in Appendix B,
Source code for the Java extensions to WebSphere MQ Integrator on
page 415. For more assistance, please see also the WebSphere MQ Integrator
Programming Guide.
9.3.1 The Java code

These code snippets are taken from a program that can read a file from a
directory and receive data from a telnet data stream. The basic structure of the
controlling Java class will be outlined here so that we may discuss it. For the
other supporting classes that you will need and for the full SocketNode.java code,
please refer to the Appendix B.1.1, SocketNode.java on page 416.
355
The main class for an input node should be declared like this:
Example 9-1 Extending MbInputNode and implementing MbInputNodeIterface
public class SocketNode extends MbInputNode implements MbInputNodeInterface
You will also need to declare variables that will correspond to attributes defined in
the WebSphere MQ Integrator node installation. The values of these attributes
can be set when the node is used in a message flow.
Example 9-2 Setting attribute variables
String _filePath = "";
String _dataSource = "";
String _portNumber = "";
Example 9-3 shows the function calls to tell a message flow what the names of
the output terminals should be. On a standard plug-in node, you also need to
define input terminals.
Example 9-3 Creating terminals
public SocketNode() throws MbException
{
// create terminals here
createOutputTerminal("out");
createOutputTerminal("failure");
}
For every attribute that you can set in the message flow, you must use similar
statements, as in Example 9-4, to extract the values at runtime in the broker. A
description of how to configure the attributes in WebSphere MQ Integrator will be
discussed in 9.3.3, Simple message flow to test the input node on page 360.
Simply stated, dataSource is the name of the attribute you will declare in a
message flow while _dataSource is the temporary variable that you will use for
internal processing in this program.
Example 9-4 Get and Set attributes
public String getDataSource()
{
return _dataSource;
}
public void setDataSource(String dataSource)
{
_dataSource = dataSource;
}
356
If you do want to have messages or errors sent to the system or event log file
through WebSphere MQ Integrator, utilize the MbService as follows:
Example 9-5 MbService
private void logError(String traceText) throws MbException {
MbService mbsLog = new MbService();
mbsLog.logWarning(
this, methodName, "com.ibm.samples.SocketNodeMessages", messageID,
traceText,new Object [] {});
}
The implementation of the class SocketNodeMessages is shown in Example 9-6.

Example 9-6 Error messages in a plug-in
package com.ibm.samples;
import java.util.*;
public class SocketNodeMessages extends ListResourceBundle {
/**
* <p>static multi-dimensional array used as a catalog structure to store
* messages containing a varying number of inserts, accessed via a msg
* key</p>
*/
private static final Object[][] contents = {
{"0E", "\r\nUnable to rename file.\r\n"},
{"1E", "\r\nUnable to open port."},
{"2E", "\r\nThe directory path specified is invalid.\r\nAborting read."},
{"3E", "\r\nUnable to read from file.\r\n"},
{"4E", "\r\nA general critial error occurred.\r\nThe stack trace is as
follows:\r\n"},
{"5E", "\r\nThe path specified is not a directory.\r\n"},
{"0W", "\r\nThe data source specified is invalid.\r\nDefaulting to Socket
mode, Port 3000.\r\n"},
{"0I", "\r\n-Debug Checkpoint Data- \r\n"},
};
public java.lang.Object[][] getContents () {
return contents;
}
}
357
The bulk of the input node program is reading data, building and passing the
message. Example 9-7 shows how we call a build to the message.
Example 9-7 MbMessageAssembly
public int run(MbMessageAssembly assembly) throws MbException {
byte [] generatedMessageBytes = null;
if (_dataSource.equalsIgnoreCase("file")) {
try {
generatedMessageBytes = useFilePath();
}
catch {
//some catch code here;
}
}
Furthermore, you need to include some code to look for the file in a directory,
then read it. The DirFilter is loaded as a separate class and can be found in
Appendix B.1.4, DirFilter.java on page 421.
Example 9-8 Reading the file based on the file path
private byte[] useFilePath() throws Exception {
String [] inputFileList = sourceDirectory.list(new DirFilter());
if (inputFileList.length >0) {
File sourceFile = new File(
_filePath + File.separator + inputFileList[0]);
File newSourceFile = new File(
_filePath + File.separator + inputFileList[0] + ".inuse");
byte[] inputBytes = new byte[1024];
InputStream in = new FileInputStream(newSourceFile);
ByteArrayOutputStream byteStream = new ByteArrayOutputStream();
int len;
while ((len = in.read(inputBytes)) > 0) {
byteStream.write(inputBytes,0,len);
}
in.close();
newSourceFile.delete();
return byteStream.toByteArray();
}
}
This is the basic structure of the program that you can use to retrieve a file from a
directory and pass it to WebSphere MQ Integrator as a message input rather
than from a queue. It is important to note here that we did not show any error
handling or exception catching scenarios in these snippets, but the full source
code in Appendix B.1, Java input node getting started example on page 416
shows you how to do this
358
9.3.2 Packaging and loading the input node

Now that your Java classes are written, you need to compile them using the
correct package specifications and build a JAR file.
1. The first step is to ensure that you place your Java files in a directory structure
that corresponds to the packages structure specified in your programs. For
this example, we used the package path:
2. If you used the same package path, then create a sub-directory structure
below a self-created working directory like javasource, such as:
<install_dir>\javasource\com\ibm\samples\
then copy all of your Java source files to that samples directory.
3. You must ensure that in your classpath, there is a reference to the jplugin.jar.
This file has the packages for the Mb*.class files that you will need for a
successful compilation.
4. Now you are ready to compile your source files. Open up a command window
and change to your working directory that has \com\ibm\samples\ below it,
such as:
cd <install_dir>\javasource\
5. Issue the command:

javac com\ibm\samples\*.java
If there are no errors, you should see the compiled *.class files in the same
directory as the source.
<install_dir>\javasource\com\ibm\samples\*.class
6. Now you need to create the JAR file. Change to your working directory using
cd <install_dir>\javasource\
7. Issue the following command in your working directory:

jar cvf SocketNode.jar com\ibm\samples\*.class
This should create a SocketNode.jar file in the directory that you are currently
in. By issuing the command:
jar tvf SocketNode.jar
you should see output that lists all of the classes that were added. Ensure that
all of the desired classes were added. The output looks like that shown in
Example 9-9 on page 360 if you followed the source that was in the appendix.
359
Example 9-9 jar tvf Sample Output

com/ibm/samples/DirFilter.class
com/ibm/samples/SocketNode.class
com/ibm/samples/SocketNodeException.class
com/ibm/samples/SocketNodeMessages.class
some Meta File information
8. Issue the command mqsistop <broker_name>.

9. All custom built plug-in nodes must be placed as JAR files in the lilpath
(Loadable Install Library), which is defined during installation or
customization. When installing WebSphere MQ Integrator on Windows 2000,
the default directory is <install_dir>\jplugin\. Therefore, it is necessary to copy
your newly created JAR file to this directory so that the broker will be able to
access it.
Tip: If you have a JAR file with the same name in the jplugin directory, attempt
to delete the old one before copying in the new one. If you are not allowed to
delete it, the broker or the Configuration Manager is still referencing it. If your
Configuration Manager is on the same machine as the broker, you will have to
stop the Configuration Manager also.
10.You can copy the new JAR file by issuing the command:
copy SocketNode.jar <install_dir>\jplugin\SocketNode.jar
11.Restart your broker with mqsistart <broker_name>.

You will need to restart your Configuration Manager if you had to stop it.
9.3.3 Simple message flow to test the input node

Now we will write a simple message flow to test our new input node.
1. Open the WebSphere MQ Integrator Control Center and proceed to create a
new message flow. For this simple test case, it is not necessary to create a
message set. Expand the Message Flows folder until you see IBMPrimitives.
Right-click IBMPrimitives and select Create Plugin Node.
You can use whatever Node Label you choose. It is best to make it something
meaningful, such as InputNode. For the Node Identifier, you must use the
value that is returned by the getNodeName function found in our program. For
this example, we used ComIbmSampleInputNode.
360
Important: In the first release of WebSphere MQ Integrator, it is required that

the Node Indentifier end with the word Node. However, there is also a known
bug within this release through which the word Node is added for you
automatically. Therefore, for our entry we actually used ComIbmSampleInput.
Which CSD level of WebSphere MQ Integrator you are working with could
determine if you should do this or not.
2. Now we will add the terminals. Since this is an input node, defining an In
Terminal has no effect. Therefore, we choose the word dummy to hold the
place value. The output terminals are, however, very important. Since this
node only accomplishes input and not any level of filtering, we only need two
output terminals, out and failure. Whatever values you use here must be the
same as given to the createOutputTerminal function in your program.
Figure 9-1 Creating Input Node
361
3. Click Next so that we can specify the attributes. These attributes correspond
to the fields that we specified in the various set methods of our Java program,
for example, when we declared:
Example 9-10 Attribute Extract from Declare
public void setDataSource(String dataSource)
{
}
The dataSource represents the attribute that we specify in this window. Click
InputNode in the Hierarchy then click Create Attribute. You must enter the
attribute names exactly as you did in your program. This is case sensitive. For
the first one we entered dataSource. Repeat the procedure until all of the
attributes that you declared have been added. For this example, we were able
to accept the defaults for all the other fields in this screen. Add the attribute
portNumber so that you can use it in our future discussion.
Figure 9-2 Creating Input Node 2
362
4. Click Next. In the next window, you can declare default values for the
attributes that you just specified. We left these fields empty so that there
would be no accidental parameter settings when using this node. By clicking
the Description tab, you can add a short and long description. It is
recommended that you do this here because once you click Finish, you
cannot edit this parameter further.
5. Click Next. In this window, there are other parameters than can be set. You
can have WebSphere MQ Integrator create some templates for files, create a
properties file (a file that contains start-up/run-time parameters.) or a Stub for
a customizer. Please refer to the Programming Guide for an explanation of
these special features. Click Finish to create the node.
6. Now under IBMPrimitives you should see your new custom input node. The
green box implies that this is a brand new node in a checked out state. You
can right-click it to check it in if you so choose.
Figure 9-3 New IBMPrimitive - InputNode
7. You are now ready to create a test message flow. Right-click the Message
Flows folder and select Create -> Message Flow. Give it a test name such
as InputNodeTestFlow.
8. Drag and drop your new InputNode into the window to the right. Right-click
the new node and select Properties. In the first window, use the dataSource
of file. For the filePath, use something meaningful to you such as
c:\temp\XML. This is where you are going to place test messages. If you want
to add another description, please do so now.
Figure 9-4 InputNode properties
9. Click OK. If you wish, you can change the name of the InputNode1 to
something else by right-clicking it and selecting Rename.
363
10. Now drag and drop one Compute node from the IBMPrimitives to the
Message Flow on the right. Since our message is coming from a directory
and not from an MQSeries queue, we need to attach a header to the
message. This is done by right-clicking the Compute1 node and selecting
Properties. Click the ESQL tab without selecting either Copy message
headers or Copy entire message. In the ESQL window, insert the code like
this:
Example 9-11 ESQL creating MQMD header
SET OutputRoot.MQMD.MsgType=MQMT_DATAGRAM;
SET OutputRoot.XML=InputBody;
11. Ensure that there is no message that says Syntax Error and click OK. You
can rename the node to MakeMQMD.
12. Now we need to add three output terminals. Drag and drop three MQOutput
nodes to the far right of the message flow. Rename each one of the output
terminals to Out, MQMDFailure, and Failure respectively.
13.For the Out terminal, right-click and go to Properties. Click the Basic tab. You
can leave the Queue Manager Name field blank. For the Queue Name, use
OUT_Q.
Figure 9-5 Defining the Out Queue Basic tab
14.Click the Advanced tab. For Message Context, select Default. If you not
want to add a description, click OK.
Figure 9-6 Defining the Out queue Advanced tab
364
15. Now set the Queue Names for the other output terminals. For MQMDFailure,
use MQMD_FAILURE_Q. For Failure, use FAILURE_Q. Make sure to remember to
set the Message Context to Default for each of them. Do not worry that you
have not created the queues yet, we will do it in another step.
16.Now that each of the output terminals has been defined, we need to connect
the nodes together. Right-click the Input Node and select Connect -> Out.
Attach the out connection to the MakeMQMD node. Connect the failure
connection to the Failure node (this is really just a dummy node; since there
is no MQMD attached, it is not accessible).
17.For the MakeMQMD, attach the out connection to the Out node and the
failure connection to the Failure node.
Figure 9-7 InputNodeTestFlow
18. Once you have set up your flow, click File -> Check In -> All (Saved to
Shared).
19. Before you deploy the flow, you need to create the queues on the respective
brokers queue manager. Do this by opening the MQSeries Explorer and
adding the queues with the exact names that we used above. If you used
different names than in our example, make sure that they are consistent with
the message flow. You can make simple queue definitions and accept the
defaults for this example.
365
Figure 9-8 Adding the correct queues to the Queue Manager
20. Now that your have added the necessary queues, it is time to deploy your
message flow to the broker. Return to the Control Center and select the tab
Assignments. Check out the default execution group of your broker (if that is
what you are using). Move the new message flow, InputNodeTestFlow, to the
correct broker. Check in the default execution group.
Figure 9-9 Assigning the InputNodeTestFlow
21. You may now deploy the changes to your broker by right-clicking the broker
name in the left pane and selecting Deploy -> Complete Assignments
Configuration.
22. Now by clicking the Log tab, and after waiting several seconds for the
processes to finish, you should be able to click the Refresh button and see
two messages returned to the display. If the deploy was successfull, then
there should be two messages with the blue "i" to the left. If the deploy was
not successful, it is important to read all the error messages associated with
deploying a flow with a custom built node, because the problem could have
several sources, from your Java code to the message flow to broker. Read the
messages carefully and you shouldeasily be able to determine what was
wrong with your configuration.
366
9.3.4 How to test the input node

The version of the samples program that we used takes any file from a directory
that we specify and places it into a WebSphere MQ Integrator message flow. For
this first example, all we did in the message flow test was to extract the file from
the c:\temp\XML directory, add the MQMD header and place the data of the file
into a queue called OUT_Q.
You may have noticed that when you deployed the message flow to the broker,
output was shown in one of the command windows that was started when you
started the broker service. Look for this output now; it should look something like
this.
Example 9-12 Sample standard output messages
MtiImbParserFactory::MtiImbParserFactory
Searching for Incoming File...none found.
Searching for Incoming File...
1. To test your message, create a simple piece of similar XML data using a text
editor such as Notepad:
Example 9-13 Simple XML test file
<data><action>add</action></data>
2. Ensure that there are no extraneous white spaces and save the file as
TestMessage.xml, but do not save it into the c:\temp\XML directory. You do
not have to use a true XML file for this example, but the file must end with the
.xml extension for it to be pulled from the directory. We are using a true XML
file here so that it can be reused if required in a future example.
3. Place a copy of the message into the c:\temp\XML directory; it should
immediately disappear from the directory. In the command window, you
should see a message that says File Closed. Message created.
Example 9-14 Sample standard output when file is created
File closed. Message created.
Searching for Incoming File...
4. Once you have tested your new node, you may want to stop the flow from the
Control Center using the Operations tab; right-click the flow and stop it. This
will keep the messages from deploying to the screen constantly or the
process from taking up system resources while your are developing the
application.
367
Figure 9-10 InputNodeTestFlow stopped
5. Now for the final assurance, open up the MQSeries Explorer. Double-click the
OUT_Q; if your message was created, it should be in the list. To view the
contents of your message, double-click the message then click the Data tab.
It may only let you select a hexadecimal format, but you should be able to see
the text of the message for verification.
Figure 9-11 Output for the XML test message
6. That is all there is to it to testing the input nodes directorys reading ability. If
you want to be able to change the location of the directory that is being read,
you will have to change the filePath setting in the message flow and redeploy.
368
9.3.5 How to use the input node to read a telnet stream

Included with the sample program SocketNode.java, there is also the
functionality to read data from a telnet stream and use it as input to a WebSphere
MQ Integrator message flow.
Necessary changes
1. If you have not yet saved your workspace in your Control Center, do so now
with a name like InputNodeTestWorkspace.xml. Also, this would be a good
time to stop running your InputNodeTestFlow if you have not done so
according to the instructions above.
2. Make a copy of your current message flow, by right-clicking the message flow
and selecting Copy. Then click the top-level Message Flow folder, right-click
and select Paste. The new copy will be given a default name. Change the
name of the new message flow to InputNodeTelnetTestFlow or something that
helps you remember the difference between the two.
Figure 9-12 New copy making InputNodeTelnetTestFlow
3. Now open the new message flow so that we can make some changes to the
custom node definition. Right-click the Input node and select Properties. For
the dataSource, change it to, for example, port. For the portNumber, you can
use any valid port number that is not already being used by this machine. We
are going to specify 3500, but the Java program will default to 3000 if you do
not specify a port.
Figure 9-13 Changing the port settings
4. Click OK. Check-in All (Save to Shared). Check-out the default execution
group of your broker and assign the new message flow to the broker. Check in
the default execution group. Deploy the Delta Assignments Configuration
for the broker.
369
Figure 9-14 Both Input Nodes deployed
5. Switch to the log view and wait for the confirmation messages to appear by
clicking the Refresh button.
6. Once the new flow begins, you should see in your standard output terminal
messages stating that it is waiting for incoming data. This is because the Java
program is monitoring the port constantly until it detects a new session being
started.
Example 9-15 Telnet session waiting for incoming data
Waiting
Waiting
Waiting
Waiting
Waiting
for
for
for
for
for
Incoming
Incoming
Incoming
Incoming
Incoming
Data...
Data...
Data...
Data...
Data...
Testing the telnet session input node

This test is based on having telnet access available and configured to the
machine where the broker is residing. To configure telnet access, please consult
your network administrator. At the very minimum, the administrator will need to
configure the telnet server to listen on the port that you specified.
1. Open a command window and run the telnet program by typing telnet and
the IP address of where the broker is located. If the telnet server of the
machine the broker is running on is listening on more than one port, you will
have to specify the same port that you defined in your node.
2. In your telnet session, you can begin typing XML directly into the session.
This is a way of testing the socket functionality. You would not do so in
production, but it is a simple way of testing port listening capability. Instead,
you would probably want to have XML come in through an HTTP session or a
batched telnet stream. As you type your XML, be careful to not use the
backspace or other non supported keys, because on some telnet sessions,
this will cause bytes to be placed in the stream that will invalidate your XML.
Make sure that you do not type extra spaces at the end of the string.
370
Type something simple like this:

Example 9-16 Sample XML
<data><action>add</action></data>
3. Now use the Escape keystroke for your telnet session. On Windows 2000 it is
CTRL+]. In your command window, you should see messages confirming that
a new message was created.
4. Check the OUT_Q to see if the XML data that you entered appears in the
queue.
Tip: In this chapter, we explain how to deploy a custom Java input node on a
Windows 2000 Broker installation. We did, however, conduct nearly these
exact installation steps to deploy the same JAR file on Solaris and z/OS
successfully without even recompiling the .java files. If you choose to try this
also, please ensure that you specify a correct path setting as your filePath
attribute.
9.4 Implementing a plug-in node

In 9.3, Implementing an input node on page 355, we describe in detail the steps
required to build a usable Java program, compile the package and release it with
a message flow. Since there is much overlapping between an input node and a
plug-in node, we will only discuss in this section the differences that you need to
be aware of. It is recommended that you review the WebSphere MQ Integrator
Programming Guide manual, section Programming a plug-in node or parser.
9.4.1 Details of the example

As with the input node example, this plug-in node example is a simple yet
powerful tool that allows you to read the contents of an XML file and route the
message based on the contents. The source code for the program is included
with the full WebSphere MQ Integrator installation. It can be found in
<install_dir>\examples\JavaPlugin\com\ibm\samples on a Windows 2000
installation. The file we are going to use is called SwitchNode.java, but in the
same directory you may notice that there is also a file called TransformNode.java.
We will explain SwitchNode.java in detail, but TransformNode.java is also a
useful program that shows you how to transform data from one value to another
in an XML document based on content. After completing this section and
reviewing the comments of TransformNode.java, you should have no trouble
deploying this.
371
The source code for both programs can be found in Appendix B.2, Java plug-in
node getting started example on page 422 and also in the Web materials. You
can learn how to access the Web materials from the Appendix , Locating the
Web material on page 445.
9.4.2 The Java code

Start by opening the source file SwitchNode.java in your favorite text editor. Read
the comments in the code to better understand what the program is to be used
for. The program will parse an XML message looking for the first occurrence of
the <action></action> tags. The message will then be routed to an output node
with a name matching the value found there.
Notice that this program implements a different interface than the input node:
Example 9-17 Implementing MbNodeInterface
public class SwitchNode extends MbNode implements MbNodeInterface
We also have to create an input terminal:

Example 9-18 Calling createInputTerminal
createInputTerminal("in");
Otherwise, the structure of the program is very much like that of the input node.
There are a few value changes, such as the string of getNodeName():
Example 9-19 getNodeName ComIbmSwitchNode
public static String getNodeName()
{
return "ComIbmSwitchNode";
}
There are only two sections of code that provide the functionality that we require.
We must parse the XML file and then determine where to route based on the
value found. Parsing the file is accomplished through only two lines of code since
MbElement is already provided for us.
Example 9-20 Parsing the XML content
MbElement rootElement = assembly.getMessage().getRootElement();
MbElement switchElement =
rootElement.getLastChild().getFirstChild().getFirstChild();
Our example XML data is going to look like this:

<data><action>change</action></data>
372
This way, the parser will be able to locate the appropriate tag. Depending on
which XML structure you are required to parse, this can be altered by the
getLastchild().getFirstChild() order or precedence.
Now that the parser has based the value of the action on the switchElement, we
can evaluate its contents. First, we have to cast the switchElement to a string:
Example 9-21 Casting switchElement to a string
String terminalName;
String elementValue = (String)switchElement.getValue();
Now that the value is housed in elementValue, we can evaluate it with simple if
-> then -> else logic:
Example 9-22 Evaluating elementValue
if(elementValue.equals("add"))
terminalName = "add";
else if(elementValue.equals("change"))
terminalName = "change";
else if(elementValue.equals("delete"))
terminalName = "delete";
else if(elementValue.equals("hold"))
terminalName = "hold";
else
terminalName = "failure";
Notice that if the elementValue does not have a match, the message will be
routed to the failure output terminal.
The last step is to let WebSphere MQ Integrator know which terminal we want to
send the message to. This is accomplished by defining the MbOutputTerminal
value and propagating it:
Example 9-23 Setting the MbOutputTerminal value and propagating
MbOutputTerminal out = getOutputTerminal(terminalName);
out.propagate(assembly);
There are several features that you may want to add to a routing program, such
as dynamic error handling or creating multiple into terminals. Review the API
javadoc for more ideas on how to use the other jplugin.jar features.
373
9.4.3 Packaging and loading the input node

If you want to maintain a consistent development environment, copy the
SwitchNode.java file to your new <install_dir>\javasource\com\ibm\samples
directory. When you compile the source code, make sure that you specify the
specific java source name and not *.java, otherwise you will recompile
everything in this working directory. Also make sure that your classpath has been
set to point to the jplugin.jar, as illustrated inImplementing an input node on
page 355.
Following is a quick review of the commands:
1. cd <install_dir>\javasource\
2. javac com\ibm\samples\SwitchNode.java
3. jar cvf SwitchNode.jar com\ibm\samples\SwitchNode.class
4. mqsistop <broker_name> (also mqsistop ConfigMgr, if on the same machine)
5. delete <install_dir>\jplugin\SwitchNode.jar
6. copy SwitchNode.jar <install_dir>\jplugin\SwitchNode.jar
7. mqsistart <broker_name> (also mqsistart ConfigMgr, if on the same
machine)
9.4.4 A simple message flow to test the plug-in node

As we did with the input node, we are going to define a new custom primitive
using our JAR file as the source. Then we are going to expand our current
message flow (InputNodeMessageFlow) by creating new output terminals and
adding the SwitchNode. The message flow then should be able to retrieve the
message from a directory as before and route it to the appropriate queue based
on the value found in the action tag.
If you did not choose to complete the InputNodeMessageFlow, you can simply
create a new message flow using a standard MQInput node as input.
1. If your control center is not open, go to Start -> Programs -> IBM
WebSphere MQ Integrator 2.1 -> Control Center.
2. Expand the Message Flows folder until you see IBMPrimitives. Right-click
IBMPrimitives and select Create Plugin Node.
3. You can use whatever Node Label you choose. It is best to make this
something meaningful like SwitchNode. For the Node Identifier, you must use
the value that is returned by the getNodeName function found in our program.
For this example, we used ComIbmSwitchNode, but remember, you may have to
leave off the trailing Node so that your actual input is ComIbmSwitch.
374
4. You need an input terminal; use in.

5. You need several output terminals: add, change, delete, hold, and failure.
Figure 9-15 Creating the Plug-in Node
6. Click Next. There are no attributes that we need to define for this example.
7. Click Next. Add a description here.
8. Click Next; right-click the InputNodeTestFlow and click Check Out.
9. Right-click the Failure node and click Delete.
10.Right-click the Out node and click Delete.
11. Drag and drop a new SwitchNode from the IBMPrimitives to the place where
the Out node was.
12. Right-click SwitchNode1 and rename it to SwitchNode since it is the only one
that we are going to use for this flow.
13. Drag and drop five MQOutput nodes from the IBMPrimitives to the far right of
your message flow.
375
14. Rename each of the new output nodes to Add, Change, Delete, Hold, and
Failure.
15. Right-click the Add output terminal and click Properties.
16. Click the Basic tab and change the name of the Queue to ADD_Q.
Figure 9-16 Defining the Add queue Basic tab
17.Click the Advanced tab and change the Message Context to Default. If you
do not want to change the description, click OK.
Figure 9-17 Defining the Add queue Advanced tab
18.For each of the terminals, name the queues CHANGE_Q, DELETE_Q, HOLD_Q and
FAILURE_Q, respectively. Make sure that you remember to change the
Message Context to Default for each.
19.Right-click the MakeMQMD node and select Connect -> Out, then join the
connection to the SwitchNode.
20.Right-click the SwitchNode and select Connect -> Add, then join the
connection to the Add terminal node.
21. Complete the last task for each of the output terminals.
376
22. When finished, your flow should look like this:
Figure 9-18 InputNodeTestFlow with the SwitchNode added
23.Click File -> Check In -> All (Saved to Shared).

24. Go to Start -> IBM MQSeries V5.2.1 -> MQSeries Explorer.
25. For the queue manager that is deploying your test message, create the
following queues: ADD_Q, CHANGE_Q, DELETE_Q, HOLD_Q, FAILURE_Q
and accept all of the default values for this test.
Figure 9-19 Queues required for SwitchNode test
26. Return to the Control Center and redeploy your broker from the Assignments
tab by right-clicking the broker with the existing message flow and clicking
Deploy -> Complete Assignments Configuration.
27. Switch to the Log tab and refresh the screen to ensure that the message flow
deployed successfully.
377
28. To test the message flow, simply copy and paste a version of the file
TestMessage.xml that you created for the input node test into the
c:\temp\XML directory. It should immediately be removed by the InputNode. If
your <action> tags contained the value change, then you should see your
complete message appear in the CHANGE_Q.
9.5 Summary
By now you should have a fairly good understanding of what it takes to create
and deploy a custom built Java node with WebSphere MQ Integrator. At this
point, you should probably review the programming guide and the API javadoc
once more to make sure the points we made here are perfectly clear to you. Also
be sure to take a look at the Web materials for any last minute updates to these
code examples or additional information.
There are several other custom features and classes that have been built into the
jplugin API and that you can take advantage of. Likewise, there is a limitless
number of possibilities stemming from the functionality within Java itself, so you
may want to consider implementing a custom Java node. All the reasons that
make Java a good programming language (platform independence, ease of use
and a robust toolset) also explain why you may choose to exploit this functionality
for your own purposes.
378
10
Chapter 10.
Using the aggregation

nodes
In this chapter, we briefly examine the new aggregation nodes by developing a
message flow to use them. Aggregation nodes are introduced in WebSphere MQ
Integrator V2.1, although a similar function was previously available in a
SupportPac.
379
10.1 Developing a message flow using aggregation

The purpose of aggregation is to allow for several different messages to be
generated from a message flow and then for the responses to these messages to
be brought back together in the same or in a different message flow.
This feature is often required by front-end applications that need to gather data
from several back-end applications and then consolidate that information into a
single response for a user or customer. Using aggregation nodes, this message
consolidation (or aggregation ) can be performed in the broker.
The advantage of using a broker to do this is that the requesting (or client)
application need only send a single message to the broker, and receive a single
message back. Any number of intermediate messages can be generated and
consolidated by the broker. Therefore, back-end applications can be added,
removed or changed without affecting the client application.
10.2 Components of the example system

In our example, we start with a simple XML message, which is assumed to have
been generated by a client application. We use the RFHUTIL utility (SupportPac
IH03) to place this message, from a flat file, onto our input queue.
Next, the FAN_OUT message flow reads the initial input message (as
MRM-defined XML) and then generates two request messages: one as
MRM-defined delimited data, and one as generic XML.
The two request messages are processed by flows PROC_A and PROC_B,
which simulate back-end applications. They extract information from a database
to populate the message fields and then send the messages to a reply queue.
Finally, the FAN_IN message flow receives the response messages, aggregates
them and constructs a final reply using information from both messages. This
message is placed into the output queue and we can examine it using RFHUTIL.
The actual message and database fields are used here only for the purposes of
our example and so we re-use the message sets developed in Chapter 6, New
MRM features explored on page 163 and Chapter 7, Exploring the new XML
features on page 205, along with the sample database that comes with the DB2
software. The message sets and flows used here are all downloadable from the
Web. See Appendix D, Additional material on page 445 for instructions.
380
10.3 The role of the aggregation nodes

Three nodes are provided to make this feature operate: AggregateControl,
AggregateReply and AggregateRequest.
10.3.1 The AggregateControl node

This node is placed in the FAN_OUT message flow to begin an aggregation
event (also known as the fan-out). It has an input and output terminal which
passes the original message through. It also has a control terminal which outputs
a separate control message. Initially, this control message will not have any
message headers. The AggregateControl node is represented in a message flow
by the icon shown in Figure 10-1.
Figure 10-1 AggregateControl node
The control message must be passed through to the AggregateReply node,

either directly (if in the same flow) or by using a message queue. The out
terminal is wired up multiple times, once for each request message that is to be
generated. In our example, we have two connections, but there could be more.
You could also split the flow at a later point, as long as the AggregateControl
node has been previously processed. The AggregateControl node adds
information to the LocalEnvironment tree and this information must be preserved
(this is particularly important with Compute nodes) until the AggregateRequest
node can save it later on in the flow.
This node has two important properties:
Aggregate Name, which specifies a name used to associate the FAN_OUT
message flow with the FAN_IN message flow. We use TESTAGG for our
example; the name is not important, but must be unique in your broker.
Timeout, which specifies the amount of time that replies are waited for at the
FAN_IN. After this time, a message will be generated on the timeout terminal
of the AggregateReply Node. If 0 is coded, then replies are waited for
indefinitely (this is probably not a good idea in production).
Chapter 10. Using the aggregation nodes
381
10.3.2 AggregateRequest node

This node is placed in the FAN_OUT message flow after the request messages
have been sent using an MQOutput node. It records that the request has been
sent and gathers information for the AggregateReply node to use. This state
information is stored in the broker database. It has one in and one out terminal.
The AggregateRequest node is represented in a message flow by the icon
Figure 10-2 AggregateRequest node
It has one property:

Folder Name, which specifies the name for the folder in the AggregateReply
node's compound message that will contain the reply message(s) from this
request.
The folder name becomes part of the compound (or aggregated) message tree
built by the AggregateReply node from the reply messages. You can specify any
value for the folder name and it does not have to be unique. Bear in mind that a
long name will make your ESQL statements harder to code.
However, if you use the same folder name for more than one request message in
a single aggregation, then the replies become an array in the compound
message under the folder name and need to be accessed with an array
subscript.
The AggregateRequest node does not itself generate the request message. You
generate the actual request message with a MQOutput (or MQeOutput) node
before using this node.
As well as using the LocalEnvironment information placed in the message by the
AggregateControl node, the AggregateRequest node uses information in the
WrittenDestinationList that is placed there by the output node. You must therefore
preserve this information if you manipulate the message tree in a Compute node.
382
The Advanced tab of a Compute nodes properties specifies which of the

message, local environment and exception lists are generated by that Compute
node. If you are not generating one of these, it is passed on unchanged. But if
you decide to modify the LocalEnvironment information in a Compute node, be
sure to copy the input AggregationControl information with a statement like this:
SET OutputLocalEnvironment.ComIbmAggregateControlNode =
InputLocalEnvironment.ComIbmAggregateControlNode;
10.3.3 AggregateReply node

This node is the most complex of the three; it is also the only aggregation node
required in the FAN_IN flow. It marks the end of the FAN_IN process. It receives
the control message (at the control terminal) and the reply messages (at the in
terminal). You can use this node in the same message flow as the FAN_OUT
logic, but here we use the example of a separate FAN_IN flow for clarity. The
AggregateReply node is represented in a message flow by the icon shown in
Figure 10-3.
Figure 10-3 AggregateReply node
This node waits for all the replies to arrive (or for the time-out interval to expire)
and then generates a compound (or aggregated) message built from all the
replies on the out terminal. The compound message includes the top level tree
name of ComIbmAggregateReplyBody, then the folder names and then the
messages, including everything below the Root of each message such as the
MQMD.
This node reads the broker database to retrieve information stored there by the
AggregateRequest nodes. In the event of a time-out (that is, if one or more
messages fail to arrive in the specified interval), the incomplete compound
message is sent to the timeout terminal.
You can use different time-out values for different requests by configuring more
than one AggregateControl node (but with the same aggregate name) in the
FAN_OUT flow. If messages arrive that cannot be identified as part of this
aggregation, they are sent to the unknown terminal. The other terminals are the
failure and catch terminals. Exceptions can be caught at either the MQInput node
383
or the AggregateReply node; see the manual WebSphere MQ Integrator Using

the Control Center, GC34-5602, for a table showing when each catch point is
used, and be careful to connect both of the catch terminals to any downstream
exception flow that you might use.
The node properties are:
Aggregate Name: the name used to associate the fan-in and fan-out and
also the name set in the fan-out AggregateControl node properties.
Unknown Message Timeout: specifies the amount of time for which
messages that cannot be identified as valid replies are held before being
propagated to the unknown terminal.
Transaction Mode: defines whether or not messages propagated by this
node are put transactionally.
10.4 The FAN_OUT flow

The FAN_OUT flow is constructed like any other WebSphere MQ Integrator
message flow; it is assumed that the reader has the skills to build simple
message flows using the Control Center. Only the essential parts of the flow and
properties will be illustrated here. The complete flow and message set are
supplied as Web materials and it is suggested that they are imported and
examined.
The input message is a simple XML message as follows:
Example 10-1 Test XML message
<people>
<person location="Unknown"age="35">
<name>
<first>JAMES</first>
<last>WALKER</last>
</name>
<email>james@nowhere.com</email>
</person>
</people>
The above message can be cut and pasted into Notepad to create a test file to
read with RFHUTIL, but remember to remove all blanks outside of XML tags and
remove any carriage returns before saving it. Failure to do so will result in the
MRM not parsing the message. A correct example is supplied as file
Atesting.xml.
384
If you have read Chapter 7, Exploring the new XML features on page 205, you
will recognize this message, as we defined it to the MRM in the message set
named CONTACTS.
Note that the contents of this XML message are relevant, because we will be
accessing the DB2 sample database using the name shown above. Make sure
that the message data for the name is correct and in upper-case format.
At this time, you should ensure that you have installed the SAMPLE database
that is supplied with DB2, and registered it as an ODBC data source of the same
name. You should also find out the schema (or owner) name for this database
(usually the user ID that created it). In our case it is ZPAT.
We use the EMPLOYEE table from the SAMPLE database; if you run the DB2
Control Center, the database should be displayed as shown. If you do not want to
install this database, you can amend the ESQL statements in the processing
flows to use some hard-coded values, and remove the database SELECT
statements, since this database access is not required to demonstrate message
aggregation.
Figure 10-4 DB2 SAMPLE database
385
Figure 10-5 Sampling the contents of table EMPLOYEE
The MQInput node

The FAN_OUT flow starts with an MQInput node that has the Defaults tab
properties set to the appropriate message set, type and format.
.
Figure 10-6 FAN_OUT MQInput node defaults
386
These defaults are needed if the input message does not have an MQRFH2
header specifying them. You could choose to specify the MQRFH2 header
information when using the RFHUTIL program to put the message in the queue.
The input queue is named WMQI.IN in this example.
Figure 10-7 FAN_IN MQInput node queue name
In the FAN_OUT flow, the failure node of the MQInput node is wired to an
MQOutput node which has a queue name of WMQI.FAIL. The message flows
also have Trace nodes connected between most of the important nodes; these
have been left in so that you can run a trace if you want to.
See Section 7.2.4, Problem solving with this flow on page 223 for details on
running user traces. We will show some extracts from the trace files later on.
The AggregateControl node and control message

Add an AggregateControl node to the flow and connect the MQInput out terminal
to the in terminal of the AggregateControl node. Set the Aggregation Name in the
properties to TESTAGG. For the moment, leave the value of Timeout as 0 (no
time-out).
Figure 10-8 AggregateControl node properties
387
The out terminal propagates the input message and is wired up to the flow logic
used to create request messages; in our case, it is wired up twice. The logic of
the request generating parts of the flow will be described shortly. If the order of
execution of these flow paths is important, you can use a FlowOrder node to
control it.
This is the actual fan-out logic, where the execution path divides into as many
parts as needed to generate the number of request messages required. We have
two parts, but you could have more than two, or you could have a loop in the
message flow generating messages (using a Filter node to control the loop
iteration), or send multiple messages from ESQL using the PROPAGATE
statement.
Each request message needs to pass through an MQOutput node, followed by a
AggregateRequest node to be included in the reply aggregation. You can also
generate a message that did not form part of the aggregation, or decide not to
generate a message for a particular branch of the fan-out logic.
The control terminal generates the aggregation control message; this needs to
be sent to a queue that can be read by the FAN_IN flow. However, the message,
as generated by the AggregateControl node, does not have an MQMD, so if
MQSeries is used to transport the message, we need to add one of these.
For this reason, a Compute node is wired between the control terminal and an
MQOutput node rather than connecting the two directly. This Compute node
simply adds an MQMD. This is done by setting a single field in the MQMD
(ensure that this header is created before the message body). The other default
values will be used when the message is generated.
388
Figure 10-9 Adding the MQMD and copying the XML
The above two lines of ESQL are all that is needed to generate an MQMD and
copy the control message XML to the output message. The output of the
Compute node is then wired to an MQOutput node and the queue name property
is set to WMQI.CONTROL (other values can be left to default). This will place the
control message into the named queue.
The generic XML request path

The out terminal of the AggregateControl node is wired to a path of nodes which
will generate our first request message. These are a Compute node, an
MQOutput node and an AggregateRequest node.
The Compute node builds a generic XML message to pass to the PROC_A flow.
This message is simply an example; you can construct whatever type of
message that your back-end application requires.
The Compute node does not modify the LocalEnvironment tree (and so does not
need to copy the aggregation control data in the ESQL). The compute mode field
(an advanced property) is simply set to message as only a new message (and not
a new LocalEnvironment) is generated. The complete ESQL follows.
389
Example 10-2 Generic XML, Compute node

Set OutputRoot.MQMD.Version = 2;
Set OutputRoot.MQMD.Format = 'MQSTR';
SET "OutputRoot"."XML"."staff"."given"
= "InputBody"."person"."name"."first";
SET "OutputRoot"."XML"."staff"."surname" = "InputBody"."person"."name"."last";
The output terminal of the Compute node is wired to an MQOutput node which
places the message in the WQMI.REQUEST_A queue.
Figure 10-10 MQOutput Request_A node
In this node, set a reply queue name of WMQI.REPLY (and use your queue
manager name in place of ZPAT for the reply-to queue manager).
Figure 10-11 MQOutput Request_A node
390
The Compute node is connected (although it need not be immediately

connected) to an AggregateRequest node, which records the request for
aggregation. This node must receive the WrittenDestinationList and the
LocalEnvironment control data intact from the earlier MQOutput and
AggregateControl nodes.
We set a folder name in the AggregateRequest Node properties to be used when
constructing the compound message from the replies sent with this folder name
(there can be more than one for the same folder). Typically, you would use a
different folder name for each request to allow you to clearly identify the
appropriate part of the compound reply message.
Figure 10-12 Setting the folder name
In this case, we call the folder ALPHA. This terminates our first request flow,
although you do not have to make this the last node.
The MRM delimited request path

This section of the flow is similar to the first request path. The Compute node
uses the following ESQL to transform the request format into a delimited format
using the message set DLM_TEST that we created in Section 6.1, Converting a
delimited message to XML on page 164. In this case, we use the message set
to generate the request message as a delimited format MRM-defined message.
You should add the output message layout from the message set to the Compute
node output messages section to allow the use of drag and drop for constructing
the XML. It is also possible to do the same with the MQMD fields. Select Use as
message body to generate the first two lines of the ESQL shown; the rest is
generated manually.
Again, the advanced property of the Compute mode is set to Message. Since we
do not change the LocalEnvironment information, it is automatically passed
through unchanged.
391
Figure 10-13 The Compute node properties

Example 10-3 ESQL to transform into delimited message
SET OutputRoot.Properties.MessageSet = 'DNUMQ4G07I001';
SET OutputRoot.Properties.MessageType = 'TEST';
Set OutputRoot.Properties.MessageFormat = 'TDS1';
Set OutputRoot.MQMD.Format = 'MQHRF2';
SET OutputRoot.MQRFH2.(MQRFH2.Field)Version = 2;
SET OutputRoot.MQRFH2.(MQRFH2.Field)Format = InputRoot.MQMD.Format;
SET OutputRoot.MQRFH2.mcd.Msd = OutputRoot.Properties.MessageDomain;
SET OutputRoot.MQRFH2.mcd.Set = OutputRoot.Properties.MessageSet;
SET OutputRoot.MQRFH2.mcd.Type = OutputRoot.Properties.MessageType;
SET OutputRoot.MQRFH2.mcd.Fmt = OutputRoot.Properties.MessageFormat;
Set "OutputRoot"."MRM"."FIRST_NAME" = "InputBody"."person"."name"."first";
Set "OutputRoot"."MRM"."LAST_NAME" = "InputBody"."person"."name"."last";
392
Again, this is an arbitrary example and is not required for aggregation, but it
serves to demonstrate the aggregation of a generic XML reply message with an
MRM-defined one. You can aggregate messages from different domains or from
the same domains, since the complete message tree of the reply messages are
added to the message tree under ComIBMAggregateReplyBody.
The syntax warning about the reserved word Set can be ignored or the offending
word placed in double quotes. Notice that the message sections are created in
order.
Note: An MQRFH2 header has been added to the message. This is because
in the FAN_IN flow we receive all the messages on a single MQInput node
and therefore need to ensure that they are correctly parsed. We do this by
coding the message domain, set, type and format in the MQRFH2 header for
this request and defaulting to generic XML for the other one.
Use your message set identifier in the ESQL if it is different from the example.
The output from the Compute node is wired to an MQOutput node just as in the
previous request path. This time, the output queue name is set to
WMQI.REQUEST_B. The reply-to queue remains set to WMQI.REPLY.
The output from the MQOutput node is again finally wired to a AggregateRequest
node, but this time the property folder name is set to BRAVO.
This completes the FAN_OUT flow; the messages are summarized in Table 10-1.
Table 10-1 The messages
Function
Queue name
Reply-to queue
Input (in)
WMQI.IN
Control (out)
WMQI.CONTROL
Request A (out)
WMQI.REQUEST_A
WMQI.REPLY
Request B (out)
WMQI.REQUEST_B
WMQI.REPLY
The control message is automatically produced by the AggregateControl node in

a generic XML format with attributes such as the ones shown in Example 10-4.
Example 10-4 Control message
<ComIbmAggregateControlNode brokerUUID="5b6a7693ea0000000080c249b15d63a9"
aggregateName="TESTAGG" replyGroupId="84264abf87ae410f87ff1ed772bbfa95"
timeout="0"/>
393
The request messages are in whatever format you used to create them; in our
example, the generic XML request message (Request A) is as shown below:
Example 10-5 Request A
<staff>
<given>JAMES</given>
<surname>WALKER</surname>
</staff>
Our example delimited message (Request B) looks like this:

Example 10-6 Request B
JAMES,WALKER
Check in, deploy and test the FAN_OUT flow by placing the original test XML
message onto WMQI.IN and you should see these three messages appear in the
appropriate queues (do not forget to create the queues as local queues in
MQSeries Explorer). Test the FAN_OUT flow in isolation until it is successful.
Remember to deploy the DLM_TEST and CONTACTS message sets as well.
If you experience problems, you can import the working FAN_OUT flow available
as a Web material or run traces until you have debugged your flow. You might
also use the Control Center debugger to help track down the problem.
Figure 10-14 shows the entire FAN_OUT flow along with Trace nodes (the
MQInput node also has a failure queue wired up to it).
Figure 10-14 The FAN_OUT flow
394
10.5 The processing flows

These flows simulate back-end applications that receive the request messages,
access a database and send reply messages with the requested information.
10.5.1 PROC_A flow

The first flow is called PROC_A and handles the generic XML requests. It has an
MQInput node with the queue name set to WMQI.REQUEST_A.
.
Figure 10-15 Generic XML MQInput
The default message domain is set to XML and the other default fields are left
blank. In all these examples, the MQInput nodes transaction mode is set to the
default of Yes, but you may prefer to set it to No, or to wire up the failure terminal
to a failure queue to avoid message rollback and looping during initial testing.
A Compute node is next in the flow. We access the SAMPLE database (supplied
with DB2), so you need to add the database table to the inputs side in the
Compute node properties using a Data Source value of SAMPLE and a Table
Name value of EMPLOYEE.
395
Figure 10-16 Adding a database table to the Compute node
Select Copy entire message and then add the following line of ESQL at the
bottom.
Example 10-7 ESQL needed to get database record
Set "OutputRoot"."XML"."staff"."record" = THE
(SELECT T.* FROM Database.ZPAT.EMPLOYEE AS T WHERE T.LASTNAME =
"InputBody"."staff"."surname");
Note that the schema name here is ZPAT; this will be different for your database
and you should change it to the value for your schema. Use the DB2 Control
Center to find out the correct value for your installation of DB2.
This ESQL statement reads a single row from the database where the last name
matches the one from the input message. All columns are returned (because we
used T.* in the SELECT statement) and will be added to the message tree. This
has the effect of adding the entire employee record to the message. This is just
an example to illustrate the power of XML; you could select certain columns or
use fixed format messages if you so chose.
The Compute node is wired to an MQReply node. The use of MQReply is
important, since we want to ensure that the incoming MQSeries message ID is
moved to the correlation ID of the reply message. The reply-to queue name is
stored in the MQMD and so no parameters are needed for this node.
396
Figure 10-17 The PROC_A flow
This flow generates a message to the WMQI.REPLY queue, as follows:

Example 10-8 Reply XML message
<staff>
<given>JAMES</given>
<surname>WALKER</surname>
<record>
<EMPNO>000190</EMPNO>
<FIRSTNME>JAMES</FIRSTNME>
<MIDINIT>H</MIDINIT>
<LASTNAME>WALKER</LASTNAME>
<WORKDEPT>D11</WORKDEPT>
<PHONENO>2986</PHONENO>
<HIREDATE>1974-07-26</HIREDATE>
<JOB>DESIGNER</JOB>
<EDLEVEL>16</EDLEVEL>
<SEX>M</SEX>
<BIRTHDATE>1952-06-25</BIRTHDATE>
<SALARY>20450.00</SALARY>
<BONUS>400.00</BONUS>
<COMM>1636.00</COMM>
</record>
</staff>
10.5.2 PROC B flow

The second flow is called PROC_B and handles the MRM delimited requests. It
has an MQInput node with the queue name set to WMQI.REQUEST_B.
Because the message will have an RFH2 header defining its message domain,
set, type and format, the values in the MQInput node defaults are not important,
but it is easiest to set XML as the default domain and leave it that way.
397
However, to verify that the message is the one we expected, we connect a Check
node to the flow as the next node. This is configured as shown in Figure 10-18:
Figure 10-18 Check node properties
Remember to use your message set identifier, if it is different. If the message

headers match the values in the Check node, the message goes to the match
terminal; if not, it goes to the failure terminal. We connect an MQOuput node to
the failure terminal (set to use the queue WMQI.FAIL2) and a Compute node to
the match terminal.
The Compute node is similar to the one in PROC_A, except that it selects only
one single message field from the database table row (in this example, the same
database and table as before). The ESQL is as shown in Example 10-9.
Example 10-9 ESQL for database lookup
SET OutputRoot = InputRoot;
Set "OutputRoot"."MRM"."LOCATION" = THE
(SELECT ITEM T.WORKDEPT FROM Database.ZPAT.EMPLOYEE AS T WHERE T.LASTNAME =
"InputBody"."LAST_NAME");
Copy entire message is selected (which generates the first line) and then the
WORKDEPT column is extracted from the table and used to set the LOCATION
field in the MRM message tree. Remember to change ZPAT to the name of your
schema.
398
The database table has again been added to the inputs side; you can manually
add some column names such as EMPNO and WORKDEPT to the input display
if you want. The MRM message TEST has also been added to the display.
The output of this Compute node is an MRM message wired to an MQReply
node (again, this logic is important to ensure that the MSGID is moved to the
CORRELID). The reply-to-queue name is already in the message MQMD
header. Be sure to preserve the MQMD header in these processing flows by
copying the headers, or the entire message, in any Compute node.
399
Figure 10-20 The PROC_B flow
The output message from this flow looks like the one shown in Example 10-10.
Example 10-10 Delimited message output
JAMES,WALKER,,D11
If you look at this message with MQSeries Explorer, you should also see the
MQRFH2 header preceding the payload data in the message data when you
browse it.
Check in, deploy and test the PROC_A and PROC_B flows (one at a time is the
method suggested) along with the working FAN_OUT flow. Once all of these are
working properly (use RFHUTIL to examine the various messages content in
detail), you should clear all the test queues of messages before testing the
FAN_IN flow.
Tip: You can remove unwanted messages from a queue (for example the
control messages) during testing by using the RFHUTIL program to read
them. This program will also display the message contents in different ways,
such as parsed XML. To put messages to a queue, use RFHUTIL to read the
message data from a file first, and then to put it into the queue.
We have now produced the control message on the WMQI.CONTROL queue,

and two reply messages on the WMQI.REPLY queue. The aggregation state
data should have been recorded by the broker in its database. Everything is now
ready for the FAN_IN flow to complete the message aggregation.
These process flows are arbitrary examples and are not specific to aggregation,
other than the MQReply logic, which can be performed by any MQSeries
application.
400
10.6 The FAN_IN flow

This flow has two MQInput nodes; the first of these is configured to read the
WMQI.CONTROL queue, with a default message domain of XML. It is then wired
to the AggregationReply node (to the control terminal). This receives the control
message from the FAN_OUT flow and passes it to the AggregateReply node.
The second MQInput node is set to read the WMQI.REPLY queue, and again the
default message domain is set to XML. This default correctly handles the generic
XML message from PROC_A which does not have a RFH2 header. When the
MRM-defined message from PROC_B arrives, the RFH2 header in the message
will inform the MRM of which message domain, set, type and format to use.
Both reply messages are received by this MQInput node and the order of receipt
is not important. Both are passed on to the in terminal of the AggregateReply
node. You can, of course, build an aggregation with more than two messages, or
even just one, if the logic does not always need two requests.
The AggregationReply node has a property value of TESTAGG for the Aggregation
Name field (which should match the value used in the FAN_OUT flow) and a
time-out for unknown messages (this is not the time-out for the expected
messages).
Figure 10-21 AggregateReply node properties
When the number of messages expected (determined from the broker database
state information) is received, the AggregationReply node generates the
compound output message. If messages that are not part of this aggregation are
received, they are passed to the unknown terminal. If the expected messages fail
to arrive within the time-out interval, then the incomplete compound message is
passed to the timeout terminal. A time-out value of 0 indicates indefinite time.
Failure and catch terminals exist and can be wired up as required. We should
now have a compound message being produced which can be processed in the
remainder of this flow to generate a response to the original request.
401
To construct a final reply, a Compute node is used which has access to the
compound message. Unfortunately, because the compound message is not in
the MRM, you cannot directly drag and drop message fields. However, you can
still drag the MRM field names and then insert the extra levels.
In this example, the compound message has two folders, one for each message,
so the PROC_B message fields have the following prefix (or stem):
InputRoot.ComIbmAggregateReplyBody."BRAVO"
BRAVO is the folder name associated with this request by the AggregateRequest
node in FAN_OUT. The remainder of the structure is the MRM message, so the
fully qualified field name for LAST_NAME is:
InputRoot.ComIbmAggregateReplyBody."BRAVO"."MRM"."LAST_NAME";
Similarly, the PROC_A generic XML fields are available as follows:
InputRoot.ComIbmAggregateReplyBody."ALPHA"."XML"."staff"."record"."EMPN
O";
You can access any combination of the two (or more) message structures in the
Compute node to build a new output message. There will be as many folders as
there are different folder names from the aggregation requests for TESTAGG.
If more than one request message has used the same folder name in a single
aggregation instance, then each message for the same folder becomes an array
element within the folder (which is not the case in our example).
You could have several different message domain types in a compound reply, or
a number of XML messages, or a number of MRM messages, etc. If you
compound several XML messages, then the results are not merged into a single
XML tree, unless you choose to do so using appropriate Compute node logic.
Example 10-11 ESQL to produce a final response message
Set OutputRoot.MQMD.Format = 'MQSTR';
Set OutputRoot.XML."REP"."name" =
InputRoot.ComIbmAggregateReplyBody."BRAVO"."MRM"."LAST_NAME";
Set OutputRoot.XML."REP"."loc" =
InputRoot.ComIbmAggregateReplyBody."BRAVO"."MRM"."LOCATION";
Set OutputRoot.XML."REP"."emp" =
InputRoot.ComIbmAggregateReplyBody."ALPHA"."XML"."staff"."record"."EMPNO";
Set OutputRoot.XML."REP"."tel" =
InputRoot.ComIbmAggregateReplyBody."ALPHA"."XML"."staff"."record"."PHONENO";
402
The Compute node does not select Copy message headers (since there are
none produced by the aggregation reply node), nor does it use Copy all
messages. A new message header must be constructed for the new output
message, although you can copy fields from one of the included messages
header.
The properties, MQMD and other headers of each included message are
available under their folder name (for example using the element name
InputRoot.ComIbmAggregateReplyBody.BRAVO.MQMD.Format).
When building a new message, be sure to create at least one field in each
header section in the correct order (for example, create the MQMD before
creating the MQRFH2 before creating the XML), otherwise the output message
may not be generated correctly or not at all by the parser during MQOutput.
The output of the Compute node is connected to an MQOutput node which uses
a queue name of WMQI.OUT. The final response message looks like this:
Example 10-12 Final response message
<REP>
<name>WALKER</name>
<loc>D11</loc>
<emp>000190</emp>
<tel>2986</tel>
</REP>
This example message shows how both process flows have extracted different
data (although, in our test case, from the same database) and then how the two
reply messages have been aggregated and a final response built using data from
the different messages that was available in the compound message.
Figure 10-22 The FAN_IN flow
403
10.7 A trace showing the compound message tree

The data in Example 10-13 is produced from the AggregateReply node (when
successful); it is the input message to the Compute node following it. You cannot
directly output this aggregated compound message to a queue, since it does not
have a structure that is directly valid for any message domain parser.
Example 10-13 Aggregated message tree
2001-12-06 16:56:01.345000
UserTrace
BIP4060I: Data 'TRACE AFTER AGGREGATION
----------------------(
(0x1000000)Properties
= (
= NULL
= NULL
= NULL
(0x3000000)Encoding
= NULL
(0x3000000)CodedCharSetId = NULL
= UNKNOWN
= UNKNOWN
= NULL
(0x3000000)ExpirationTime = NULL
(0x3000000)Priority
= NULL
(0x3000000)ReplyIdentifier = NULL
= 'MQ'
(0x3000000)Topic
= NULL
)
(0x1000000)ComIbmAggregateReplyBody = (
(0x1000000)BRAVO = (
= 'DNUMQ4G07I001'
= 'TEST'
= 'TDS1'
(0x3000000)Encoding
= 546
= TRUE
= FALSE
= NULL
(0x3000000)ExpirationTime = -1
(0x3000000)Priority
= 0
(0x3000000)ReplyIdentifier =
X'414d51207a7061742020202020202020f46a0f3ca2400100'
= 'MQ'
(0x3000000)Topic
= NULL
)
(0x1000000)MQMD
= (
= 'WMQI.REPLY'
= TRUE
(0x3000000)Encoding
= 546
404
1880
= 437
(0x3000000)Format
= 'MQHRF2 '
(0x3000000)Version
= 2
(0x3000000)Report
= 0
(0x3000000)MsgType
= 2
(0x3000000)Expiry
= -1
(0x3000000)Feedback
= 0
(0x3000000)Priority
= 0
= 0
(0x3000000)MsgId
=
X'414d51207a7061742020202020202020f46a0f3c42f00000'
(0x3000000)CorrelId
=
X'414d51207a7061742020202020202020f46a0f3ca2400100'
= 0
(0x3000000)ReplyToQ
='
'
= 'zpat
'
= 'zpat
'
X'0000000000000000000000000000000000000000000000000000000000000000'
'
= 26
= 'zpat
'
(0x3000000)PutDate
= DATE '2001-12-06'
(0x3000000)PutTime
= GMTTIME
'21:56:01.120'
= '
'
(0x3000000)GroupId
=
X'000000000000000000000000000000000000000000000000'
= 1
(0x3000000)Offset
= 0
(0x3000000)MsgFlags
= 0
= -1
)
(0x1000000)MQRFH2
= (
(0x3000000)Version
= 2
(0x3000000)Format
= '
'
(0x3000000)Encoding
= 546
(0x3000000)Flags
= 0
(0x3000000)NameValueCCSID = 1208
(0x1000000)mcd
= (
(0x1000000)Msd = (
(0x2000000) = 'MRM'
)
(0x1000000)Set = (
405
(0x2000000) =
)
(0x1000000)Type
(0x2000000) =
)
(0x1000000)Fmt
(0x2000000) =
)
'DNUMQ4G07I001'
= (
'TEST'
= (
'TDS1'
)
)
(0x1000008)MRM
=
(0x3000001)FIRST_NAME
(0x3000001)LAST_NAME
(0x3000001)LOCATION
)
(
= 'JAMES'
= 'WALKER'
= 'D11'
)
(0x1000000)ALPHA = (
(0x3000000)Encoding
(0x3000000)ExpirationTime
(0x3000000)Priority
(0x3000000)ReplyIdentifier
X'414d51207a7061742020202020202020f46a0f3cb2400100'
(0x3000000)Topic
)
(0x1000000)MQMD
= (
(0x3000000)Encoding
(0x3000000)Format
(0x3000000)Version
(0x3000000)Report
(0x3000000)MsgType
(0x3000000)Expiry
(0x3000000)Feedback
(0x3000000)Priority
(0x3000000)MsgId
X'414d51207a7061742020202020202020f46a0f3c42e00000'
406
=
=
=
=
=
=
=
=
=
=
=
''
''
''
546
437
TRUE
FALSE
NULL
-1
0
= 'MQ'
= NULL
=
=
=
=
=
=
=
=
=
=
=
=
=
'WMQI.REPLY'
TRUE
546
437
'MQSTR
'
2
0
2
-1
0
0
0
(0x3000000)CorrelId
=
X'414d51207a7061742020202020202020f46a0f3cb2400100'
=
(0x3000000)ReplyToQ
='
'
= 'zpat
'
=
X'0000000000000000000000000000000000000000000000000000000000000000'
'
=
= 'zpat
'
(0x3000000)PutDate
=
(0x3000000)PutTime
=
'21:56:01.180'
=
(0x3000000)GroupId
=
X'000000000000000000000000000000000000000000000000'
=
(0x3000000)Offset
=
(0x3000000)MsgFlags
=
=
)
(0x1000010)XML
= (
(0x5000018)XML
= (
(0x6000011) = '1.0'
)
(0x1000000)staff = (
(0x1000000)given
= (
(0x2000000) = 'JAMES'
)
(0x1000000)surname = (
(0x2000000) = 'WALKER'
)
(0x1000000)record = (
(0x1000000)EMPNO
= (
(0x2000000) = '000190'
)
(0x1000000)FIRSTNME = (
(0x2000000) = 'JAMES'
)
(0x1000000)MIDINIT
= (
(0x2000000) = 'H'
)
(0x1000000)LASTNAME = (
(0x2000000) = 'WALKER'
'zpat
'
26
DATE '2001-12-06'
GMTTIME
'
'
1
0
0
-1
407
)
(0x1000000)WORKDEPT = (
(0x2000000) = 'D11'
)
(0x1000000)PHONENO
= (
(0x2000000) = '2986'
)
(0x1000000)HIREDATE = (
(0x2000000) = '1974-07-26'
)
(0x1000000)JOB
= (
(0x2000000) = 'DESIGNER'
)
(0x1000000)EDLEVEL
= (
(0x2000000) = '16'
)
(0x1000000)SEX
= (
(0x2000000) = 'M'
)
(0x1000000)BIRTHDATE = (
(0x2000000) = '1952-06-25'
)
(0x1000000)SALARY
= (
(0x2000000) = '20450.00'
)
(0x1000000)BONUS
= (
(0x2000000) = '400.00'
)
(0x1000000)COMM
= (
(0x2000000) = '1636.00'
)
)
)
)
)
)
)
Tip: Please refer to Chapter 6 of the IBM manual Using the Control Center,
SC34-5602, which also covers the use of aggregation nodes, and, in
particular, read the section dealing with exception handling. The online help in
the Control Center also explains the node properties and terminals in more
detail.
408
10.8 Best practices for aggregation

Some suggestions when using aggregation:
You must use a Compute node to prepare a new final output message (but
you could copy large parts of the compound message to the output message
with a few ESQL statements, especially when they are both in XML format).
Any MQSeries application, which replaces the PROC_A or PROC_B flows in
our example, must follow the convention of copying the MsgId to the Correlid
field in the reply message (which must also be sent to the reply-to-queue).
Otherwise, the replies cannot be associated with the corresponding requests.
You should set a time-out value in the AggregateControl node and code your
flow logic to deal with incomplete compound messages (time-outs).
You should set the unknown message time-out in the AggregateReply node;
this gives time for the control message to arrive, which reduces the risk of
getting an unknown message in the event that a reply message arrives before
the control message.
It is best to use a transactional unit of work in your FAN_OUT flow, so that
either all or none of the request messages and the control messages are
committed.
The FAN_OUT and FAN_IN flows must run on the same broker, since key
information is passed and persisted using the broker database. You should
ideally use persistent messages to avoid orphaning the state information in
the database if the reply or control messages are lost during a restart.
When suspending flows in a broker, stop the FAN_OUT flow before the
FAN_IN to allow time for the FAN_IN to service any outstanding requests.
Attention: The aggregate nodes (AggregateControl, AggregateRequest,

AggregateReply) use the broker database. If you are using DB2 as the broker
database, you may experience database deadlocks under stress conditions
when running with multiple threads. This will be identified by the WMQI event
log message 2322, with SQL State 40001. This is caused by a DB2 feature
called next key locking. If this problem occurs, then next key locking can be
disabled by typing db2set DB2_RR_TO_RS=YES in a DB2 command window and
restarting the DB2 database manager. Refer to the DB2 product
documentation for more information.
409
Web materials
Instructions for importing message sets and flows can be found in Section 6.7.1,
Importing the Web materials message sets and flows on page 203.
The following exported flows are supplied:
FAN_OUT.xml
PROC_A.xml
PROC_B.xml
FAN_IN.xml
The original input test message is supplied as file Atesting.xml. The message
sets are CONTACTS.mrp and DLM_TEST.mrp.
A formatted trace file for a complete fan-out and fan-in transaction using the
sample flows is supplied as a file named AGGREGATION.txt.
410
Appendix A.
Hardware/software
configuration
This appendix provides details about the hardware and software configuration of
the computers that were used to build the examples and to perform the migration
exercise.
411
A.1 Hardware/software specification for brokers

running on Windows 2000
Machine details
IBM PC 300PL
Pentium III processor running at 667MHz
512MB memory
20GB EIDE hard disk
Operating system
Windows 2000 Professional + ServicePac 2
Software details
DB2 Enterprise Edition V6.1 + Fixpak 7
MQSeries for Windows NT and Windows 2000 V5.2.1 with CSD U200151
MQSeries for Java MA88
MQSeries Integrator product level details

MQSeries Integrator V2.0.1 was installed with CSD U200146. To complete the
migration and coexistance scenarios, fix IC32427 was installed.
MQSeries Integrator V2.0.2 was installed with CSD U200147. To complete the
migration and coexistance scenarios, an additional CSD U200161 and fix
IC32427 were installed.
WebSphere MQ Integrator V2.1 was installed with CSD U200167.
Fixes and CSDs can be downloaded from:
ftp://ftp.software.ibm.com/software/mqseries/fixes/
412
A.2 Hardware/software specification for the AIX broker

machine
Machine details
IBM RS/6000s 44P Model 170
512 MB
2 Ultra SCSI Hard disks of 9GB
Operating system
AIX V4.3.3
Software details
DB2 Enterprise Edition V7.1
MQSeries for AIX V5.2 + CSD2 (U474779, U474840, U478788)
MQSeries for Java MA88
MQSeries Integrator product level details

MQSeries Integrator V2.0.2 was used. PTF U479417 was applied. To complete
the coexistence scenarios, fix IC32427 was installed as well.
WebSphere MQ Integrator V2.1 was installed at PTF level U481171.
Fixes and CSDs can be downloaded from:
ftp://ftp.software.ibm.com/software/mqseries/fixes/
A.3 Hardware/software specification for the Sun Solaris

broker machine
Machine details
Sun SPARC
1024 MB RAM
Operating system
Solaris 8
Appendix A. Hardware/software configuration
413
Software details
Oracle 8.1.6
MQSeries for Solaris V5.2 + CSD2 (U474789)
WebSphere MQ Integrator V2.1 + GA CSD (U481172).
414
Appendix B.
Source code for the Java

extensions to WebSphere
MQ Integrator
This appendix contains all of the source code for the Java examples used
throughout this redbook. Though they have been implemented and tested for
usability, you should not use them in your production environment without
conducting testing and quality assurance for yourself.
You can also find the source code on the Web site for this redbook. The
instructions for accessing the material can be found in Appendix D, Additional
material on page 445.
415
B.1 Java input node getting started example

B.1.1 SocketNode.java
Source code
import com.ibm.broker.plugin.*;
import java.io.*;
import java.net.*;
public class SocketNode extends MbInputNode implements MbInputNodeInterface {
String _portNumber = "";
String _filePath = "";
String _dataSource = "";
int FAILURE;
ServerSocket server = null;
public SocketNode () throws MbException {
// create terminals here
createOutputTerminal ("out");
createOutputTerminal ("failure");
}
public String getDataSource () {
return _dataSource;
}
public String getFilePath () {
return _filePath;
}
public static String getNodeName () {
return "ComIbmSampleInputNode";
}
public String getPortNumber () {
return _portNumber;
}
private void logMessage ( String methodName, String messageID, String traceText)
throws MbException{
MbService mbsLog = new MbService ();
if (messageID.endsWith ("W")) {
mbsLog.logWarning (this, methodName, "com.ibm.samples.SocketNodeMessages",
messageID, traceText,new Object [] {});
}
else{
if (messageID.endsWith ("I")) {
mbsLog.logInformation (this, methodName, "com.ibm.samples.SocketNodeMessages",
}
else {
mbsLog.logError (this, methodName, "com.ibm.samples.SocketNodeMessages",
}
}
416
}
public int run (MbMessageAssembly assembly) throws MbException {
byte [] generatedMessageBytes = null;
// select correct routine
if (_dataSource.equalsIgnoreCase ("port")) {
try {
generatedMessageBytes = usePortNumber ();
}
catch (InterruptedIOException e) {
System.out.println ("Timed out");
return TIMEOUT;
}
catch (SocketNodeException e) {
return FAILURE;
}
catch (Exception e) {
logMessage ("run", "4E", e.getMessage ());
e.printStackTrace ();
return FAILURE;
}
}
else {
if (_dataSource.equalsIgnoreCase ("file")) {
try {
generatedMessageBytes = useFilePath ();
}
return FAILURE;
}
return FAILURE;
}
}
else {
logMessage ("run", "0W", "");
System.out.println ("Invalid datasource specified.");
// use defaults and run port version.
_portNumber = "3000";
_dataSource = "port";
try {
generatedMessageBytes = usePortNumber ();
}
catch (InterruptedIOException e) {
System.out.println ("Timed out");
return TIMEOUT;
}
return FAILURE;
}
Appendix B. Source code for the Java extensions to WebSphere MQ Integrator
417

return FAILURE;
}
}
}
if (generatedMessageBytes == null){
return TIMEOUT;
}
else {
MbMessageAssembly outputAssembly = new MbMessageAssembly (assembly,createMessage
(generatedMessageBytes));
MbOutputTerminal out = getOutputTerminal ("out");
if(out != null) {
out.propagate (outputAssembly);
}
return SUCCESS_CONTINUE;
}
}
public void setDataSource (String dataSource) {
}
public void setFilePath (String filePath) {
_filePath = filePath;
}
public void setPortNumber (String portNumber) {
_portNumber = portNumber;
}
private byte[] useFilePath () throws Exception {
//check validity
System.out.println ("Seaching for Incoming File...");
File sourceDirectory = new File (_filePath);
if (sourceDirectory == null) {
logMessage ("useFilePath", "2E","Directory '" + _filePath + "'");
throw new SocketNodeException ();
}
if (sourceDirectory.isDirectory () == false) {
logMessage ("useFilePath", "5E", "Path '" + _filePath + "'");
System.out.println ("Source path is not a directory.");
}
// loop for 5 seconds or until a file is found
long startTime = System.currentTimeMillis ();
while ((System.currentTimeMillis () - startTime) < 5000) {
String [] inputFileList = sourceDirectory.list (new DirFilter ());
// only use first file
if (inputFileList.length >0) {
// open first file and rename to indicate use
File sourceFile = new File (_filePath + File.separator + inputFileList[0]);
if (sourceFile==null) {
logMessage ("useFilePath", "3E", "File '" + _filePath + File.separator +
inputFileList[0] + "'");
418
}
File newSourceFile = new File (_filePath + File.separator + inputFileList[0] +
".inuse");
if (sourceFile.renameTo (newSourceFile) == false) {
logMessage ("useFilePath", "0E", "Source '" + _filePath + File.separator +
inputFileList[0] + "' Dest '"+ _filePath + File.separator + inputFileList[0] +
".inuse");
}
System.out.println ("\rFile found. Reading message ...");
// copy file into byte array for propagation
InputStream in = new FileInputStream (newSourceFile);
ByteArrayOutputStream byteStream = new ByteArrayOutputStream ();
int len;
while ((len = in.read (inputBytes)) > 0) {
//append to input;
byteStream.write (inputBytes,0,len);
}
in.close ();
newSourceFile.delete ();
System.out.println ("\rFile closed. Message created.
\n");
return byteStream.toByteArray ();
}
}
System.out.println ("none found.\n");
return null;
}
private byte[] usePortNumber () throws Exception {
System.out.println ("Waiting for Incoming Data...");
// open server port if not already open
if (server == null) {
try {
server = new ServerSocket (Integer.parseInt (_portNumber,10));
}
catch (Throwable t){
logMessage ("usePortNumber", "1E", "Port '" + _portNumber + "'\r\nError:\r\n" +
t.getMessage ());
}
}
server.setSoTimeout (10000);
Socket sock = server.accept ();
System.out.println ("\rConnection established. Reading message ...");
InputStream in = sock.getInputStream ();
ByteArrayOutputStream byteStream = new ByteArrayOutputStream ();
int len;
while ((len = in.read (inputBytes)) > 0) {
//append to input;
419
byteStream.write (inputBytes,0,len);
}
in.close ();
System.out.println ("\rConnection closed. Message created.
return byteStream.toByteArray ();
\n");
}
}
//EOF
B.1.2 SocketNodeException.java
Source code
public class SocketNodeException extends Exception {
public SocketNodeException () {
super();
}
public SocketNodeException (String s) {
super(s);
}
}
B.1.3 SocketNodeMessages.java
Source code
import java.util.*;
public class SocketNodeMessages extends ListResourceBundle {
/**
* <p>static multi-dimensional array used as a catalog structure to store
* messages containing a varying number of inserts, accessed via a msg
* key</p>
*/
private static final Object[][] contents = {
{"0E", "\r\nUnable to rename file.\r\n"},
{"1E", "\r\nUnable to open port."},
{"2E", "\r\nThe directory path specified is invalid.\r\nAborting read."},
{"3E", "\r\nUnable to read from file.\r\n"},
{"4E", "\r\nA general critial error occurred.\r\nThe stack trace is as
follows:\r\n"},
{"5E", "\r\nThe path specified is not a directory.\r\n"},
{"0W", "\r\nThe data source specified is invalid.\r\nDefaulting to Socket mode, Port
3000.\r\n"},
420
{"0I", "\r\n-Debug Checkpoint Data- \r\n"},

};
public java.lang.Object[][] getContents () {
return contents;
}
}
B.1.4 DirFilter.java
Source code
public class DirFilter implements java.io.FilenameFilter {
public DirFilter () {
super();
}
public boolean accept (java.io.File dir, String name) {
// accept if filename ends in .xml
if (name.endsWith (".xml") == true) {
return true;
} else {
return false;
}
}
}
B.1.5 Compilation and packaging instructions

1. From a command window, add to your classpath:
set classpath=%path%;<install_dir>\classes\jplugin.jar
(where <install_dir> is the drive and the directory where the WebSphere
MQ Integrator installation is located)
if the setting is not already in your classpath.
2. Write programs shown above in a text editor or copy them from the Web site.
3. Save programs to <install dir>\javasource\com\ibm\samples\. Ensure that you
save the files with a .java extension and that a .txt or other extension is not
attached.
4. From a command prompt, type cd <install dir>\javasource\
5. Run the command javac com\ibm\samples\*.java
6. Create the JAR using jar cvf SocketNode.jar com\ibm\samples\*.class
7. Stop the broker with mqsistop <broker_name>
8. If the configuration manager is running on the same machine, issue the
command mqsistop ConfigMgr
421
9. Delete old versions using delete <install_dir>\jplugin\SocketNode.jar

10. Copy the file using
copy SocketNode.jar <install_dir>\jplugin\SocketNode.jar
11. Restart your broker and configuration manager services using

mqsistart <broker>
mqsistart ConfigMgr
B.2 Java plug-in node getting started example

B.2.1 SwitchNode.java
Source code
/*
* Licensed Materials - Property of IBM
* 5648-C63
* (C) Copyright IBM Corp. 1999, 2001
*/
/**
* Sample plugin node.
* This node propagates the incoming message to one of several output terminals
* depending on the content of the message.
* A minimal test message for this node would be:
* <data><action>change</action></data>
*/
public class SwitchNode extends MbNode implements MbNodeInterface {
String _nodeTraceSetting;
/**
* Switch node constructor.
* This is where input and output terminal are created.
*/
public SwitchNode () throws MbException {
createInputTerminal ("in");
createOutputTerminal ("add");
createOutputTerminal ("change");
createOutputTerminal ("delete");
createOutputTerminal ("hold");
}
/**
422
* This static method is called by the framework to identify this node.

* If this method is not supplied, a default name will be generated
* automatically based on the node's package/class name. In this case
* it would be 'ComIbmSamplesSwitchNode'.
*/
return "ComIbmSwitchNode";
}
/**
* This evaluate message is called by the broker for each message passing
* through the flow. The message assembly is passed in with the 'assembly'
* parameter. It is possible for a node to have more than one input
* terminal. The terminal that the message has come in on is represented
* by the 'in' parameter.
*/
public void evaluate (MbMessageAssembly assembly, MbInputTerminal in)
throws MbException {
// Navigate to the relevant syntax element in the XML message
MbElement rootElement = assembly.getMessage ().getRootElement ();
MbElement switchElement = rootElement.getLastChild ().getFirstChild ().getFirstChild
();
// To aid debugging, text can be printed to stdout/stderr.
// On NT this can be viewed by selecting 'Allow sevice to interact with
// desktop' on the NT Services properties dialog.
// On Unix set the environment variable MQSI_RUN_ATTACHED=1 before
// starting the broker.
if(_nodeTraceSetting.equals ("debug")) {
System.out.println ("Element = " + switchElement.getName ());
System.out.println ("Value = " + switchElement.getValue ());
}
// Select the terminal indicated by the value of this element
String terminalName;
String elementValue = (String)switchElement.getValue ();
if(elementValue.equals ("add"))
terminalName = "add";
else if(elementValue.equals ("change"))
terminalName = "change";
else if(elementValue.equals ("delete"))
terminalName = "delete";
else if(elementValue.equals ("hold"))
terminalName = "hold";
else
terminalName = "failure";
MbOutputTerminal out = getOutputTerminal (terminalName);
//
//
//
//
//
Now propagate the message assembly.

If the terminal is not attached, an exception will be thrown. The user
can choose to handle this exception, but it is not neccessary since
the framework will catch it and propagate the message to the failure
terminal, or if it not attached, rethrow the exception back upstream.
423
out.propagate (assembly);
}
/* Attributes are defined for a node by supplying get/set methods.
* The following two methods define an attribute 'nodeTraceSetting'.
* The capitalisation follows the usual JavaBean property convention.
*/
public String getNodeTraceSetting () {
return _nodeTraceSetting;
}
public void setNodeTraceSetting (String nodeTraceSetting) {
_nodeTraceSetting = nodeTraceSetting;
}
}
B.2.2 TransformNode
Source code
/*
* Licensed Materials - Property of IBM
* 5648-C63
* (C) Copyright IBM Corp. 1999, 2001
*/
/**
* Sample plugin node.
* This node alters the content of the incoming message before passing it to
* its output terminal.
* A minimal test message for this node would be:
* <data><action>add</action></data>
*/
public class TransformNode extends MbNode implements MbNodeInterface {
String _nodeTraceSetting;
/**
* Transform node constructor.
* This is where input and output terminal are created.
*/
public TransformNode () throws MbException {
createInputTerminal ("in");
createOutputTerminal ("out");
}
/**
* This static method is called by the framework to identify this node.
424
* If this method is not supplied, a default name will be generated

* automatically based on the node's package/class name. In this case
* it would be 'ComIbmSamplesTranformNode'.
*/
return "ComIbmTransformNode";
}
/**
* This evaluate message is called by the broker for each message passing
* through the flow. The message assembly is passed in with the 'assembly'
* parameter. It is possible for a node to have more than one input
* terminal. The terminal that the message has come in on is represented
* by the 'in' parameter.
*/
public void evaluate (MbMessageAssembly assembly, MbInputTerminal in)
throws MbException {
// The incoming message assembly and its embedded messages are read-only.
// New objects must be created using the copy constructors
MbMessage newMsg = new MbMessage (assembly.getMessage ());
MbMessageAssembly newAssembly = new MbMessageAssembly (assembly, newMsg);
// Navigate to the relevant syntax element in the XML message
MbElement rootElement = newAssembly.getMessage ().getRootElement ();
MbElement switchElement = rootElement.getFirstElementByPath ("/XML/data/action");
// To aid debugging, text can be printed to stdout/stderr.
// On NT this can be viewed by selecting 'Allow sevice to interact with
// desktop' on the NT Services properties dialog.
// On Unix set the environment variable MQSI_RUN_ATTACHED=1 before
// starting the broker.
System.out.println ("Element = " + switchElement.getName ());
System.out.println ("Value = " + switchElement.getValue ());
}
// Change the value of an existing element
String elementValue = (String)switchElement.getValue ();
if(elementValue.equals ("add"))
switchElement.setValue ("change");
else if(elementValue.equals ("change"))
switchElement.setValue ("delete");
else if(elementValue.equals ("delete"))
switchElement.setValue ("hold");
else
switchElement.setValue ("failure");
System.out.println ("New value = " + switchElement.getValue ());
}
// Add a new tag as a child of the switch tag
MbElement tag = switchElement.createElementAsLastChild (MbElement.TYPE_NAME,
"PreviousValue",
425
elementValue);
// Add an attribute to this new tag
tag.createElementAsFirstChild (MbElement.TYPE_NAME_VALUE,
"NewValue",
switchElement.getValue ());
MbOutputTerminal out = getOutputTerminal ("out");
// Now propagate the message assembly.
// If the terminal is not attached, an exception will be thrown. The user
// can choose to handle this exception, but it is not neccessary since
// the framework will catch it and propagate the message to the failure
// terminal, or if it not attached, rethrow the exception back upstream.
out.propagate (newAssembly);
}
public String toString () {
return getName ();
}
/* Attributes are defined for a node by supplying get/set methods.
* The following two methods define an attribute 'nodeTraceSetting'.
* The capitalisation follows the usual JavaBean property convention.
*/
public String getNodeTraceSetting () {
return _nodeTraceSetting;
}
public void setNodeTraceSetting (String nodeTraceSetting) {
_nodeTraceSetting = nodeTraceSetting;
}
}
B.2.3 Compilation and packaging instructions

These two programs should not be contained in the same JAR file because of
obvious version issues, but they can be deployed at the same time. Follow the
instructions below:
1. From a command window, add to your classpath
set classpath=%path%;<install_dir>\classes\jplugin.jar
(where <install_dir> is the drive and the directory where the WebSphere
MQ Integrator installation is located)
if the setting is not already in your classpath.
2. Write programs shown above in a text editor or copy them from theWeb site. .
426
3. Save programs to <install dir>\javasource\com\ibm\samples\. Ensure that you

save the files with a .java extension and that a .txt or other extension is not
attached to the end.
4. From your previous command window, execute
cd <install dir>\javasource\
5. Execute the command javac com\ibm\samples\SwitchNode.java

6. Create the JAR using
jar cvf SwitchNode.jar com\ibm\samples\SwitchNode.class
7. Stop the broker with mqsistop <broker_name>

8. If the configuration manager is running on the same machine, issue the
command mqsistop ConfigMgr
9. Delete old versions using delete <install_dir>\jplugin\SwitchNode.jar
10. Copy the file using
copy SwitchNode.jar <install_dir>\jplugin\SwitchNode.jar
11. Execute the command javac com\ibm\samples\TransformNode.java

12. Create the JAR using
jar cvf TransformNode.jar com\ibm\samples\TransformNode.class
13. Delete old versions using delete

<install_dir>\jplugin\TransformNode.jar
14. Copy with the file using
copy TransformNode.jar <install_dir>\jplugin\TransformNode.jar
15.Restart your broker and configuration manager services using

mqsistart <broker>
mqsistart ConfigMgr
427
428
Appendix C.
Oracle8i installation and

configuration on Solaris
This appendix describes the procedures used to install Oracle8i on Sun Solaris
to support the WebSphere MQ Integrator Broker installation discussed in this
redbook. This should not be used as the only means of reference for an
installation. Please also refer to the specific Oracle installation documentation for
Solaris and to the WebSphere MQ Integrator Solaris Installation Guide for further
help.
The scenario covers the most common situations from a practical point of view.
We have provided tips and critical steps for installation and configuration. We
have also added checks at the end of each section.
429
Installation planning and design

Planning is an important part of a successful Oracle installation. Every
installation should be properly planned and should consider the requirements for
an installation in a development environment, a test environment and finally an
implementation in the production environment.
When planning the installation, the main activities are:
1. Ensuring that the software versions you plan to use have been tested
together and are official supported by the WebSphere MQ Integrator broker
installation.
2. Preparing all the software, fixes, patches and information needed for the
installation.
You may also wish to back up your systems before beginning installation.
Which versions are supported by the product?

The prerequisite hardware and software requirements for WebSphere MQ
Integrator can be found in the WebSphere MQ Integrator Sun Solaris Installation
Guide. If you are completing an Oracle installation on other platforms such as
Windows NT/2000 or AIX or HP-UX, you can still use this appendix for reference,
but make sure to use the WebSphere MQ Integrator installation guide specific to
your platform as your primary guide.
For this example, we installed Solaris 2.7, Oracle8 8.1.6 and WebSphere MQ
Integrator with no service packs. There was no other software required.
For Solaris documentation, please visit:
http://docs.sun.com
Getting started
During the installation, except when noted otherwise, you have to be logged in as
root.
These are the basic steps that need to be completed:
1. Configure Solaris and apply the recommended fixes.
2. Change the parameters of the operating system, especially semmsl and
semmns. Otherwise, Oracle will not have enough processes and memory
available and will not let you create databases.
430
3. Install Oracle.
4. Create a database for the broker. You can use any name for the SID (the user
that owns the database), but preferably limit it to names up to four characters
long (Oracle recommendation).
5. Prepare the database for an ODBC connection to be used by the WebSphere
MQ Integrator broker.
Preparing the Solaris machine

First, we prepared all the data and software needed to assure a quick
installation.
If you will be installing Solaris on a new machine, be sure to configure Solaris so
that enough space is allocated to the file systems created. This is because the
default install of Solaris will only create 27 MB for the /opt file system where all
products in this guide will be installed.
Install Oracle8i server

This section provides detailed instructions for installing and configuring the
Oracle8i Enterprise Edition Release 2 (8.1.6) for Sun SPARC Solaris on the
Oracle8i database server system.
We have organized the Oracle8i Enterprise Edition database server install into
the following phases:
Oracle8i install prerequisites
Installing Oracle8i Enterprise Edition Database Server
Oracle8i post-install configuration
Preparing the Oracle8i databases
Oracle8i disk space requirement

We recommend that you allocate the following disk space:
Oracle8i Enterprise Edition Server 8.1.6: requires 1160 MB of free disk
space.
We allowed for this space when we installed Solaris 7 by allocating space to the
/opt file system.
Appendix C. Oracle8i installation and configuration on Solaris
431
Verifying Solaris patch levels required by Oracle8i

Though we did not have to install any patches for our implementation, you should
verify your specific environment with the documentation that is provided with
your Oracle software.
Configuring the UNIX kernel for Oracle8i

To ensure that Oracle8i has enough system memory, we need to configure the
UNIX kernel.
To configure the UNIX kernel for Oracle8i, complete the following steps:
1. Start a Solaris Console window and log in as user root.
2. Back up the system file:
# cd /etc
# cp system system.bak
3. Add or modify the Solaris kernel configuration parameters. In our case, for
1024 MB of physical memory, the kernel parameters are:
set
set
set
set
set
set
set
set
msgsys:msginfo_msgmax=65535
msgsys:msginfo_msgmnb=65535
msgsys:msginfo_msgmap=258
msgsys:msginfo_msgmni=256
msgsys:msginfo_msgssz=16
msgsys:msginfo_msgtql=1024
msgsys:msginfo_msgmax=65535
msgsys:msginfo_msgseg=32768
set shmsys:shminfo_shmmax=4294967295set shmsys:shminfo_shmseg=16

set shmsys:shminfo_shmmni=300
set
set
set
set
set
set
semsys:seminfo_semmni=1024
semsys:seminfo_semmap=1026
semsys:seminfo_semmns=2048
semsys:seminfo_semmnu=2048
semsys:seminfo_semume=200
semsys:seminfo_semopm=200
4. Add also this extra kernel configuration parameters needed for Oracle:
set shmsys:shminfo_shmmin=1
set shmsys:shminfo_shmmni=100
set semsys:seminfo_semmsl=2048
set semsys:seminfo_semvmx=32767
432
Important: In particular, the semmns and semmsl parameters determine the

number of processes the kernel will handle and each Oracle database
requires, by default, 150. If these values are set too low, new databases
cannot be created or started.
5. Type the following command to shut down and reboot:

# /usr/sbin/shutdown -i6 -g0 -y
(If you have trouble with this command, try issuing the command reboot.)
6. Create groups by typing the following:
# groupadd dba
# groupadd oinstall
Creating a UNIX user account for Oracle8i

To create a user named oracle and make the user a member of the dba group,
complete the following steps:
1. Start a Solaris Console window and log in as root.
2. Create user oracle by typing the following:
# useradd -d /export/home/oracle -m -g oinstall -G dba -s /usr/bin/ksh
oracle
The syntax is as follows:

# useradd -d <path_home_dir> -m -g <primary_group> -G <secondary_group> -s
<path_shell> <username>
where:
-d <path_home_dir> is the home directory of the user
-m creates the directory of the user and .profile
-g is the primary group to add the user to
-G is the secondary group to add the user to
-s <path_shell> is the path of the shell used by this user
<username> is the user name to create
3. Create a password for user oracle by typing the following:

# passwd oracle
This will prompt the user for the password.
433
4. Verify login with user:

# su - oracle
$ su - oracle
You will be prompted for your password.
Setting environment variables

To set environment variables as part of the .profile of the oracle user shell,
complete the following steps:
1. Log in as user oracle
# su - oracle
2. Add the following environment variables to the oracle user .profile:

umask 022
export ORACLE_BASE=/opt/oracle8/u01
export ORACLE_HOME=$ORACLE_BASE/app/oracle/product/8.1.6
export ORACLE_SID=oracle
export PATH=$PATH:$ORACLE_HOME/bin
# The following export is required for XWindows used by Oracle8i install.
export DISPLAY=hostname:0.0
If you will be working on the Solaris machine, you can use :0.0 without the host
name.
Important: A SID is the owner of a database, a user inside the Oracle
environment, because the owners of the databases are not Solaris users as
with DB2. No matter what you type here, in subsequent steps we will create
new SIDs for each database. It is necessary to use a SID. If a SID is not
provided at this stage, we found that the installation produces an error.
Creating mount points

To create mount points, complete the following steps:
2. Create the following directories:
This directory is used for the Oracle8i software:
# mkdir -p /opt/oracle8/u01
The following directory is intended to be used for databases:

# mkdir -p /opt/oracle8/u02
434
3. Change the owner of the directories to user oracle and group dba by typing
the following command:
# chown -R oracle:dba /opt/oracle8
4. Change permissions as follows:

# chmod -R g+w /opt/oracle8
Installing Oracle8i Enterprise Edition Server

On the database server system, we installed the Oracle8i Enterprise Edition.
This database server will host the WebSphere MQ Integrator broker database.
Complete the following steps to install the Oracle8i Enterprise Edition server:
1. Start a Solaris Console window, and log in as user oracle.
# su - oracle
2. Insert the Oracle8i Enterprise Edition Release 2 (8.1.6) for Sun SPARC
Solaris CD-ROM on the database server.
3. To start the Oracle8i install, type the following:
# xhost +
access control disabled, clients can connect as any host
# su - oracle
$ /cdrom/oracle8i/runInstaller
4. When the Oracle8i Welcome window appears, click Next.

5. When the File Locations window appears, verify that the paths are as follows
and then click Next:
Source: /cdrom/oracle8i/stage/products.jar
Destination: /opt/oracle8/u01/app/oracle/product/8.1.6
Note: The destination should be the path specified as the ORACLE_HOME.
6. When the UNIX Group Name window appears, enter the group oinstall
defined above, and then click Next.
7. When the Oracle Universal Installer window appears, you will be prompted to
run a script as user root in another Solaris Console window.
a. Start a Solaris Console window and log in as root.
b. Execute the script by typing the following:
# /tmp/OraInstall/orainstRoot.sh
435
c. You should see a message that states the following:

Creating Oracle Inventory pointer file (/var/opt/oracle/orainst.loc).
Changing groupname of /opt/oracle8/u01/oraInventory to dba.
8. Click the Oracle Universal Install window to bring it back to the foreground,
and then click Retry.
9. When the Available Products window appears, select Oracle8i Enterprise
Edition 8.1.6.0.0, and then click Next.
10. When the Installation Types window appears, select Typical or Standard,
and then click Next.
11. For the next windows, you can accept the defaults by clicking Next. When the
Create Database window appears, you can create a default database if you
want, but it is not necessary, because we are going to the specific database
required in future steps. To avoid creating the default database, select No and
click Next.
12. When the Summary window appears, review all the information. You can
click Back to change any selection. When everything looks correct, click
Install.
The installation will begin. It cannot be left unattended because it requires
some scripts to be run as root during the process.
13.When the Setup Privileges window appears, a message will be displayed to
run the following script:
a. Start a Solaris Console window and log in as root.
b. Execute the script by typing:
# /opt/oracle8/u01/app/oracle/product/8.1.6/root.sh
c. You will be prompted to enter the full path to the local bin directory. We
entered /usr/bin. Click Enter.
d. Click the Setup Privileges window to bring it to the foreground, then click
OK.
14.When the End of Installation window appears, click Exit.
The Oracle8i Enterprise Edition server installation is now complete.
Oracle 8i post-install configuration

After the Oracle8i installation, we need to perform the following configuration
steps:
Update oracle user .profile
Create dbora for database autostart (optional)
436
In this section, we will add Oracle8i required environment variables to the oracle
user .profile that we created by completing the following steps:
1. Start a Solaris Console window.
2. Log in as the oracle user.
# su - oracle
3. Add entries to the end of the oracle user .profile as seen in Example 10-14.
Example 10-14 oracle user .profile entries required for Oracle8i
export LD_LIBRARY_PATH=$ORACLE_HOME/lib
CLASSPATH=$ORACLE_HOME/JRE:$ORACLE_HOME/jlib:$CLASSPATH
CLASSPATH=$ORACLE_HOME/product/jlib:$CLASSPATH
export CLASSPATH
ORACLE_SID=oracle
ORAENV_ASK=NO
. /usr/bin/oraenv
4. This script overrides the ORACLE_HOME defined in the oracle user .profile.
Modify /usr/bin/oraenv to correct the problem. Find the following text and add
a # at the beginning of each line to make it a comment:
ORAHOME=`dbhome "$ORACLE_SID"`
case $? in
0)ORACLE_HOME=$ORAHOME ;;
*)echo $N "ORACLE_HOME = [$ORAHOME] ? $C"
read NEWHOME
case "$NEWHOME" in
"")ORACLE_HOME=$ORAHOME ;;
*)ORACLE_HOME=$NEWHOME ;;
esac ;;
esac
export ORACLE_HOME
Net 8 Configuration
This section describes the required configuration for Net8 after the Oracle8i
installation.
2. Update the /etc/services file with the listener. The listener name and port were
defined during the Oracle8i installation (Net8).
We added the following line to our services file:
LISTENER 1521/tcp
3. Save the services file.
437
Note: The /etc/services file is symbolically linked to /etc/inet/services. When

saving the file with vi use the vi w! command to override the default write
permissions.
4. Check the status of the listener.

# su - oracle
$ lsnrctl status LISTENER
Where LISTENER is the name or your listener (in our case the name is
LISTENER).
5. You can start the listener with:
$ lsnrctl start LISTENER
Preparing the Oracle8i database

Prior to the creation of a broker, the database needs to be created.
The steps in this process are as follows:
Create a new Oracle8i database
Conduct database verification
Tune the database
Configure autostart of the database
Create the Oracle ID and tablespace
Create broker user and tablespace
Configure Net8
Creating an Oracle 8i database

We will create the following Oracle8i databases in preparation for the WebSphere
MQ Integrator broker. If you want to create multiple brokers, you can either create
a new database instance for each broker or run them all from one instance.
We are going to create one database for this example called:
wmqibkdb (WebSphere MQ Integrator Broker Database)
438
To create an Oracle8i database, complete the following steps on the Oracle8i

Enterprise Edition Server system:
1. Start a Solaris Console window as root.
2. Disable access control so that any user can access to the display:
# xhost +
3. Log in as user oracle:

# su - oracle
4. Run the Oracle8i Database Configuration Assistant:

$ dbassist &
5. When the Oracle Database Configuration Assistant welcome window

appears, select Create a database and then click Next.
6. Select Custom as the database type and then click Next.
7. Select Multipurpose as the application type and then click Next.
8. Enter the Concurrently connected users: <value>. We accepted the default
(15). Then click Next.
9. Select Dedicated Server Mode as the server mode and click Next.
10.In the Select Options window, deselect all options, except SQL *Plus help
(optional), and then click Next.
11.When asked to review the database information, enter the following:
Global Database Name: wmqibkdb
SID (do not use more than four characters for this name): bkdb
Initialization Filename: /opt/oracle8/u01/admin/was/pfile/initwas.ora
Compatible Parameter: 8.0.5
12. For the character sets, we left the defaults. MQSeries and WebSphere MQ
Integrator should support any available character sets, so customize this for
your needs. Click Next.
13.When the Review the control file parameters window appears, look for the
directories where it will save the database data.
If it has something to do with admin, then leave the default
/opt/oracle8/u01 directory.
Otherwise, if it has something to do with the oradata, change the directory
to u02 for the wmqibkdb database.
14. Carefully check that all paths are correct, because the defaults may be
incorrect. The control files should be placed under the user SID directory
(u02).
439
15. When the Review the SYSTEM tablespace information window appears, look
for the directories where it will save the database data, and correct them if
necessary.
16.When the Review the redo log file parameter information window appears,
carefully review the paths and click Next.
17.When the Review the logging parameter information window appears, review
it carefully and click Next.
18.When the Review the SGA information window appears, check the number of
processes this database will use.
If you have followed our instructions and set the kernel parameters semmsl
and semmns, then the default setting of 150 processes will work.
If you have not set high values for semmsl and semmns, decrease the
processes value. Decreasing this value will not prevent the creation of the
database and this value can be changed in the future. If this value is too
high for your system, the database will not be created.
19.Click Next (more tuning will be done in later steps).
20. When the Review the directory path information window appears, accept the
defaults and click Next.
21.Select Create database now, and click Finish.
22.When the Oracle Database Configuration Assistant alert appears, asking if
you want to proceed, click Yes.
23.The database creation progress indicator should be visible. This process
takes approximately 20 minutes.
Oracle 8i database verification

After the installation, we recommend that you take some steps to verify that the
Oracle8i Enterprise Edition server is installed correctly.
To verify the Oracle8i Enterprise Edition, complete the following steps:
1. Start a Solaris Console window and log in as user oracle.
# su - oracle
2. To start an Oracle command window, type the following:

$ sqlplus system/manager@wmqibkdb
SQL> quit
If the username/password combination does not work, use whatever the default
value was that was displayed during the database creation.The Oracle user
system has a default password of manager and has access to all databases.
Later we will create users for each database.
440
Database tuning
1. Start a Solaris Console window and log in as user oracle.
# su - oracle
2. In the $ORACLE_HOME/dbs/init<your_SID>.ora initialization file, modify the

values of the parameters shown in . In this table, we show the recommended
minimum values for these parameters, but in our Solaris system we kept the
highest of the two values (the recommended and the default).
Table 10-2 Oracle8i database tuning parameters
Parameters
wmqibkdb database values
open_cursors
200
db_block_buffers
2000
shared_pool_size
20000000
processes
100
3. Stop and start the Oracle8i Server for the database tuning changes to take
effect:
# su - oracle
$ dbshut
$ dbstart
Note: The Oracle8i dbshut and dbstart scripts will stop and start all
databases. This behavior is desired in this example, but may not be
appropriate in other situations.
Using svrmgrl is another option for stopping and starting the databases.
4. If your Oracle8i Server database instances do not start, check the tuning
parameters entered for errors. Changing the tuning values beyond the
physical memory available on the system will result in the database instance
not starting.
441
Configuring the autostart of the database

The following procedure will automate the startup and shutdown of the Oracle8i
database server.
1. Edit the /var/opt/oracle/oratab file.
Database entries in the oratab file appear in the following format:
ORACLE_SID:ORACLE_HOME:{Y|N}
where Y or N specifies whether you want the dbstart and dbshut scripts to
start up and shut down the database. Find the entries for all the databases
that you want to start up. They are identified by the SID in the first field.
Change the last field for each to Y to enable the database to start when the
dbstart command is run.
For example:
oracle:/opt/oracle8/u01/app/oracle/product/8.1.6:Y
2. Create a dbora file.

This procedure only needs to be completed once on the Oracle8i database
server.
a. Change to the /etc/init.d directory:
# cd /etc/init.d
b. Create a file called dbora. Example 10-15 provides a sample dbora file.
We changed the ORA_HOME to reflect the directory specified during the
Oracle8i server installation.
Example 10-15 Sample dbora
#!/bin/sh
# Set ORA_HOME to be equivalent to the ORACLE_HOME
# from which you wish to execute dbstart and
# dbshut
# set ORA_OWNER to the user id of the owner of the
# Oracle database in ORA_HOME
ORA_HOME=/opt/oracle8/u01/app/oracle/product/8.1.7
ORA_OWNER=oracle
case "$1" in
start)
# Start the Oracle databases:
# The following command assumes that the oracle login will not prompt the
# user for any values
su - $ORA_OWNER -c $ORA_HOME/bin/dbstart &
;;
stop)
442
# Stop the Oracle databases:

# The following command assumes that the oracle login will not prompt the
# user for any values
su - $ORA_OWNER -c $ORA_HOME/bin/dbshut &
;;
esac
c. Link the file dbora as follows:

# ln -s /etc/init.d/dbora /etc/rc0.d/K10dbora
# ln -s /etc/init.d/dbora /etc/rc2.d/S99dbora
Creating an Oracle broker user, grant access and configure

ODBC
If you have completed all of the steps successfully up to this point, you can return
to Oracle customization on page 135. The material in that section will describe
how to create a new user for the broker to use, grant the appropriate access and
configure the ODBC connection to the new data source.
443
444
Appendix D.
Additional material
This redbook refers to additional material that can be downloaded from the
Internet as described below.
Locating the Web material

The Web material associated with this redbook is available in softcopy on the
Internet from the IBM Redbooks Web server. Point your Web browser to:
ftp://www.redbooks.ibm.com/redbooks/SG246509
Alternatively, you can go to the IBM Redbooks Web site at:

ibm.com/redbooks
Select the Additional materials and open the directory that corresponds with
the redbook form number, SG24-6509.
Contents of the Web material

The material is organized in several directories. Each directory contains files that
are specific to a particular chapter.
445
Files related to Chapter 3

Directory name
CM201
CM202
CM210
Description
Contains exported message flows and message sets
used in an MQSeries Integrator V2.0.1 environment. A
sample input file for the utility mqsiput is also included.
used in an MQSeries Integrator V2.0.2 environment.
Sample input files for the utility mqsiput are also included.
used in an WebSphere MQ Integrator V2.1 environment.
Sample input files for the utility mqsiput are also included.
These files should be used in an environment that has the required level of
software. The level of MQSeries Integrator and WebSphere MQ Integrator that
we have used to create these files is documented in Appendix A,
Hardware/software configuration on page 411.

All files related to Chapter 6 should be used in a version 2.1 environment of
WebSphere MQ Integrator. The software should be at least at the level U200167.
File name
TAGGED_TEST.mrp
DLM_TEST.mrp
TAG_TO_XML.xml
CSV_TO_XML.xml
Description
Exported message set.
Exported message flow.
Exported message flow.

All files related to Chapter 7 should be used in a version 2.1 environment of
WebSphere MQ Integrator. The software should be at least at the level U200167.
File name
CONTACTS.mrp
CONTACTS_flows.zip
Example1.xml
Example2.xml
Example.dtd
Description
Zip file containing five exported message flows.
Sample XML message to test the message flows.
Sample XML message to test the message flows.
Document Type Definition for the sample messages.

File name
swiftmsg.txt
SWIFTFlows.xml
rulesfromNEONB
446
Description
Sample SWIFT message.
Sample message flows for SWIFT messages.
Collection of rules for import in a New Era Of Networks
environment.
formatsfromNEONB
formatsfromNEONA
Collection of formats for import in a New Era Of Networks

environment.
Collection of formats for import in a New Era Of Networks
environment.

File name
InputNodeFlow.xml
SwitchNode.java
SwitchNode.jar
SocketNode.zip
SocketNode.jar
TransformNode.java
Description
Message flow that uses the Java input node and plug-in
node.
Source code for the SwitchNode plug-in.
Compiled code for the SwitchNode plug-in.
All of the source code for the SwitchNode input node.
Compiled code for the SocketNode input node.
Source code for the TransformNode plug-in.

File name
Aggregation.txt
FAN_OUT.xml
FAN_IN.xml
PROC_A.xml
PROC_B.xml
Description
User trace output that shows the aggregation of
messages.
Exported message flow FAN_OUT.
Exported message flow FAN_IN.
Exported message flow PROC_A.
Exported message flow PROC_B.
System requirements for downloading the Web material

The following system configuration is recommended:
Hard disk space:
Hard disk space:
Operating System:
Processor :
Memory:
5 MB is required to download and unzip the package.

1 GB will be required to install and configure all
WebSphere MQ Integrator components.
Windows NT V4 with Service Pack 6a or Windows 2000
with Service Pack 2.
Pentium processor running at 500 Mhz or faster
512 MB.
How to use the Web material

Create a subdirectory (folder) on your workstation and unzip the contents of the
Web material zip file into this folder. This will create a number of directories, each
with a name referring to the chapter to which the material belongs.
Appendix D. Additional material
447
448
Related publications
The publications listed in this section are considered particularly suitable for a
more detailed discussion of the topics covered in this redbook.
IBM Redbooks
For information on ordering these publications, see How to get IBM Redbooks
on page 450.
MQSeries Publish/Subscribe Applications, SG24-6282
Intra-Enterprise Business Process Management, SG24-6173
WebSphere MQ Integrator for z/OS V2.1 Implementation Guide, SG24-6528
Other resources
These publications are also relevant as further information sources:
WebSphere MQ Integrator Introduction and Planning, GC34-5599
WebSphere MQ Integrator Using the Control Center, GC34-5602
WebSphere MQ Integrator Programming Guide, SC34-5603
WebSphere MQ Integrator Administration Guide, SC34-5792
WebSphere MQ Integrator ESQL Reference, SC34-5923
WebSphere MQ Integrator Problem Determination Guide, GC34-5920
WebSphere MQ Integrator Working with Messages, SC34-6039
WebSphere MQ Integrator Messages, GC34-5601
Referenced Web sites

These Web sites are also relevant as further information sources:
WebSphere MQ Family home page
http://www-4.ibm.com/software/ts/mqseries/
WebSphere MQ Integrator home page

http://www-4.ibm.com/software/ts/mqseries/integrator/
449
WebSphere MQ Family manuals

http://www-4.ibm.com/software/ts/mqseries/library/manualsa/index.html
WebSphere MQ Family Support

http://www-3.ibm.com/software/ts/mqseries/support/summary/
WebSphere MQ Family SupportPacs

http://www-4.ibm.com/software/ts/mqseries/txppacs/txpm1.html
W3C consortium
http://www.w3.org
Java documentation
http://docs.sun.com
How to get IBM Redbooks

You can order hardcopy Redbooks, as well as view, download, or search for
Redbooks at the following Web site:
ibm.com/redbooks
You can also download additional materials (code samples or diskette/CD-ROM

images) from that site.
IBM Redbooks collections

Redbooks are also available on CD-ROMs. Click the CD-ROMs button on the
Redbooks Web site for information about all the CD-ROMs offered, as well as
updates and formats.
450
Glossary
Access Control List (ACL). The list of
principals that have explicit permission (to
publish, to subscribe to, and to request
persistent delivery of a publication message)
against a topic in the topic tree. The ACLs
define the implementation of topic-based
security.
Check out. The Control Center action that

extracts and locks a resource from the
configuration or message repository for local
modification by a user.
Collective. A totally connected set of brokers
forming part of a multi-broker network for
Publish/Subscribe applications.
AMI. See Application Messaging Interface.

API. See Application Programming Interface.
Application Messaging Interface. The
programming interface provided by MQSeries
that defines a high level interface to message
queuing services.
Application Programming Interface. An
interface provided by a software product that
enables programs to request services.
BLOB. Binary Large Object, a block of bytes
of data (for example, the body of a message)
that has no discernible meaning, but is treated
as one solid entity that cannot be interpreted.
Configuration Manager. A component of

WebSphere MQ Integrator that acts as the
interface between the configuration repository
and an existing set of brokers.
Configuration repository. Persistent
storage for broker configuration and topology
definition.
Configuration. The collection of brokers,
their execution groups, the message flows and
sets that are assigned to them, and the topics
and associated access control specifications.
Connector. See Message processing node
connector.
Broker domain. A collection of brokers that

share a common configuration, together with
the single Configuration Manager that controls
them.
Control Center. The graphical interface that

provides facilities for defining, configuring,
deploying, and monitoring resources of the
WebSphere MQ Integrator network.
Broker. See Message broker.
Debugger. A facility on the Message Flows

view in the Control Center that enables
message flows to be visually debugged.
Check in. The Control Center action that

stores a new or updated resource in the
configuration or message repository.
Deploy. Make operational the configuration

and topology of the broker domain.
Destination list. See Local environment.
451
Distribution list. A list of MQSeries queues

to which a message can be put using a single
statement.
Document Type Definition. The rules that
specify the structure for a particular class of
XML documents. The DTD defines the
structure with elements, attributes, and
notations, and it establishes constraints for
how each element, attribute, and notation can
be used within the particular class of
documents.
Domain. See Message Domain and Broker
Domain.
DTD. See Document Type Definition.
Element. A unit of data within a message
that has a business meaning.
Java Database Connectivity. An application

programming interface that has the same
characteristics as ODBC but is specifically
designed for use by Java database
applications.
Java Development Kit. Software package
used to write, compile, debug and run Java
applets and applications.
Java Message Service. An application
programming interface that provides Java
language functions for handling messages.
Java Runtime Environment. A subset of
the Java Development Kit that allows you to
run Java applets and applications.
JDK. See Java Development Kit.
JMS. See Java Message Service.
ESQL. See Extended SQL.

JRE. See Java Runtime Environment.
Execution group. A named grouping of
message flows that have been assigned to a
broker.
Extended SQL. A specialized set of SQL
functions and statements based on regular
SQL, extended with functions and statements
unique to WebSphere MQ Integrator.
Field reference. A sequence of
period-separated values that identify a specific
field within a message tree. An example of a
field reference might be
Address.Country.City.Street.HouseNumber.
Input node. A message flow node that
represents a source of messages for the
message flow.
lil. See Loadable Implementation Library.

Loadable Implementation Library. The
module that implements a plug-in node or a
custom-written parser. One library can
implement several plug-in nodes or parsers.
Local environment. Information associated
with the message while it is being processed
by a message flow. This information includes:
User-defined variable information created
and used by nodes within the message
flow.
A list of destinations to which a message is
sent. Destinations can include other nodes
(for example when using the RouteToLabel
node) and MQSeries queues (used by
MQOutput nodes).
A list of destinations to which a message
has been sent by an output node.
452
Message broker. A set of execution

processes hosting one or more message
flows.
Message domain. The value that
determines how the message is interpreted
(parsed). The following domains are
recognized:
MRM, which identifies messages defined
using the Control Center.
NEONMSG and NEON, which identify
messages created using the New Era of
Networks user interfaces.
XML, JMSMap, and JMSStream, which
identify messages that are self-defining.
BLOB, which identifies messages that are
undefined.
Message flow. A directed graph that

represents the set of activities performed on a
message or event as it passes through a
broker. A message flow consists of a set of
message processing nodes and message
processing connectors.
Message parser. A program that interprets
the bit stream of an incoming message and
creates an internal representation of the
message in a tree structure. A parser is also
responsible to generate a bit stream for an
outgoing message from the internal
representation.
Message processing node connector. An
entity that connects the output terminal of one
message processing node to the input
terminal of another.
Message processing node. A node in the
message flow, representing a well defined
processing stage. A message processing
node can be one of several primitive types or it
can represent a subflow.
Message queuing. A communication

technique that uses asynchronous messages
for communication between software
components.
Message repository. A database holding
message template definitions.
Message set. A grouping of related
messages.
Message type. The logical structure of the
data within a message.
MQRFH. An architected message header
that is used to provide metadata for the
processing of a message. This header is
supported by MQSeries Publish/Subscribe.
MQRFH2. An extended version of MQRFH
being used by WMQI applications.
Node. See Message processing node and
Plug-in node.
ODBC. See Open Database Connectivity.
Open Database Connectivity. A standard
application programming interface for
accessing data in both relational and
non-relational database management
systems. Using this API, database
applications can access data stored in
database management systems on a variety
of computers even if each database
management system uses a different data
storage format and programming interface.
ODBC is based on the call level interface (CLI)
specification of the X/Open SQL Access
Group.
Output node. A message processing node
that represents a point at which messages
flow out of the message flow.
Glossary
453
Parser. See Message parser.

Plug-in node. An extension to the broker,
written by a third-party developer, to provide a
new message processing node or message
parser in addition to those supplied with the
product.
Point-to-point. Style of application
messaging in which the sending application
knows the destination of the message.
Predefined message. A message with a
structure that is defined before the message is
created or referenced.
Publish/subscribe. Style of application
messaging in which the providers of
information (publishers) are decoupled from
the consumers (subscribers) of that
information using a broker as an intermediate
runtime component.
Publisher. An application that makes
information about a topic available to a broker
in a publish/subscribe system.
Queue Manager. A subsystem that provides
queuing services to applications. It provides
an application programming interface so that
applications can access messages on the
queues that are owned and managed by the
queue manager.
Queue. A WebSphere MQ object.
Applications can put messages on, and get
messages from, a queue. A queue is owned
and managed by a queue manager. A local
queue is a type of queue that can contain a list
of messages waiting to be processed. Other
types of queues cannot contain messages but
are used to point to other queues.
454
Self-defining message. A message that

defines its structure within its content. For
example, a message coded in XML is
self-defining.
Subflow. A sequence of message
processing nodes that can be included within
a message flow.
Subscriber. An application that requests
information about a specific topic form a
publish/subscribe broker.
Terminal. The point at which one node in a
message flow is connected to another node.
Topic. A character string that describes the
contents of the information that is being
published in a publish/subscribe system.
User Name Server. The WMQI component
that interfaces with operating system facilities
to determine valid users and groups.
Wire format. A description of the physical
representation of a message within the
bit-stream.
XML. eXtensible Markup Language, a
standard for the representation of data.
Abbreviations and acronyms

Application Messaging
Interface
MQI
Message Queuing Interface
MRM
Message Repository Manager
API
Application Programming
Interface
NEON
New Era Of Networks
BLOB
Binary Large Object
OAG
Open Applications Group
BOD
Business Object Document
ODBC
Open Database Connectivity
PCDATA
Parsed Character Data
RRS
Resource Recovery Services
AMI
CSV
Comma Separated Variable

Length
CWF
Custom Wire Format
SQL
Structured Query Language
DB2
Database 2
SWIFT
DTD
Document Type Definition
Society For Worldwide

Interbank Financial
Telecommunications
EAI
Enterprise Application
Integration
TDWF
Tagged/Delimited Wire
Format
EDI
Electronic Data Interchange
UOW
Unit of Work
ESQL
Extended Structured Query

Language
UR
Unit of Recovery
GUI
URI
Uniform Resource Identifier
HTML
HyperText Mark-up Language
URL
Uniform Resource Locator
XML
eXtensible Mark-up Language
HTTP
HyperText Transport Protocol
IBM
International Business
Machines Corporation
IDE
Integrated Development
Environment
ITSO
International Technical
Support Organization
JAR
Java Archive
JDBC
Java Database Connectivity
JDK
Java Development Kit
JMS
Java Message Service
JRE
Java Runtime Environment
lil
loadable implementation
library
MMC
Microsoft Management
Console
455
456
Index
AIX 71
Solaris 138
Windows 52, 158
A
add
a breakpoint 200
a delimiter 168
a plug-in node to Control Center 360
broker to topology 42, 59, 74, 84, 99
element to workspace 214, 334
elements to a compound type 174
message set to workspace 100
NEON message set to workspace 334
new group
AIX 67
Solaris 134
new user ID
AIX 67
Oracle 136
Solaris 134
Windows 145
physical format 168, 208
after import 118
during import 100, 124
types to workspace 212, 214
aggregation 380
AIX administration 67, 112
application communication protocol
MQSeries Everyplace 3
point to point 3
publish/subscribe 3
request/reply 380
SCADA 3
application group
specifying in MQInput node 313
versus message set 313
application isolation 7
applying maintenance 89, 107
SQL Server 147
assignment
message flow 9, 43, 85, 102, 184, 366
message set 43, 85, 102, 184
role of assigner 11
security 39
automate
channel start-up
B
broker
See message broker
build time 18
C
channel
create receiver
AIX 71
Solaris 138
Windows 55, 161
create sender
AIX 71
Solaris 138
Windows 53, 160
for brokers 7, 57, 138
for Configuration Manager 58
for Control Center users 7
triggering
AIX 71
Solaris 138
Windows 52, 158
Check node 398
check-in process 177
classpath for plug-in nodes 359
coexistance of multiple versions 87, 107
collective 7, 10
command
add group
Solaris 134
add user
Solaris 134
change password
Solaris 134
consistency check 251, 265, 284
create broker
AIX 72
Solaris 138
Windows 47, 50, 66, 82, 98, 105
457
create Configuration Manager 64, 97

create queue manager
AIX 70
Solaris 133
DB2 command window 117, 252
db2profile 69
delete Configuration Manager 117, 123
drop message repository tables 117, 124
drop mrm tables 117, 124
format export 248, 267
format import 248, 259, 283
format log 225
import message set 117, 124
list WebSphere MQ Integrator resources 138,
157
migrate configuration repository 117, 124
MQSeries command interface
AIX 70
Solaris 134
Windows 57
NNSY version verification command 255
ping channel 72
ping database listener 135
read log 225
reload rules and formats 249
rule export 267
rule import 259, 284
running definition scripts 57
software installation
AIX 113
Solaris 134
Windows 153
software uninstall
AIX 256, 268
HP-UX 256
Solaris 256
Windows 256, 268
start broker 118, 125, 141, 360, 374
start Configuration Manager 100, 118, 125, 374
start database listener 135
start queue manager 70, 133
start tracing 224
stop broker 360, 374
stop Configuration Manager 100, 374
compatibility 239
compound type
add elements 174
create 172
create a message based on 176
458
for attributes 217

type content 173
compound types
for elements 217
Compute node 180, 182, 196197, 218, 222
propagate statement 231, 388
return statement 231
access to NNSY database 262, 288, 334
communication 6, 50, 71, 82, 98
create 64, 95
database authorities 63, 94
database interaction 6
delete 29, 117, 123
features 5
queue manager 40
security requirements 39, 62, 94
start 100, 118, 125, 374
stop 100, 374
upgrade requirements 108
version dependance 73, 93
configuration repository 5, 9, 29
migrate tables 117, 124
configure database access 274
consistency check 251, 265, 284
consolidate Configuration Managers 93, 128
Control Center 11
add message set 100
add NEON message set 334
communication 7
import message flow 100
in a multi-version domain 73, 92
log messages from other versions 58
NNSY message properties file 289
security 26
using the NEON message set 330
version dependance 73
copy
message headers 181, 219
message set identifier 182
message tree 181, 196
create
compound type 172
Configuration Manager 64, 95
database
for NNSY support 269
SQL Server 148
database for NNSY support 269
message 176
message broker
AIX 72
dummy 117
Solaris 138
Windows 47, 50, 66, 80, 98, 105, 155
message element 170
message flow 179
message set 165
new user ID
AIX 67
Oracle 136
Solaris 134
Windows 154
plug-in node in Control Center 360
queue 185
queue manager
AIX 70
Solaris 133
Windows 45, 62, 78, 155
receiver channel
AIX 71
Solaris 138
Windows 55, 161
sender channel
AIX 71
Solaris 138
Windows 53, 159
transmission queue
AIX 70
Solaris 138
Windows 50, 158
user group
AIX 67
Solaris 134
create a JAR file 359
D
database
authorities
for broker and DB2 47, 63, 68, 79, 95
for broker and Oracle 136, 140
for broker and SQL Server 148
for Configuration Manager 63, 94
broker and NNSY 242
client configuration 274
create
SQL Server 148
NNSY
access for broker 262, 286
access for Configuration Manager 262, 288
database configuration
DB2 68
Oracle 135
database connection file
add development entries 287
add runtime entries 285
create
V2.0.x 243
V2.1.0 245, 272
entries for export and import 253
entry for broker 343
entry for Configuration Manager 262, 288, 334
name
V1.x 253
V2.0.x 244
V2.1.0 253
updating initial file 258
database listener
start 135
status 135
Database node 333
database schema 243
DB2 command window 117, 252
debug
Compute node 198
message flow 200
define
attributes of a node
in Control Center 362
in source code 356
queue manager 40
terminals of a node
in source code 356, 372
definition model 18
delete
broker
during uninstall 124125
broker from topology 109
message set from broker 127
delimiter 168, 177, 192
deployment
debug message flow 200
deleted broker 109
errors in a multi-version environment 86, 106
Index
459
full versus delta 109

log file 185, 229
message broker 5
message flow 5, 85, 102, 366
message set 18, 85, 102, 185
topology 42, 60, 74, 84, 99
verify results 185
destination of trace 224
document type definition 206
drop mrm tables 117, 124
duplicate node names 101
message set 21, 116, 123

NNSY formats 248
F
features of
broker 7
Configuration Manager 5
ESQL 24
Filter node 388
flow
See message flow
FlowOrder node 388
E
element
See message element
environment variable
after uninstall 256
ICU_DATA 261, 287288
MQSI_PARAMETERS_FILE 244
NEON_ROOT 244
NN_CONFIG_FILE_PATH 243, 245, 253, 261,
282, 286, 288
NNSY_CATALOGUES 245, 261, 286, 288
NNSY_ROOT 245, 261, 286, 288
ODBCINI
AIX 68
Solaris 134
ORACLE_HOME 140
PATH 262, 288
error
invalid input XML 227
wrong order of elements 228
ESQL
code palette 17, 25
create statement 234
features 24
for XML attributes 233
loops and branches 16
move statement 234
reference variables 233
using in a Compute node 181
ESQL attribute names versus XML attribute names
223
execution group
See message broker
export
DTD 209
message flow 13
460
G
generate
DTD 209
generic XML 232
multiple messages 231
XML header 233
grant database authorities
for broker and DB2 47, 79, 9495
AIX 68
for broker and Oracle 136, 140
for broker and SQL Server 148
for Configuration Manager and DB2 63
NNSYGRP 258, 268
I
import
C and COBOL 211
Cobol copybook 74
DTD 206, 208
message flow 13, 100, 203, 236
error 101
message set 21, 100, 117, 124, 203, 236
physical format 203
NNSY format 248, 259, 283
NNSY rule 259, 284
inbound MQSeries communication
AIX 71
Solaris 133
input format
versus message type 313
input node 352
definition of an input node class 356
install after uninstall 117, 123
invalid order of elements 227
J
Java Development Kit 354
Java interface for nodes 353
L
Label node 327
language versions of log messages 58
log file
deployment 185, 229
queue manager 46, 62, 78, 133
renamed NNSY log files 249
syslog
Solaris 137
writing log records from a plug-in 357
writing to the log file 354
log messages 58
logging requirements 46, 62, 78, 133
loop
in a message flow 17, 388
in ESQL 16, 230
M
message
create 176
examples of tagged and delimited 239
logical model 19
sample SWIFT message 291
wire format 21
message broker 2
access to NNSY database 262, 286, 343
add to topology 42, 59, 74, 84, 99
assign message flow 9, 43, 85, 102, 184, 366
assign message set 43, 85, 102, 184
collective 7, 10
communication 6, 50, 71
create 80
AIX 72
Solaris 138
Windows 47, 50, 66, 98, 105, 155
create dummy 117
database access
AIX 68
database authorizations 63, 68, 79, 136,
148149
database connectivity 242
database security 47
delete 29
delete during uninstall 109, 124
delete from topology 109

domain 7
features 7
group membership 154
instance name 9
ODBC interface
AIX 68
Solaris 136
Windows 150
operations 12
queue manager 40
required resources 8
security 39
security requirements 40, 46, 63, 79, 94
AIX 67
service user ID 154
start 118, 125, 141, 360
stop 360
supported database software 23, 132, 144
supported platforms 8
user profile
AIX 69
Solaris 134
UUID 112
message consolidation 380
message domain 184, 289
NEON 246
NEON and NEONMSG 317
NEONMSG 247
message element
change contents 201
create 170
order 171
order in output message 197
re-order 178
separation 177
message flow
assignment 9, 43, 85, 102, 184, 366
breakpoint 200
components 13
create 179
debugging 198
execution control 9
export 13
features used 41
functionality 2
import 13, 100, 203, 236
loops 17, 388
security 39
Index
461
stop 367
sub-flow 14, 17
transactional 23
message length 50
message processing model 290
message processing node
See node
message repository
drop tables 117, 124
message routing
in NEON domain 320
in NEONMSG domain 327
message set
add to workspace 100
assignment 43, 85, 102, 184
create 165
deployment 18
export 116, 123
identifier 166
import 117, 124, 203, 236
name 165
NEON message set 334
properties 166
repository 6, 29
security 39
unassign 127
UUID 32
UUID after import 127
versus application group 313
message transformation 181
from NEONMSG to XML 300, 306
NEON domain 292
NEONMSG domain 296
message tree 383
copy 196
copying 181
copying individual elements 181
examine contents 201
message type
versus input format 313
messaging standard 168, 206
migrate
broker database 117
configuration repository 117, 124
migration steps
for NNSY 250
MQInput node 196, 218
messages in NEON domain 293, 313
messages in NEONMSG domain 298
462
setting properties 179

MQMD
adding a message descriptor 364, 388
MQOutput node 184
using destination list 323
MQReply node 396
MQRFH and MQRFH2 3, 15, 180, 344345, 387,
393
MQSeries
channel definitions 57, 71, 138
create queue manager
AIX 70
Solaris 133
Windows 45, 62, 78, 155
executing commands
AIX 70
Solaris 134
Windows 57
message length 50
queue definition 70, 138, 158, 185
system queues
for a broker 7
for User Name Server 10
MQSeries Everyplace 3
MQSeries Integrator
components
version 1.x product 238
version 2.x product 4
NEON compatibility matrix 239
product history 238
MQSeries security 39
MRM
changes 29
components 18
type composition 20
MRM versus XML element name 216
MRM XML versus generic XML 227, 232
multi-version environment
deployment errors 86, 106
N
NEON Application Group 310
NEON message set 330
NEONFormatter node
definition 246
example 294, 297, 308, 314, 318
NEONMap node 298
definition 247
example 297, 304, 319
NEONMap versus NEONTransform nodes 296
NEONRules node
definition 246
example 308, 314, 322
subscription 311
NEONRulesEvaluation node
definition 247
example 327, 343
NEONTransform node
definition 247
example 306
network requirements 46
network services 72
New Era of Networks
using an MQRFH or MQRFH2 header 345
NNFie
session definition
V2.0.1 253, 266
V2.1.0 281
NNRie
session definition
V2.0.1 253, 266
V2.1.0 281
NNSY format
check consistency 252, 284
consistency check 265
export 254, 267
import 259, 283
reload 249
NNSY message properties file 289
NNSY rules
check consistency 252
consistency check 266, 284
export 254, 267
import 259, 284
reload 249
sample conditions 324
sample subscriptions 325
NNSY version identification 255
node
add plug-in to Control Center 360
AggregateControl 381
AggregateReply 381
AggregateRequest 382
Check 398
Compute 180, 182, 196, 218, 222
create JAR file 359
Database 333
define attributes
in source code 356
define terminals
in source code 356
definition of a plug-in node class 372
duplicate name 101
ESQL 14
FlowOrder 388
identifier 360, 374
input nodes 352
Label 327
label of node 360, 374
MQInput 179, 196, 218
messages in NEON domain 293, 313
messages in NEONMSG domain 298
MQReply 396
NEONFormatter
definition 246
example 294, 308, 314, 318
NEONMap
definition 247
example 304
NEONMap versus NEONTransform 296
NEONRules
definition 246
example 308, 314, 322
NEONRulesEvaluation
definition 247
example 327, 343
NEONTransform 247
example 306
output node 352
plug-in node 352
primitive nodes 13
property 13
ResetContentDescriptor 317
Trace 223, 387
node development
software requirements 354
node interface 353
O
ODBC
configuration 63, 135, 150
AIX 68
Index
463
Solaris 136
environment variable 68
ini file 136
operational security 39
order
of assignments in ESQL 219, 227
of attributes 218
of elements in output message 197
of message elements 178
of tags of input message 197
of XML elements 218
output
of trace 225
output message
generate 231
generate multiple 231
output node 352
P
parameter file for rules engine 244
equivalent in V2.1.0 348
parser 18, 167
custom-written 14
NEON 246
NEON and NEONMSG 289
NEON and NEONMSG example 317
NEONMSG 247
parser, built-in 2
partially parsing 173
physical format 18, 184, 192, 208
add 168
after import 118
during import 100, 124
changing 181
identifier 168169, 179
name 168169
properties 169170
specifying during import 203
ping channel 72
ping database listener 135
point to point 3
port number 46, 72, 79
properties
MQInput node 179
publish/subscribe 3
criteria 10
security 39
464
Q
queue manager
create
AIX 70
Solaris 133
Windows 45, 62, 78, 155
definition requirements 45
requirements for WMQI components 40
start 70
R
Redbooks Web site 450
Contact us xii
refresh
rules and formats 249
TCP/IP configuration
AIX 72
registry security 39, 46, 62, 79, 94
repository 56
request/reply 380
required maintenance 87, 107
ResetContentDescriptor node 317
resource
saved states 13
resource control 13
resource coordinator 139
resource manager 23, 139
roles 1112
rules engine 248
parameter file 244
simulation 343
run-time 18
S
SCADA 3
script for defining MQSeries objects 57
security 4, 6, 10, 26
MQSeries 39
roles based 12, 39
Windows NT 12
select
individual fields 181
software installation
AIX 256
HP-UX 256
Solaris 256
Windows 256
Solaris administration 134

start
broker 360, 374
Configuration Manager 125
database listener 135
message broker 125, 141
queue manager 70, 133
trace 224
tracing 224
stop
broker 360, 374
message flow 367
subroutine 14, 17
subscription
in NNSY 311
SupportPac
Business Scenarios 38
features 41
message display utility 304
SWIFT message structure 291
syslog
Solaris 137
system queues 7, 910
for a broker 7
for a User Name Server 10
T
TCP/IP port number 46, 72, 79
topology
add broker 42, 59, 73, 84, 99
delete broker 109
deploy 42, 60, 74, 84, 99
full versus delta deploy 109
trace
activating 224
analyzing output 226
example output 225
format log 225
format output 225
read log 225
to a file 224
Trace node 224, 387
transaction 23
transaction coordination 23, 139
transaction mode 223, 384
triggering
AIX 71
Solaris 138
Windows 52, 158
type
link to a physical format 177
type composition 191
type content 173, 191
U
uninstall
AIX 112, 256, 268
delete broker 109
HP-UX 256
Solaris 256
Windows 117, 123, 256, 268
user group 12, 39, 67
user ID authorization 4, 6
user profile 69, 134, 140
user roles 11
user trace file 224
UUID
ESQL function 24
message set 32
V
validation of imported MRM definitions 211
variables in ESQL 233
version of NNSY utilities 255
W
WebSphere MQ family overview 3
components 4
extending functionality 2, 14
folder name 29
installation 134, 153
NNSY support 257
moving components 30
positioning 3
Windows administration 145, 154
Windows NT registry 39, 46
wire formats 21
See also physical formats
workspace
add message set 100
import message flow 100
Index
465
X
XML
attributes 206, 216
MRM versus XML 233
change XML name 215216
import a DTD 206
message 50
names 216
physical format 208
processing blanks and carriage returns 384
466
Deployment and Migration
(1.0 spine)
0.875<->1.498
460 <-> 788 pages
Back cover
Deployment and
Migration
Migration
possibilities for
brokers and
NEON-based
message flows
Multi-broker and
multi-platform
configuration
scenarios
New features,
including enhanced
MRM and Java nodes
The release of WebSphere MQ Integrator Version 2.1 has introduced

quite a few changes; these changes make it more appealing for
message flow developers and message set designers to migrate to
the new version so that they can exploit this functionality.
After a brief overview of the product, we look at several migration
issues that might arise; we also describe the migration process for
MQSeries Integrator Version 2.0.1 and Version 2.0.2 on Windows NT
and AIX platforms. The migrated environment is further extended
with a broker running on Solaris using Oracle, and a broker running
on Windows using SQL Server. Besides the migration of brokers and
the Configuration Manager, this redbook also investigates the
migration of message flows that use NEON functionality. We discuss
several scenarios explaining how to take advantage of the tighter
integration between NEON-based functionality and base WebSphere
MQ Integrator functionality.
Finally, we introduce the major new features of this release. The
extended functionality of the Message Repository Manager and the
extended support for XML messages is explored using several
examples. The support for Java-based plug-in nodes and input
nodes is demonstrated by developing a simple input node that reads
files from a directory to initiate a message flow. The new aggregate
nodes also demonstrate how to combine several messages of
several formats into a single XML message.
INTERNATIONAL
TECHNICAL
SUPPORT
ORGANIZATION
BUILDING TECHNICAL
INFORMATION BASED ON
PRACTICAL EXPERIENCE
IBM Redbooks are developed by
the IBM International Technical
Support Organization. Experts
from IBM, Customers and
Partners from around the world
create timely technical
information based on realistic
scenarios. Specific
recommendations are provided
to help you implement IT
solutions more effectively in
your environment.
For more information:

ibm.com/redbooks
SG24-6509-00
ISBN 0738424293

Websphere MQ Integrator

Caricato da

Informazioni sul documento

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Websphere MQ Integrator

Caricato da

Copyright:

Formati disponibili

Front cover

Geert Van de Putte

International Technical Support Organization

First Edition (April 2002)

Chapter 3. Migration of an MQSeries Integrator environment . . . . . . . . . 37

Copyright IBM Corp. 2002

3.8.1 Upgrade on AIX1. . . . . . . . . . . . . . . . . . .

Chapter 4. Deploying a broker on Sun Solaris using Oracle 8i . . . . . . . 131