MQSeries Integrator
`
`Programming Guide
`Version 2.0
`
`IBM
`
`SC34-5603-00
`
`
`
`HP_1024_0001
`
`

`
`
`
`HP_1024_0002
`
`HP_1024_0002
`
`

`
`MQSeries Integrator
`
`Programming Guide
`Version 2.0
`
`IBM
`
`SC34-5603-00
`
`
`
`HP_1024_0003
`
`

`
`
`
`
`
` Note!
`
`Before using this information and the product it supports, be sure to read the general information under Appendix C, “Notices”
`on page 189.
`
`First edition (April 2000)
`
`This edition applies to IBM MQSeries Integrator Version 2.0, and to any subsequent releases and modifications until otherwise
`indicated in new editions.
`
` Copyright International Business Machines Corporation 2000. All rights reserved.
`US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
`
`HP_1024_0004
`
`

`
`
`
`
` Contents
`
`Contents
`
`About this book
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Who this book is for .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`What you need to know to understand this book .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Terms used in this book
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Where to find more information .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`MQSeries Integrator publications
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`MQSeries publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
`MQSeries information available on the Internet
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`. vii
`. vii
`. vii
`. vii
` viii
` viii
`viii
`. ix
`
`Part 1. Application programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
`
`Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
`Chapter 1.
`Overview of MQSeries Integrator
`. 3
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`Chapter 2. Writing application programs .
`. 7
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`. 7
`Sending and receiving messages .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Point-to-point messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
`
`Chapter 3. Writing publish/subscribe applications .
` 11
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Publish/subscribe messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
` . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
`The publisher
`The subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
` 20
`Flow of publish/subscribe messages .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`The broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
`Sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
` 27
`Using the AMI in publish/subscribe applications
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`Chapter 4. The MQRFH2 rules and formatting header .
` 29
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`MQRFH2 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
`Message service folders .
` 36
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`Chapter 5. Publish/subscribe command messages .
` 39
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Delete Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
`Deregister Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
`Publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
`Register Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
`Request Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
`Broker Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
`Message descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
`Reason codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
`
`Part 2. Programming a plug-in node or parser
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. 61
`
`Implementing a plug-in node or parser .
`Chapter 6.
` 63
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
` 66
`Implementing a message processing node
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Implementing a message parser
` 87
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Accessing the message content
` 89
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`General development considerations .
` 95
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`
` Copyright IBM Corp. 2000
`
`
`
`iii
`
`HP_1024_0005
`
`

`
`
`
`
`
`.
`.
`
` 97
` 98
`
`. 103
`. 104
`. 105
`. 107
`. 108
`. 112
`
`. 135
`. 136
`. 137
`. 139
`. 140
`. 146
`
`. 159
`
`Using Windows NT event logging from a plug-in .
`Errors and exception handling .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`.
`.
`
`.
`.
`
`.
`.
`
`.
`.
`
`Chapter 7. Node implementation and utility functions
`Node implementation function overview .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Node utility function overview .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Exception handling and logging overview .
`.
`.
`.
`.
`.
`.
`.
`.
`Node implementation function interface
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Node utility function interface
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`
`.
`.
`.
`.
`.
`
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`Chapter 8. Parser implementation and utility functions .
`Parser implementation function overview .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Parser utility function overview .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Exception handling and logging overview .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Parser implementation function interface .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Parser utility function interface .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`Chapter 9. Exception handling and logging .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`
`.
`
`Contents
`
`Part 3. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
`
`Appendix A. Using filters in content-based routing .
`. 165
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`Field references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
`
`.
`
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`Appendix B. Plug-in node sample code .
`.
`.
`.
`.
`.
`.
`.
`.
`The sample property editor TraceSettingPropertyEditor.java
`The sample customizer files .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`. 171
`. 171
`. 173
`
`Appendix C. Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
`Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
`
`Part 4. Glossary and index .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. 193
`
`Glossary of terms and abbreviations .
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`.
`
`. 195
`
`Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
`
`iv MQSeries Integrator Version 2.0 Programming Guide
`
`
`
`HP_1024_0006
`
`

`
`1. Communication between publisher, subscriber, and broker
`2. Publish/subscribe without retained publications
`.
`.
`.
`.
`.
`.
`3. Using retained publications
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`4. Publish on request only
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`5. The results service application .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`6. A sample plug-in XML interface definition file
`.
`.
`.
`.
`.
`.
`7. Sample plug-in WDP file
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`8. Plug-in node icons
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`9. Sample plug-in node help file
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`10. Sample plug-in node properties file
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`11. PropertyEditor sample code
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`12. Customizer sample code
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`13. Tree representation of a message .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`14. Syntax element tree
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`15. First generation of syntax elements
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`16. Tree representation of an XML message .
`.
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`Tables
`
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`
` 12
` 21
` 21
` 22
` 25
` 70
` 76
` 78
` 79
` 81
` 82
` 84
` 90
` 91
` 91
` 93
`
`
`
`
` Figures
`
`+
`+
`+
`+
`+
`+
`+
`
` Tables
`
`1. Fields in MQRFH2 .
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`.
`2.
`Initial values of fields in MQRFH2 .
`.
`.
`.
`3. Utility function return codes and values .
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`.
`
`.
`.
`
` 29
` 34
` 100
`
`
`
`Contents v
`
`HP_1024_0007
`
`

`
`
`
`
`
`Tables
`
`vi MQSeries Integrator Version 2.0 Programming Guide
`
`
`
`HP_1024_0008
`
`

`
`
`
`
`About this book
`
`About this book
`
`This book explains how to write application programs that communicate with
`MQSeries Integrator Version 2.0, or to write plug-in nodes and parsers that can be
`installed in this product.
`
`Part 1, “Application programming” on page 1 starts with a brief overview of the
`concepts and capabilities of MQSeries Integrator Version 2.0.
`It then describes
`how to write application programs using both point-to-point and publish/subscribe
`communication models. Full details of the publish/subscribe command messages,
`and the MQRFH2 message header that is used to send them, are also provided.
`
`Part 2, “Programming a plug-in node or parser” on page 61 describes how to write
`plug-in message processing nodes and parsers to enhance the capabilities of
`MQSeries Integrator. Full details of the functions you need to write, and the utility
`functions provided to assist you, are given in this part of the book.
`
`A glossary is also provided.
`
`+
`+
`
`Changes made to this book after it was included on the MQSeries Integrator
`Version 2.0 CD are marked with the + character.
`
`Who this book is for
`This book is for programmers who need to write application programs that will
`communicate with MQSeries Integrator Version 2.0, or to write plug-in nodes and
`parsers that will be installed in this product.
`
`What you need to know to understand this book
`To understand this book, you need to have some understanding of MQSeries,
`including the use of the Message Queue Interface (or the Application Messaging
`Interface).
`
`You are recommended to read the MQSeries Integrator Introduction and Planning
`book before starting to write application programs. It contains information about the
`design of applications that communicate with MQSeries Integrator.
`
`Terms used in this book
`All references to MQSeries Integrator are to MQSeries Integrator Version 2.0
`unless otherwise stated.
`
`The book uses the following shortened names:
`(cid:1) MQSeries: a general term for IBM MQSeries Messaging products.
`the MQSeries Publish/Subscribe SupportPac
`(cid:1) MQSeries Publish/Subscribe:
`available on the Internet for several MQSeries server operating systems (the
`Internet URL is given in “MQSeries information available on the Internet” on
`page ix).
`
` Copyright IBM Corp. 2000
`
`
`
`vii
`
`HP_1024_0009
`
`

`
`
`
`
`
`MQSeries publications
`
`Where to find more information
`Becoming familiar with the MQSeries Integrator library will help you accomplish
`MQSeries Integrator tasks quickly. The library covers planning, installation,
`administration, and client application tasks.
`
`The library also contains references to complementary product libraries, including
`the MQSeries Family library.
`
`MQSeries Integrator publications
`The following books make up the MQSeries Integrator Version 2.0 library:
`(cid:1) IBM MQSeries Integrator Version 2.0 Introduction and Planning, GC34-5599
`(cid:1) IBM MQSeries Integrator Version 2.0 Installation Guide, GC34-5600
`(cid:1) IBM MQSeries Integrator Version 2.0 Messages, GC34-5601
`(cid:1) IBM MQSeries Integrator Version 2.0 Using the Control Center, SC34-5602
`(cid:1) IBM MQSeries Integrator Version 2.0 Programming Guide, SC34-5603 (this
`book)
`(cid:1) IBM MQSeries Integrator Version 2.0 Administration Guide, SC34-5792
`
`All books in the MQSeries Integrator Version 2.0 library are available in softcopy, in
`Portable Document Format (PDF).
`
`You can read these books using the Adobe Acrobat Reader, or in a Web browser
`(with Acrobat Reader as a plug-in). You can also print your own copies of these
`books.
`
`You need Version 3 or later of Acrobat Reader. You can download a free copy of it
`from the Adobe Web site:
`http://www.adobe.com
`
`The MQSeries Integrator Version 2.0 books are also available in hardcopy.
`
` MQSeries publications
`This section describes MQSeries publications that are referred to in this book.
`They are available in hardcopy, HTML, and PDF formats, except where noted.
`
`MQSeries Application Programming Guide
`The MQSeries Application Programming Guide, SC33-0807, provides guidance
`information for users of the message queue interface (MQI). It describes how to
`design, write, and build an MQSeries application.
`It also includes full descriptions
`of the sample programs supplied with MQSeries.
`
`MQSeries Application Programming Reference
`The MQSeries Application Programming Reference, SC33-1673, provides
`comprehensive reference information for users of the MQI.
`It includes: data-type
`descriptions; MQI call syntax; attributes of MQSeries objects; return codes;
`constants; and code-page conversion tables.
`
`MQSeries Application Messaging Interface
`The MQSeries Application Messaging Interface book, SC34-5604, describes the
`MQSeries Application Messaging Interface SupportPac. This is a simple interface
`
`viii MQSeries Integrator Version 2.0 Programming Guide
`
`
`
`HP_1024_0010
`
`

`
`
`
`
`that application programmers can use without needing to understand all the options
`available in the MQI. The options that are required in a particular installation are
`defined by a system administrator, using services and policies.
`
`This book is available in PDF format only.
`
`MQSeries Publish/Subscribe User’s Guide
`The MQSeries Publish/Subscribe User’s Guide, GC34-5269, provides
`comprehensive information for users of the MQSeries Publish/Subscribe
`SupportPac.
`It includes: installation; system design; writing applications; and
`managing the publish/subscribe broker.
`
`This book is available in PDF format only.
`
`For a complete list of MQSeries product publications, refer to the information on the
`MQSeries web site.
`
`MQSeries information available on the Internet
`The MQSeries Business Solution, of which MQSeries Integrator is a part, has a
`Web site at:
`http://www.ibm.com/software/ts/mqseries
`
`By following links from this web site you can:
`(cid:1) Obtain the latest information about all MQSeries family products.
`(cid:1) Access all the books for the MQSeries family products.
`(cid:1) Down-load MQSeries SupportPacs.
`
`You might be interested in the MQSeries Integrator problem determination Q&A
`SupportPac (MHI1) that you can access from:
` http://www.ibm.com/software/mqseries/txppacs/
`
`
`
`About this book
`
`ix
`
`HP_1024_0011
`
`

`
`
`
`
`
`x MQSeries Integrator Version 2.0 Programming Guide
`X MQSeries Integrator Version 2.0 Programming Guide
`
`
`
`HP_1024_0012
`
`HP_1024_0012
`
`

`
`
`
`
` Part 1. Application programming
`
`This part contains:
`(cid:1) Chapter 1, “Introduction” on page 3
`(cid:1) Chapter 2, “Writing application programs” on page 7
`(cid:1) Chapter 3, “Writing publish/subscribe applications” on page 11
`(cid:1) Chapter 4, “The MQRFH2 rules and formatting header” on page 29
`(cid:1) Chapter 5, “Publish/subscribe command messages” on page 39
`
` Copyright IBM Corp. 2000
`
`
`
`1
`
`HP_1024_0013
`
`

`
`
`
`
`
`2 MQSeries Integrator Version 2.0 Programming Guide
`2 MQSeries Integrator Version 2.0 Programming Guide
`
`
`
`HP_1024_0014
`
`HP_1024_0014
`
`

`
`
`
`
`MQSeries Integrator overview
`
` Chapter 1.
`
`Introduction
`
`To build a complete MQSeries Integrator Version 2.0 application, you need to
`consider the following activities:
`(cid:1) Define the information space and model.
`(cid:1) Build the business message flows.
`(cid:1) Develop or modify applications that feed messages into the message flows,
`and consume the messages they produce.
`
`The first two activities are described in the MQSeries Integrator Introduction and
`Planning book and MQSeries Integrator Using the Control Center respectively.
`
`This book concentrates on the third activity, how to develop applications that work
`with MQSeries Integrator Version 2.0. To help you understand what can be done
`with the product, this chapter contains an overview of its functionality.
`
`Overview of MQSeries Integrator
`MQSeries Integrator Version 2.0 is IBM’s message broker product, addressing the
`needs of business and application integration through management of information
`flow. It provides services that allow you to:
`(cid:1) Route a message to several destinations, using rules that act on the contents
`of one or more of the fields in the message or message header.
`(cid:1) Transform a message, so that applications using different formats can
`exchange messages in their own formats.
`(cid:1) Store and retrieve a message, or part of a message, in a database.
`(cid:1) Modify the contents of a message (for example, by adding data extracted from
`a database).
`(cid:1) Publish a message to make it available to other applications. Other
`applications can choose to receive publications that relate to specific topics, or
`that have specific content, or both.
`(cid:1) Extend the function of MQSeries Integrator Version 1.
`
`These services are based on the messaging transport layer provided by the
`MQSeries products.
`
` Message brokers
`A message broker, usually referred to simply as a broker, is a set of execution
`environments hosting services you create to handle your message traffic.
`
`You can install and configure any number of brokers. Together, these make up a
`broker domain. The broker domain is the set of brokers you can administer as a
`single entity, using the MQSeries Integrator Version 2.0 Control Center.
`
`Brokers are connected together to provide communication throughout your broker
`domain, as required. This is needed for publish/subscribe applications (see
`“Applications” on page 5). Communications in the broker domain are provided by
`MQSeries.
`
` Copyright IBM Corp. 2000
`
`
`
`3
`
`HP_1024_0015
`
`

`
`
`
`
`
`MQSeries Integrator overview
`
` Message flows
`
`When you design your broker domain, you decide what processing must be done
`on the messages flowing through the brokers. You define this work as a set of
`actions executed between receipt of the message by the broker, and delivery of the
`message to the target applications.
`
`Each action, or subset of actions, is implemented as a message processing node,
`and these are grouped together in a sequence to form a message flow. You create
`message flows using the MQSeries Integrator Control Center (see “The Control
`Center” on page 5).
`
`Message flows can range from the very simple, performing just one action on a
`message, to the complex, providing a number of actions on the message to
`transform its format and content. A message flow can process one message in
`several ways to deliver a number of output messages, perhaps with different format
`and content, to a number of target applications.
`
`The message flows you create receive messages at MQInput nodes. Every input
`node represents an MQSeries queue, and every message flow must have at least
`one input node.
`
`Message flows usually complete their activity by sending one or more messages to
`one or more recipients from MQOutput nodes that represent MQSeries queues, or
`from Publication nodes that redistribute the message to interested subscribers
`using MQSeries queues.
`
`Other message flows might simply store the message in a database for later
`processing, and not use an output node at all.
`
`The other nodes between input and output provide the actions you want taken
`against the messages. MQSeries Integrator supplies a number of predefined
`message processing nodes.
`In addition to the input and output nodes already
`mentioned, their functions include filter (on message data content) and compute (for
`example, add data from a database).
`
`You can create new nodes, using a system programming interface supplied by
`MQSeries Integrator, to provide other options for message processing. This is
`described in Part 2, “Programming a plug-in node or parser” on page 61.
`
`Each message flowing through your system has a specific content and structure,
`referred to as a message template.
`
`Message template information identifies the structure of the data it contains.
`Messages sent to MQSeries Integrator can be of the following types:
`(cid:1) MQSeries messages, with an MQSeries message descriptor (MQMD) and data;
`this type of message does not have to be predefined but if the data is not one
`of the defined types, MQSeries Integrator will not be able to distinguish
`individual fields
`(cid:1) Message repository manager (MRM) messages (defined in the MQSeries
`Integrator Control Center)
`
` Messages
`
`4 MQSeries Integrator Version 2.0 Programming Guide
`
`
`
`HP_1024_0016
`
`

`
`
`
`
`MQSeries Integrator overview
`
`(cid:1) MQSeries Integrator Version 1 messages (defined in the MQSeries Integrator
`Version 1 user interface)
`(cid:1) XML (Extensible Markup Language) messages (which are self-defining)
` (cid:1) User-defined messages
`
`Message template information for predefined messages is usually included in the
`message header, so the message flows recognize the messages when they receive
`them. Other messages might not use the expected header, but you can set up your
`message flow input nodes to indicate how the messages will be processed.
`
`The message bit-stream is decoded by message parsers. MQSeries Integrator
`supplies several message parsers ready for use on known message templates and
`message headers.
`
`You can create new parsers, using a system programming interface supplied by
`MQSeries Integrator, if you need to process other types of message. This is
`described in Part 2, “Programming a plug-in node or parser” on page 61.
`
`The Control Center
`The functions and facilities of MQSeries Integrator are controlled using a graphical
`interface known as the Control Center. The Control Center comes with
`comprehensive on-line help, and is described in MQSeries Integrator Using the
`Control Center.
`
` Applications
`
`You can use the Control Center to:
`(cid:1) Define your broker domain
`(cid:1) Work with message flows
`(cid:1) Organize your MRM messages
`(cid:1) Control your publish/subscribe network
`(cid:1) Manage your broker domain
`
`The Control Center allows you to restrict access and authority to the functions it
`provides, so you can control who can do what within the broker domain.
`
`Applications using messages to send or receive data can communicate in several
`ways. Applications written to the point-to-point model transfer information from one
`sender to one receiver. Publish/subscribe applications, on the other hand, transfer
`information from one or more sender to one or more receivers, with a third party
`acting as the intermediary so that the information requirements of the receiver are
`matched against the information that the sender provides.
`
`Today, most MQSeries applications are using point-to-point communications.
`These applications might be using a one-way send-and-forget (or datagram) model,
`or a request/reply (client/server) model. Such messages can be sent to a message
`flow you have established in the broker, to carry out the required processing on the
`message before sending it on to the receiving application.
`
`Brokers support a second type of communication model known as
`publish/subscribe. In this model, some applications (publishers) provide information,
`and others (subscribers) consume that information. You can also have applications
`that are both publishers and subscribers.
`
`
`
`Chapter 1.
`
`Introduction 5
`
`HP_1024_0017
`
`

`
`
`
`
`
`MQSeries Integrator overview
`
`Publishers create messages and send them to one or more message flows at a
`local broker that support publish/subscribe. Each message has an associated topic
`that categorizes the information in the message. Subscribers register subscriptions
`with their local broker, specifying the types of publication they are interested in
`(determined, for example, by the topic and the contents of the message). When a
`broker receives a publication that matches a subscription that has been registered,
`it sends that publication to the subscriber. Brokers exchange subscriptions and
`publications with each other, so that subscribers can receive information published
`at any broker in the domain.
`
`New and existing applications can take advantage of the broker functions through
`the MQSeries Message Queue Interface (MQI), or the MQSeries Application
`Messaging Interface (AMI). Both interfaces support point-to-point and
`publish/subscribe programming models. You can use the MQI to send messages
`that access broker functions. The AMI provides higher levels of function that are
`designed to simplify the messaging process, particularly for the publish/subscribe
`model.
`
`If you have existing applications written to these interfaces, it should be possible, in
`many cases, to configure your message broker environment in such a way that the
`applications will run unchanged.
`
`You can find information about the design of new applications, and the reuse of
`existing applications in the MQSeries Integrator Introduction and Planning book.
`
`The remaining chapters in Part 1 of this book tell you how to write application
`programs that communicate with MQSeries Integrator Version 2.0.
`
`6 MQSeries Integrator Version 2.0 Programming Guide
`
`
`
`HP_1024_0018
`
`

`
`
`
`
`Sending and receiving messages
`
`Chapter 2. Writing application programs
`
`Applications communicate with MQSeries Integrator by sending messages to the
`broker, or receiving messages from the broker, using MQSeries message queues.
`Before writing your application program, you need to decide on the following:
`(cid:1) The structure and format of the messages
`(cid:1) The queues used for sending and receiving messages
`(cid:1) The communication model (point-to-point, publish/subscribe, or both)
`(cid:1) The programming interface (Message Queue Interface or Application
`Messaging Interface)
`(cid:1) Other features (transactional processing, message ordering, message
`persistence)
`
`All these aspects of the application design are covered in detail in the MQSeries
`Integrator Introduction and Planning Guide.
`
`Some of the information in that book is summarized in this chapter, together with
`the information you need when writing programs to implement your design.
`
`See “Sending and receiving messages” for information relevant to all applications.
`
`See “Point-to-point messaging” on page 9 for specific information about
`point-to-point applications.
`
`Go to Chapter 3, “Writing publish/subscribe applications” on page 11 for more
`information about publish/subscribe applications.
`
`Sending and receiving messages
`In both communication models (point-to-point and publish/subscribe) messages are
`sent to, and received from, an MQSeries Integrator broker using normal MQSeries
`message queues. Information needed by the broker is (optionally) encoded in an
`MQRFH2 rules and formatting header. This header is usually placed after the
`normal MQSeries message descriptor (MQMD), and before the body of the
`message.
`
`You need to construct a message according to your chosen message template,
`including the header (if used), and send it to an input queue at the broker. This
`queue has to be set up by a system administrator, as an attribute of the input node
`of the message flow that will process your message (see MQSeries Integrator
`Using the Control Center).
`
`If you are writing an application to receive a message from the broker, the queue
`that it arrives on is also set up by the system administrator (as an attribute of the
`output node of the message flow). In the case of publish/subscribe applications,
`you specify in the application which queue you want publications to be sent to.
`
`You can use the MQSeries Message Queue Interface (MQI) or the MQSeries
`Application Messaging Interface (AMI) to send and receive these messages.
`
` Copyright IBM Corp. 2000
`
`
`
`7
`
`HP_1024_0019
`
`

`
`
`
`
`
`Sending and receiving messages
`
` Message headers
`MQSeries Integrator messages can have headers of the following types:
` (cid:1) MQRFH2
` (cid:1) MQRFH
`(cid:1) With no MQRFH2 or MQRFH header
`
` MQRFH2
`The MQRFH2 header is based on the MQRFH header, but it allows Unicode strings
`to be transported without translation, and it can carry numeric datatypes. New
`applications should use the MQRFH2 header so that they have access to all the
`functionality in MQSeries Integrator Version 2.0.
`
`Following the fixed portion of the MQRFH2 header is a number of NameValueLength
`and NameValueData pairs. Each one of these contains one folder, which holds a
`sequence of properties encoded as name/value elements in XML (Extensible
`Markup Language: see the MQSeries Integrator Introduction and Planning Guide
`for more details). A <psc> folder contains publish/subscribe commands. An <mcd>
`folder contains a description of the message contents. This is used by MQSeries
`Integrator to decide which message parser to invoke if content-based operations
`are carried out in the message flow.
`
`Full details of the MQRFH2 header and its contents are given in Chapter 4, “The
`MQRFH2 rules and formatting header” on page 29.
`
`MQRFH or no header
`Existing MQSeries Integrator Version 1 and MQSeries Publish/Subscribe
`applications using the MQRFH header are supported by MQSeries Integrator
`Version 2.0. For full details refer to MQSeries Integrator Introduction and Planning.
`
`MQSeries messages that have no MQRFH2 or MQRFH header are also supported.
`The default message properties on a message flow can provide defaults for values
`normally carried in a header. This allows messages to be parsed and published.
`
`The output message is unchanged if this function is used. See the information on
`MQInput node in MQSeries Integrator Using the Control Center.
`
`Using the Message Queue Interface
`The MQSeries Message Queue Interface (MQI) that is used to put (MQPUT) and
`get (MQGET) messages to and from queues is described in the MQSeries
`Application Programming Guide and the MQSeries Application Programming
`Reference book.
`
`If you are using the MQI in your application programs, Chapter 4, “The MQRFH2
`rules and formatting header” on page 29 describes the MQRFH2 header in detail,
`and the structure of the folders that are contained within it. Chapter 5,
`“Publish/subscribe command messages” on page 39 details the command
`messages that are sent to the broker, using the MQRFH2 header, in
`publish/subscribe applications.
`
`8 MQSeries Integrator Version 2.0 Programming Guide
`
`
`
`HP_1024_0020
`
`

`
`
`
`
`Point-to-point messaging
`
`Using the Application Messaging Interface
`For many applications it is not necessary to understand the details of the MQRFH2
`header or the MQI. The MQSeries Application Messaging Interface (AMI) has been
`developed to hide their complexities from an application programmer by containing
`them in policies and services that are set up by a systems administrator. MQSeries
`and MQSeries Integrator functionality, including publish/subscribe, can be accessed
`through the AMI using the C, C++, or Java programming languages.
`
` Restriction
`
`The MQSeries Application Messaging Interface is not available on all platforms,
`and the current version does not support the MQRFH2 header. For
`publish/subscribe applications, the AMI uses the MQRFH header as described
`in the MQSeries Publish/Subscribe User’s Guide. Note that this does not
`support all of the publish/subscribe functionality described in Chapter 3, “Writing
`publish/subscribe applications” on page 11.
`
`The latest information is available on the Internet (see “MQSeries information
`available on the Internet” on page ix).
`
`If you are using the AMI, read the remainder of this chapter and then refer to the
`MQSeries Application Messaging Interface book. You will need to check with your
`system administrator to find out what policies and services have been defined for
`your application. If you are using the publish/subscribe capability of MQSeries
`Integrator, you should also read Chapter 3, “Writing publish/subscribe applications”
`on page 11.
`
` Point-to-point messaging
`MQSeries Integrator point-to-point applications involve these components:
`
`Sender
`
`Broker
`
`An application that sends a message
`
`The message broker that processes the message