webMethods WebSphere MQ Adapter Installation and

Users Guide
Version 6.5
J anuary 2012
Title Page
This document applies to webMethods WebSphere MQ Adapter Version 6.5 and to all subsequent releases.
Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions.
Copyright 2001-2012 Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, United States of America, and/or
their licensors.
The name Software AG, webMethods and all Software AG product names are either trademarks or registered trademarks of Software AG
and/or Software AG USA, Inc. and/or its Subsidiaries and/or their licensors. Other company and product names mentioned herein may be
trademarks of their respective owners.
Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is located at
http://documentation.softwareag.com/legal/.
Use of this software is subject to adherence to Software AG's licensing conditions and terms. These terms are part of the product
documentation, located at http://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s).
This software may include portions of third-party products. For third-party copyright notices and license terms, please refer to License
Texts, Copyright Notices and Disclaimers of Third-Party Products. This document is part of the product documentation, located at
http://documentation.softwareag.com/legal/ and/or in the root installation directory of the licensed product(s).
Document ID: ADAPTER-WEBSPHEREMQ-IUG-65-20131117
Copyright
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 3
Table of Contents
About this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Deprecation of webMethods Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Document Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Documentation Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Online Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1. About the WebSphere MQ Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Overview of the WebSphereMQ Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Overview of Queuing Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Messages in a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Messages in a Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Undeliverable Message Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Architecture and Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Setting Permissions in WebSphere MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Transaction Management of WebSphereMQ Adapter Connections . . . . . . . . . . . . . . 24
Connection Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Runtime Behavior of Connection Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Built-In Services For Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Put Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Runtime Processing for Put Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Get Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Runtime Processing for Get Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Peek Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Runtime Processing for Peek Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Request/Reply Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Runtime Processing for Request/Reply Services . . . . . . . . . . . . . . . . . . . . . . . . . 35
Inquire Queue Manager/Queue Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Runtime Processing for Inquire Queue Manager/Queue Services . . . . . . . . . . . . 37
PCF Command Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Runtime Processing for PCF Command Services . . . . . . . . . . . . . . . . . . . . . . . . . 40
Associating Connections and Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Specify a Default Connection at Design Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Use Developer or Designer to Supply a Value for overrideConnection at
Design Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

4 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Programmatically Supply a Value for overrideConnection at Run Time . . . . . . . . . . . . 42
Programmatically Supply a Value for $connectionName at Run Time . . . . . . . . . . . . . 43
Programmatically Change the Connection Associated with an Adapter Service at
Design Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Adapter Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Asynchronous Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Synchronous Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Listener Notification Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Exactly Once Notification Feature in a Clustered Environment . . . . . . . . . . . . . . . . . . 47
Listener Transactionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Transactional Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Non-Transactional Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Runtime Processing of Listeners and Notifications . . . . . . . . . . . . . . . . . . . . . . . . 47
Runtime Processing of Listeners and Asynchronous Listener Notifications . . 47
Runtime Processing of Listeners and Synchronous Listener Notifications . . 49
Using Version Control Systems to Manage Adapter Elements . . . . . . . . . . . . . . . . . . . . . . 50
Infrastructure Data Collector Support for the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Viewing the Adapter's Update Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Controlling Pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
2. Installing, Upgrading, and Uninstalling WebSphere MQ Adapter . . . . . . . . . . . . . . . . . 53
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Installing WebSphereMQ Adapter 6.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Upgrading to WebSphereMQ Adapter 6.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Uninstalling WebSphereMQ Adapter 6.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
3. Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
WebSphereMQ Adapter Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Package Dependency Requirements and Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . 61
Enabling Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Disabling Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Group Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
WebSphereMQ Adapter in a Clustered Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Adapter Service Support in Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
WebSphereMQ Adapter Notification Support in Clusters . . . . . . . . . . . . . . . . . . . . . . 64
Duplicate Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Ordering of Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Clustering Considerations and Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Requirements for Each Integration Server in a Cluster . . . . . . . . . . . . . . . . . . . . . 64
Considerations When Installing WebSphereMQ Adapter Packages . . . . . . . . . . 65
Considerations When Configuring Connections with Connection
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 5

Pooling Enabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Considerations and Requirements for Notifications in a Clustered Environment . 66
Using the Exactly Once Notification Feature in a Clustered Environment . . . . . . . 66
Disabling the Redirection of Administrative Services . . . . . . . . . . . . . . . . . . . . . . . . . . 67
4. Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Before Configuring or Managing Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Configuring WebSphereMQ Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Overriding Connections in a Flow Service at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Dynamically Changing a Service's Connection at Run Time . . . . . . . . . . . . . . . . . . . . . . . . 81
Viewing WebSphereMQ Adapter Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 81
Viewing Connection Parameters Using Integration Server Administrator . . . . . . . . . . 82
Viewing Connection Parameters Using Developer or Designer . . . . . . . . . . . . . . . . . . 82
Editing WebSphereMQ Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Copying WebSphereMQ Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Deleting WebSphereMQ Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Enabling WebSphereMQ Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Disabling WebSphereMQ Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Configuring SSL Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Step 1: Configure the Integration Server Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Step 2: Apply Private and Public Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Applying Private Key to Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Applying Public Key to Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Step 3: Apply Private Key and Certificates for the Adapter Connection . . . . . . . . . . . . 87
Applying Private Key to Adapter Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Applying Public Key to Queue Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Step 4: Configure the Cipher Spec Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
5. Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Before Configuring or Managing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Using Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Configuring Put Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Using Put Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Input Signature Properties for the Put Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Output Signature Properties for the Put Service . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Configuring Get Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Using Get Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Input Signature Properties for the Get Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Output Signature Properties for the Get Service . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Configuring Peek Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Using the Peek Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Input Signature Properties for the Peek Service . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Output Signature Properties for the Peek Service . . . . . . . . . . . . . . . . . . . . . . . . 125

6 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Configuring Request/Reply Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Using the Request/Reply Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Input Signature Properties for the Request/Reply Service . . . . . . . . . . . . . . . . . . . . . . 137
Output Signature Properties for the Request/Reply Service . . . . . . . . . . . . . . . . . . . . . 141
Configuring Inquire Queue Manager/Queue Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Using the Inquire Queue Manager/Queue Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Output Signature Properties for the Inquire Queue Manager/Queue Service . . . . . . . 146
Configuring PCF Command Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Using the PCF Command Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Output Signature Properties for the PCF Command Service . . . . . . . . . . . . . . . . . . . . 149
Throwing Exceptions on Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Enabling the Throw Exception on Failure Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Disabling the Throw Exception on Failure Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Working with Messages in a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Retrieving Inbound Messages in a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Categorizing Outbound Messages as Part of a Group . . . . . . . . . . . . . . . . . . . . . . . . . 152
Working with Messages in a Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Retrieving Inbound Messages in a Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Segmenting Outbound Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Instructing WebSphere MQ to Segment Outbound Messages . . . . . . . . . . . . . . . 154
Segmenting Messages Programmatically With Your Own Code . . . . . . . . . . . . . . 154
Using the Pipeline Editor to View and Set the msgBody . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Testing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Viewing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Editing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Deleting Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Enabling Automatic Data Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Enabling Data Validation for a Single Adapter Service . . . . . . . . . . . . . . . . . . . . . . . . . 158
Enabling Validation for All Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Reloading Adapter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Reloading Adapter Values for a Single Adapter Service . . . . . . . . . . . . . . . . . . . . . . . 159
Reloading Adapter Values for All Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
6. Adapter Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Before you Configure New Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Configuring New Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Single-Queue Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Multi-Queue Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Configuring a New Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Behavior of Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Listeners and Transactional Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Listeners and Non-Transactional Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Testing Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 7

Viewing Listener Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Viewing Listener Parameters Using Integration Server Administrator . . . . . . . . . . 169
Viewing Listener Parameters Using Developer or Designer . . . . . . . . . . . . . . . . . 170
Viewing the Notification Order of a Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Editing Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Updating Listener Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Editing the Notification Order of a Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Copying Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Deleting Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Enabling Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Suspending Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Disabling Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Before you Configure Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Considerations for Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Using Asynchronous and Synchronous Listener Notifications . . . . . . . . . . . . . . . . . . . 177
Configuring Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Configuring an Asynchronous Listener Notification . . . . . . . . . . . . . . . . . . . . . . . . 178
Configuring a Synchronous Listener Notification . . . . . . . . . . . . . . . . . . . . . . . . . 184
Behavior of Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Testing Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Testing Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Viewing Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Editing Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Editing Publishable Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Deleting Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Enabling Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Disabling Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
7. Logging and Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Adapter Logging Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Accessing Adapter Logging Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Changing Adapter Logging Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Adapter Message Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Overriding Adapter Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Adapter Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Adapter Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Adapter Tracing Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Configuring Tracing Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Configuring Tracing Settings Using webMethods Integration Server
Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Archiving Tracing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Clearing Tracing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Refreshing Tracing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

8 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Enabling Tracing When Using WebSphere MQ Version 7 . . . . . . . . . . . . . . . . . . . . . . . . . . 208
A. Built-In Transaction Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Transaction Management Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Transaction Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Implicit and Explicit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Implicit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Explicit Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Built-In Transaction Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
pub.art.transaction:commitTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
pub.art.transaction:rollbackTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
pub.art.transaction:setTransactionTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
pub.art.transaction:startTransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Changing the Integration Server Transaction Timeout Interval . . . . . . . . . . . . . . . . . . . . . . 217
Transaction Error Situations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 9
About this Guide
This guide describes how to configure and use the webMethods WebSphere MQ Adapter
6.5. It contains information for administrators and application developers who want to
exchange data, such as documents, with other systems through an IBM WebSphere MQ
message queue.
To use this guide effectively, you should be familiar with:
WebSphere MQ message queues
Message queuing
The terminology and basic operations of your operating system
The setup and operation of the webMethods Integration Server.
How to perform basic tasks with webMethods Developer or Software AG Designer.
Note: Procedures for creating flow services, adapter notifications, and adapter services
are similar in Developer and Designer.
Deprecation of webMethods Developer
webMethods Developer is deprecated and does not support all the features of
webMethods Integration Server 8.2. Software AG recommends the use of Software AG
Designer for service development.
Document Titles
Some webMethods document titles have changed during product releases. The following
table will help you locate the correct document for a release on the Software AG
Documentation Web site or the Empower Product Support Web site.
Documentation 7.x 8.0
8.0
SP1 8.2
9.0 and
later
Designer Process Development online help
webMethods BPM Process Development Help x x
webMethods Designer BPM Process Development
Help
x x
webMethods Designer Process Development Help x
Designer Service Development online help
About this Guide
10 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
webMethods Service Development Help x x
webMethods Designer Service Development Help x x x
Developer users guide
Developing Integration Solutions: webMethods
Developer Users Guide
x x
webMethods Developer Users Guide x x
Integration Server administration guide
webMethods Integration Server Administrators
Guide
x x x
Administering webMethods Integration Server x x
Integration Server built-in services reference guide
webMethods Integration Server Built-In Services
Reference
x x x x x
Integration Server clustering guide
webMethods Integration Server Clustering Guide x x x x x
Integration Server publish-subscribe developers guide
Publish-Subscribe Developers Guide x x x x x
My webMethods administration guide
Administering My webMethods Server x x x
My webMethods Server Administrators Guide x x
Optimize administration guide
Administering webMethods Optimize x x x
webMethods Optimize Administrators Guide x x
Optimize users guide
webMethods Optimize Users Guide x x x
Optimizing BPM and System Resources with
BAM: webMethods Optimize Users Guide
x x
Process Engine administration guide
Administering webMethods Process Engine x x x x
webMethods Process Engine Users Guide x
Trading Networks administration guide
Documentation 7.x 8.0
8.0
SP1 8.2
9.0 and
later
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 11
About this Guide
webMethods Trading Networks Administrators
Guide
x x x
Building B2B Integrations: webMethods Trading
Networks Administrators Guide
x x
Trading Networks built-in services reference guide
webMethods Trading Networks Built-In Services
Reference
x x x x x
Trading Networks concepts guide
webMethods Trading Networks Administrators
Guide and webMethods Trading Networks Users
Guide
x
Understanding webMethods B2B: webMethods
Trading Networks Concepts Guide
x x
webMethods Trading Networks Concepts Guide x x
Trading Networks users guide
webMethods Trading Networks Users Guide x x x
Managing B2B Integrations: webMethods Trading
Networks Users Guide
x x
webMethods installation guide
Installing webMethods Products and Using the
Software AG Installer
x x
Software AG Installation Guide x
webMethods Installation Guide x x
webMethods logging guide
webMethods Audit Logging Guide x x x
webMethods Audit Guide x x
webMethods upgrade guide
Upgrading webMethods Products x x
webMethods Upgrade Guide x x x
Documentation 7.x 8.0
8.0
SP1 8.2
9.0 and
later
About this Guide
12 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Document Conventions
Documentation Installation
You can download the product documentation using the Software AG Installer. The
documentation is downloaded to a central directory named _documentation in the main
installation directory (SoftwareAG by default).
Online Information
You can find additional information about Software AG products at the locations listed
below.
Convention Description
Bold Identifies elements on a screen.
Narrowfont Identifies storage locations for services on webMethods Integration
Server, using the convention folder.subfolder:service.
UPPERCASE Identifies keyboard keys. Keys you must press simultaneously are
joined with a plus sign (+).
Italic Identifies variables for which you must supply values specific to
your own situation or environment. Identifies new terms the first
time they occur in the text.
Monospace font Identifies text you must type or messages displayed by the system.
{ } Indicates a set of choices from which you must choose one. Type
only the information inside the curly braces. Do not type the { }
symbols.
| Separates two mutually exclusive choices in a syntax line. Type one
of these choices. Do not type the | symbol.
[ ] Indicates one or more options. Type only the information inside the
square brackets. Do not type the [ ] symbols.
... Indicates that you can type multiple options of the same type. Type
only the information. Do not type the ellipsis (...).
If you want to... Go to...
Access the latest version of product
documentation.
Software AG Documentation website
http://documentation.softwareag.com
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 13
About this Guide
Find information about product releases and
tools that you can use to resolve problems.
See the Knowledge Center to:
Read technical articles and papers.
Download fixes and service packs (9.0
SP1 and earlier).
Learn about critical alerts.
See the Products area to:
Download products.
Download certified samples.
Get information about product
availability.
Access older versions of product
documentation.
Submit feature/enhancement requests.
Empower Product Support website
https://empower.softwareag.com
Access additional articles, demos, and
tutorials.
Obtain technical information, useful
resources, and online discussion forums,
moderated by Software AG professionals,
to help you do more with Software AG
technology.
Use the online discussion forums to
exchange best practices and chat with
other experts.
Expand your knowledge about product
documentation, code samples, articles,
online seminars, and tutorials.
Link to external websites that discuss
open standards and many web
technology topics.
See how other customers are streamlining
their operations with technology from
Software AG.
Software AG Developer Community for
webMethods
http://communities.softwareag.com/
If you want to... Go to...
About this Guide
14 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 15
1 About the WebSphere MQ Adapter
Overview of the WebSphereMQ Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Overview of Queuing Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Architecture and Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Setting Permissions in WebSphere MQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Associating Connections and Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Adapter Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Using Version Control Systems to Manage Adapter Elements . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Infrastructure Data Collector Support for the Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Viewing the Adapter's Update Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Controlling Pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
1 About the WebSphereMQ Adapter
16 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Overview of the WebSphere MQ Adapter
WebSphere MQ Adapter enables Integration Server to exchange information with other
systems through an IBM WebSphere MQ message queue. This capability lets you route
documents, or any piece of information, from Integration Server to systems that use
WebSphere MQ message queuing as their information interface.
For example, you might use WebSphere MQ Adapter to extract information from an
XML-based purchase order, repackage it as an order record, and deliver it to a queue for
processing by a back-end enterprise system. Or you might use WebSphere MQ Adapter
to monitor a queue and to issue updates to various systems on your intranet when a
message appears in that queue.
Overview of Queuing Concepts
This section discusses the following topics:
Queuing
Queue manager
Messages
Grouping messages
Segmenting messages
Processing undeliverable messages
Queuing
Queuing is a programming technique in which two programs exchange data
asynchronously, without calling one another directly. Using queuing, two programs
communicate by passing messages to one another via a queue. Conceptually, a queue is
like an "inbox." When one program wants another program to process a piece of
information, it simply puts that information into the other program's queue. On the other
end, the receiving program monitors its designated queue and processes messages that
other programs deposit in it.
Systems that interface with one another through queuing never interact directly; they
only interact with their queues. In fact, a program might not process its queue until
hours, days, or weeks after another program deposits a message in it.
Queue Manager
A queue manager, such as WebSphere MQ Queue Manager, acts as an intermediary
between the programs that want to exchange information. It functions as a server,
controlling the flow of information in and out of a set of queues. Queues reside on the
queue manager and you can associate multiple queues with one queue manager.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 17
1 About the WebSphereMQ Adapter
The programs that want to communicate with one another (whether they are the
suppliers of information or the consumers of information) are the Queue Manager's
clients. Because these programs do not interact directly, they are considered peers of one
another. Under this architecture, one program is not subordinate to, or a client of, the
other.
Note: The Queue Manager does not actively process or distribute the messages it receives.
Its role is to simply accept messages and hold them in the appropriate queue until a client
explicitly requests them.
Messages
A message is a discrete unit of information that one program wants to pass to another.
The following examples are possible message types:
A string containing a purchase order
A binary data structure containing an employee record
A blob containing a graphic image
The Queue Manager does not impose any constraints on the content or format of
messages exchanged via a queue, and neither does WebSphere MQ Adapter.
When a program puts a message into a queue, the client envelops or wraps the message
with control information such as routing information, priority codes, and message type.
The term message can also refer to the entire message structure; that is, the control
information plus the unit of information to be passed. In this context, the unit of
information is usually referred to as the payload, the application data, or the user data.
When this distinction is necessary, this book uses the term payload to refer to the content
of the message.
1 About the WebSphereMQ Adapter
18 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
To use queuing effectively, programs that communicate via a queue must agree on a
common message content and structure. For example, if Program A is designed to pick
up and process cXML-formatted purchase orders from a queue named Orders, programs
that interact with Program A must deliver properly-formatted cXML purchase orders to
the Orders queue. Identifying the content and structure of the payload is a key activity
you must perform when designing a system that exchanges data through WebSphere MQ
Adapter.
Messages in a Group
You can use inbound adapter services and outbound adapter services to work with
messages in a group.
For a logical unit of work, you can retrieve inbound messages in a group and also
categorize outbound messages as part of a group. For detailed instructions on how to
retrieve messages in a group and how to categorize messages as part of a group, see
Working with Messages in a Group on page 151.
Note: Inbound adapter services and messages travel from the WebSphere MQ queue to
Integration Server. The Get service or Peek service is an example of an inbound adapter
service that retrieves a messages from the queue. Outbound adapter services travel from
Integration Server to the WebSphere MQ queue. The Put service is an example of an
outbound adapter service that puts a message onto the queue.
Messages in a Segment
You can use inbound adapter services and outbound adapter services to work with
messages in a segment.
Message segmentation enables you to configure an adapter service that can
accommodate a very large file. You can also segment messages by splitting and routing
them to different destinations. For detailed instructions on how to retrieve inbound
messages in a segment and how to segment outbound messages, see Working with
Messages in a Segment on page 153.
Undeliverable Message Processing
Occasionally, a WebSphere MQ Adapter service may not be able to process a message.
For example, a listener service may receive a message that it cannot process with any of
its notifications. Normal processing dictates that the adapter should roll the message
back onto the queue. However, this causes the message to be placed at the top of the
queue, and the message would be the next one the listener receives. This logic results in
an infinite loop.
WebSphere MQ Adapter version 6.5 services allow the user to specify a dead letter queue
for the processing of undeliverable messages. A WebSphere MQ Adapter dead letter
queue does not have to be the SYSTEM.DEAD.LETTER.QUEUE-it may be any queue on
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 19
1 About the WebSphereMQ Adapter
any queue manager. A service automatically moves any message that it deems
"undeliverable" to the dead letter queue defined for that service and writes an
information message to the server log.
The service uses its Backout Threshold property in determining whether to move the
message to its dead letter queue.
For inbound services (Get, Request/Reply) and listeners, the service will examine the
message's Backout Count immediately after it receives the message. If the Backout
Count equals the service's Backout Threshold property, the service moves the
message to the dead letter queue.
For outbound services (Put, Request/Reply), the Backout Threshold property
specifies the number of times the service will attempt to put the message on the
queue. If the service cannot deliver the message to the queue within the specified
number of attempts, the service moves the message to the dead letter queue.
When a service moves a message to its dead letter queue, it appends a "dead letter
header" to the original message's payload data. This header indicates what time the
message was moved and why it was moved. The header fields of a message on the dead
letter queue do not contain the header fields of the original message.
If no dead letter queue is specified for inbound services or listeners, the service does not
move the message. If no dead letter queue is specified for outbound services, the service
writes the message to the SYSTEM.DEAD.LETTER.QUEUE.
Note: If no dead letter queue is specified for outbound services and if the
watt.MQSeries.ignore.System.Default.DeadLetterQueue property is set to true, then the
failed message is not moved.
If the message cannot be moved to the dead letter queue due to a failure, the service
discards the message and writes an error message to the server log.
The dead letter queue need not reside on the same queue manager as the service's target
queue. However, the dead letter queue's queue manager and the target queue must
reside on the same machine.
Architecture and Components
This diagram illustrates how WebSphere MQ Adapter interfaces with a WebSphere MQ
system using the WebSphere MQ libraries. Following the diagram are descriptions of the
different architectural pieces involved in the integration process.
For a more detailed description of the runtime data flow for the different types of
WebSphere MQ Adapter services, see Adapter Services on page 26.
1 About the WebSphereMQ Adapter
20 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
webMethods Integration Server. WebSphere MQ Adapter is installed and runs on
Integration Server.
WmART Package. The WmART package provides a common framework for
webMethods Product Suite 6.0 and later adapters to use Integration Server
functionality, making Integration Server the runtime environment for WebSphere MQ
Adapter. The WmART package is installed with Integration Server.
WebSphere MQ Adapter. WebSphere MQ Adapter is delivered as a single package called
WmMQAdapter.
WebSphere MQ Adapter provides user interfaces in:
Integration Server Administrator that enable you to configure and manage
adapter connections, listeners, and notifications.
webMethods Developer and Software AG Designer that enable you to configure
and manage adapter services, listeners, and notifications.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 21
1 About the WebSphereMQ Adapter
Adapter Service Templates. Adapter services enable WebSphere MQ Adapter to
implement the WebSphere MQ client libraries to perform operations on WebSphere
MQ queues. WebSphere MQ Adapter provides adapter service templates that enable
you to configure services to put, get, peek, and request/reply messages.
For example, a Get service enables you to retrieve messages from a WebSphere MQ
queue that are then sent to another application such as a purchase order entry system.
The WebSphere MQ Adapter's adapter service templates are available in Developer
and Designer. For a detailed description of adapter services, see Adapter Services
on page 26.
Adapter Connection Templates. Adapter connections enable WebSphere MQ Adapter to
connect to WebSphere MQ systems. You must configure an adapter connection before
you can configure adapter services.
The adapter provides a template for adapter connections in Integration Server
Administrator. For a detailed description of adapter connections, see Adapter
Connections on page 24.
Adapter Listener Template. An adapter listener monitors the queue for messages and
passes the messages to a listener notification. For example, an adapter listener could
listen for specific messages on a queue that contains a Group ID of 24. The adapter
listener monitors the queue for all messages that contain this Group ID, retrieves the
messages from the queue, and then passes them to the adapter listener notification for
further processing.
You must configure adapter listeners before you can configure adapter notifications.
WebSphere MQ Adapter provides adapter listener templates that enable you to
configure listeners, which monitor a queue for messages.
Adapter Notification Template. A notification waits for an adapter listener to pass a
listener notification a message. A listener notification then passes a message to
Integration Server.
WebSphere MQ Adapter provides adapter notification templates that enable you to
configure notifications, which process the message either synchronously or
asynchronously.
WebSphere MQ Libraries. WebSphere MQ Adapter requires WebSphere MQ-supplied
library files.
Queue Manager. The queue manager acts as an intermediary between the programs
that want to exchange information, and it also functions as a server, controlling the
flow of information in and out of a set of queues. WebSphere MQ Adapter requires
that you specify the queue manager name when you configure transactional or non-
transactional connections. For detailed instructions on how to configure connections,
see Configuring WebSphere MQ Adapter Connections on page 70. For more
information about queue managers, see Queue Manager on page 16.
Queue. The queue acts as an "inbox" to receive messages from the adapter services and
to hold messages until other adapter services retrieve them. The WebSphere MQ
Adapter requires that you specify the queue name when you configure transactional
1 About the WebSphereMQ Adapter
22 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
or non-transactional connections. For detailed instructions on how to configure
connections, see Configuring WebSphere MQ Adapter Connections on page 70. For
more information about queues, see Queuing on page 16.
The following diagram illustrates the use of WebSphere MQ Adapter and Integration
Server in a business-process integration.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 23
1 About the WebSphereMQ Adapter
Package Management
WebSphere MQ Adapter is provided as a package called WmMQAdapter, which you
manage like any package on Integration Server.
There are several considerations regarding how you set up and effectively manage your
packages on Integration Server, such as those described in the following list.
Configure user-defined packages for your connections, adapter services, and listener
notifications. For details, see Package Management on page 59.
Understand how package dependencies work so you make the best decisions
regarding how you manage your adapter services and notifications. For details, see
Package Dependency Requirements and Guidelines on page 61.
Control which development groups have access to which adapter services and
notifications. For details, see Group Access Control on page 63.
Understand how clustering, an advanced feature of Integration Server, works to
effectively manage your adapter services and notifications. For details, see
Clustering Considerations and Requirements on page 64.
Setting Permissions in WebSphere MQ
In order to create an adapter connection or run an adapter service that connects to a
WebSphere MQ queue, you must ensure that the following permissions are set for the
user:
Note that even if the above permissions are set, you may receive a "Not Authorized
(2035)" error when trying to find queues when creating or editing an adapter connection.
The error does not prevent you from creating a connection or executing the services. This
error occurs because the PCF command for the Find Queues function requires the user to
have dsp permission over all the queues in the Queue Manager. Because the user authority
of the SYSTEM.AUTH.DATA.QUEUE can only be granted to a user that has
Administrator privilege or is part of the mqm group, a custom user will not be able to
find queues using the Find Queues button.
To do this... Set these WebSphere MQ User Permissions...
Create a new connection connect, inq (Queue Manager)
Run a Put service put, setid (Queue)
setid (QueueManager)
Run a Get Service get, inq (Queue)
Run a Peek service browse, inq (Queue)
1 About the WebSphereMQ Adapter
24 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Adapter Connections
WebSphere MQ Adapter connects to a queue or to multiple queues at run time. You can
configure one or more connections at design time to use in integrations. The number of
connections you configure, and the types of those connections, depend on the number of
queues that you are connecting to and your integration needs.
WebSphere MQ Adapter connections contain parameters that Integration Server uses to
manage connections to the queue. WebSphere MQ Adapter uses these connections to
provide services. You configure connections using Integration Server Administrator. You
must have webMethods administrator privileges to access WebSphere MQ Adapter
administrative screens.
For instructions for configuring and managing WebSphere MQ Adapter connections, see
Adapter Connections on page 69. For information about setting user privileges, see the
Integration Server administration guide for your release. See About this Guide for
specific document titles.
For a list of tasks that you must do before you can create your connections, see Before
Configuring or Managing Adapter Connections on page 70.
Transaction Management of WebSphere MQ Adapter Connections
When you define a connection, the transaction type you choose determines the type of
transaction management that the connection's operations will use. WebSphere MQ
Adapter connections support the following transaction types. For a detailed discussion of
transaction management and WebSphere MQ Adapter, see Transaction Management
Overview on page 212.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 25
1 About the WebSphereMQ Adapter
Connection Pools
Integration Server includes a connection management service that dynamically manages
connections and connection pools based on configuration settings that you specify for the
connection. All adapter services and adapter listeners use connection pooling.
Transaction Type Description
Transactional A transactional connection uses syncpoint processing, which
means that you can group one or more requests into a single
Logical Unit of Work (LUW). You can control these requests
manually (explicit transactions), or you can allow Integration
Server transaction manager control them for you (implicit
transactions).
To control these requests explicitly within a given LUW, you use
the built-in services, described in Built-In Transaction
Management Services on page 211. If you do not use these
built-in services, the Integration Server will manage the requests
automatically (implicitly).
If a transaction uses only a single connection, or multiple
connections that are all from the same connection pool, you do
not need to manage the transaction explicitly. However, if a
transaction uses multiple LOCAL_TRANSACTION transaction
connections from different connection pools, you must manage
the transaction explicitly.
Note: Implicit transactions complete when the flow service that
contains the LUW finishes executing. If you create a looping
operation within your LUW that could potentially involve a
large number of requests, you might want to manage the
transactions explicitly to reduce the possibility that you will
need to roll back a large number of requests because a single
request fails.
Non-Transactional A non-transactional connection is stateless and does not use
syncpoint processing. All services associated with a non-
transactional connection perform a single request as an
autonomous unit of work.
For example, when a flow invokes a Get service associated with
a non-transactional connection, then these services remove each
message from the WebSphere MQ immediately after they
processes the message.
1 About the WebSphereMQ Adapter
26 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
A connection pool is a collection of connections with the same set of attributes.
Integration Server maintains connection pools in memory. Connection pools improve
performance by enabling adapter services to reuse open connections instead of opening
new connections.
Runtime Behavior of Connection Pools
When you enable a connection, Integration Server initializes the connection pool, creating
the number of connection instances you specified in the connection's Minimum Pool Size
field. Whenever an adapter service needs a connection, Integration Server provides a
connection from the pool. If no connections are available in the pool, and the maximum
pool size has not been reached, the server configures one or more new connections
(according to the number specified in Pool Increment Size) and adds them to the connection
pool. If the pool is full (as specified in Maximum Pool Size), the requesting service will wait
for the Integration Server to obtain a connection, up to the length of time specified in the
Block Timeout field, until a connection becomes available. Periodically, Integration Server
inspects the pool and removes inactive connections that have exceeded the expiration
period that you specified in Expire Timeout.
If the connection pool initialization fails (due to a network connection failure or some
other type of exception), you can enable the system to retry the initialization any number
of times, at specified intervals.
For information about configuring connections, see Adapter Connections on page 69.
Built-In Services For Connections
Integration Server provides built-in services that enable you to programmatically control
connections. You can use them to enable and disable a connection, and to return usage
statistics and the current state (Enabled or Disabled) and error status for a connection.
These services are located in the WmART package, in the pub.art.connection folder.
Another built-in service, pub.art.service:setAdapterServiceNodeConnection, enables you to
change the connection associated with an adapter service. For details, see
Programmatically Change the Connection Associated with an Adapter Service at
Design Time on page 43.
For details, see the Integration Server built-in services reference guide for your release.
See About this Guide for specific document titles.
Adapter Services
Adapter services enable you to connect to the adapter's resource and initiate an operation
on the resource from Integration Server.
You call adapter services from flow services or Java services to interact with queues.
WebSphere MQ Adapter services perform messaging services, and Integration Server
uses the adapter connections to execute the adapter services.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 27
1 About the WebSphereMQ Adapter
Adapter services are based on templates provided with WebSphere MQ Adapter. Each
template represents a specific technique for doing work on a resource, such as using the
Put template to deliver a message to a specified queue.
An adapter service template contains all the code necessary for interacting with the
resource but without the data specifications. You provide these specifications when you
configure a new adapter service.
Configuring a new service from an adapter service template is straightforward. Using
Developer or Designer, you assign the service a default adapter connection.
Important! If you are using the adapter with Integration Server 8.0 SP1 or earlier, adapter
services cannot use connections that are also used for adapter listeners.
After you select the connection for the adapter service, you select the adapter service
template and supply the data specifications, including the mapping of data types from
the adapter to or from your adapter resource. You use Developer or Designer to configure
the adapter service. For more information, see the Developer users guide or Designer
Service Development online help for your release. See About this Guide for specific
document titles.
WebSphere MQ Adapter provides the following adapter service templates:
Adapter Service Description For more information...
Put Service Opens a session to a WebSphere MQ
Queue Manager and delivers a
message to a specified queue.
See Configuring Put
Services on page 91.
Get Service Opens a session to a WebSphere MQ
Queue Manager and retrieves a
message from a specified queue.
See Configuring Get
Services on page 105.
Peek Service Opens a session to a WebSphere MQ
Queue Manager and retrieves a
copy of a message without
removing the original message from
a specified queue.
See Configuring Peek
Services on page 117.
Request/Reply
Service
Opens a session to a WebSphere MQ
Queue Manager. This service
delivers a message to a specified
queue and retrieves a corresponding
response from the sent message.
See Configuring
Request/Reply Services on
page 129.
Inquire Queue
Manager/Queue
Service
Opens a session to a WebSphere MQ
Queue Manager. This service
queries the queue manager and
queue properties.
See Configuring Inquire
Queue Manager/Queue
Services on page 144.
1 About the WebSphereMQ Adapter
28 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Put Services
A Put service creates an MQMessage object from the input signature properties, which
becomes the input document. You specify input signature properties when you configure
the Put service. The Put service places the message on the WebSphere MQ queue.
Runtime Processing for Put Services
The following diagram illustrates how the Put service delivers a message to a WebSphere
MQ queue.
PCF Command
service
Opens a session to a WebSphere MQ
Queue Manager. This service issues
Programmable Command Format
(PCF) commands to the queue
manager for execution. It retrieves
and parses the PCF command
responses.
See Configuring PCF
Command Services on
page 147.
Step Description
1 A flow or Java service, typically invoked by an Integration Server client,
initiates the Put service on Integration Server.
You configure the Put service and the wrapping flow or Java service, using
Developer or Designer.
Adapter Service Description For more information...
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 29
1 About the WebSphereMQ Adapter
2 The Put service retrieves a connection from the service's associated connection
pool.
You configure and enable the adapter connection using Integration Server
Administrator. For more information about connection pooling, including the
runtime behavior of connection pools, see Connection Pools on page 25.
3 WebSphere MQ Adapter uses the Put service's input document, or the
msgHeader properties from the Put service's input signature, to create an
MQMessage object.
You define the Put service's input signature when you configure the service.
Using Developer or Designer, the fields that you select on the MQMD Header tab
and the JMS Properties tab in the adapter service become the service's input
signature.
The following diagram illustrates the Put service's input signature, or input
document, where the msgBody value is copied to the MQMessage payload:
4 WebSphere MQ Adapter puts the MQMessage object on the WebSphere MQ
queue.
Step Description
1 About the WebSphereMQ Adapter
30 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Get Services
A Get service retrieves messages from a WebSphere MQ queue. The Get service also
creates an output document that contains the MQMD properties and the payload. When
you configure the Get service, you specify the output signature properties, which become
the output document.
Runtime Processing for Get Services
The following diagram illustrates how a Get adapter service retrieves a message from a
queue on WebSphere MQ. When the Get service executes, it checks the queue, retrieves
the message, and converts the message into a document.
5 The Put service returns a document that contains the msgHeader fields. You
define the Put service's output signature, or output document, when you
configure the service. The fields that you select on the MQMD Header tab become
the service's output signature.
The reasonCode, conditionCode, and errorMsg properties are also returned in
the output signature's document. The following diagram illustrates the Put
service's output signature where the MQMD fields are copied back to the
msgHeader document:
Step Description
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 31
1 About the WebSphereMQ Adapter
Step Description
1 A flow or Java service, typically invoked by an Integration Server client,
initiates the Get service on Integration Server.
You configure the Get service, and the wrapping flow or Java service, using
Developer or Designer.
2 The Get service retrieves a connection from the service's associated connection
pool.
You configure and enable the adapter connection using Integration Server
Administrator. For more information about connection pooling, including the
runtime behavior of connection pools, see Connection Pools on page 25.
3 The Get service uses the values from the input signature fields as filter criteria.
You define the Get service's input signature when you configure the service.
The fields that you select on the MQMD Header tab in the adapter service become
the service's input signature.
The following diagram illustrates the Get service's input signature properties
where selectionCriteria fields are copied into the MQMD Header:
1 About the WebSphereMQ Adapter
32 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Peek Services
The Peek service retrieves a copy of the message from the WebSphere MQ queue. The
Peek service creates an output document that contains the MQMD properties and the
payload. When you configure the Peek service, you specify the output signature
properties, which become the output document.
Runtime Processing for Peek Services
The following diagram shows how a Peek adapter service retrieves a copy of a message
from a queue on WebSphere MQ without removing the original message. When the Peek
service executes, it checks the queue, retrieves a copy of the message, and converts the
message data into a document.
4 The Get service retrieves the message from the WebSphere MQ queue. The
document, or the properties from the Get service's output signature, contain
the retrieved MQMD properties, JMS properties, and the payload.
5 The Get service returns a message to Integration Server that contains output
signature properties. You define the Get service's output signature when you
configure the service. The fields that you select on the MQMD Header tab and the
JMS Properties tab become the service's output signature.
The reasonCode, conditionCode, and errorMsg properties are also returned in
the output signature's document.
The following diagram illustrates the Get service's output signature. The
MQMessage's payload is mapped to the Get service's msgBody and the
MQMD Header fields are copied back to the msgHeader properties:
Step Description
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 33
1 About the WebSphereMQ Adapter
Step Description
1 A flow or Java service, typically invoked by an Integration Server client,
initiates the Peek service on the Integration Server.
You configure the Peek service, and the wrapping flow or Java service, using
Developer or Designer.
2 The Peek service retrieves a connection from the service's associated
connection pool. The connection uses the WebSphere MQ client libraries to
peek at messages on a queue.
You configure and enable the adapter connection using Integration Server
Administrator. For more information about connection pooling, including the
runtime behavior of connection pools, see Connection Pools on page 25.
1 About the WebSphereMQ Adapter
34 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
3 The Peek service uses the values from the input signature fields as filter
criteria.
You define the Peek service's input signature when you configure the service.
The fields that you select on the MQMD Header tab in the adapter service become
the service's input signature.
The following diagram illustrates the Peek service's input signature properties
where the selectionCriteria fields are copied into the MQMD Header:
4 The Peek service retrieves a copy of the message from the WebSphere MQ
queue and leaves the original message on the queue. The MQDocument, or the
properties from the Peek service's output signature, contain the retrieved
MQMD properties, JMS properties, and the payload.
5 The Peek service returns a message to Integration Server that contains output
signature properties. You define the Peek service's output signature when you
configure the service. The fields that you select on the MQMD Header tab and the
JMS Properties tab become the service's output signature.
The reasonCode, conditionCode, and errorMsg properties are also returned in
the output signature's document.
The following diagram illustrates the Peek service's output signature. The
MQMessage's payload is mapped to the Peek service's msgBody and the
MQMD Header fields are copied back to the msgHeader properties:
Step Description
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 35
1 About the WebSphereMQ Adapter
Request/Reply Services
The Request/Reply service puts a request message on the WebSphere MQ queue and
waits for a corresponding reply message.
Runtime Processing for Request/Reply Services
The following diagram shows how the adapter delivers a message to a specified queue
and retrieves a corresponding response from the sent message. In the following example,
the Request/Reply service automatically executes at a predefined time.
Step Description
1 A flow or Java service, typically invoked by an Integration Server client,
initiates the Request/Reply service on Integration Server.
You configure the Request/Reply service, and the wrapping flow or Java
service, using Developer or Designer.
2 The service retrieves a connection from the service's associated connection
pool.
Note: When you configure a Request/Reply service, make sure that you select a
non-transactional connection.
You configure and enable the adapter connection using Integration Server
Administrator. For more information about connection pooling, including the
runtime behavior of connection pools, see Connection Pools on page 25.
1 About the WebSphereMQ Adapter
36 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
3 The Request/Reply service creates an MQMessage and fills out the MQMD
fields with values from the Request/Reply service's input signature, and other
service fields that you specify on the Request/Reply Service tab in Developer or
Designer.
You define the Request/Reply service's input signature when you configure
the service. The fields that you select on the MQMD Header tab in the adapter
service become the service's input signature.
The following diagram illustrates the Request/Reply service's input signature
properties where the msgBody value is copied to the MQMessage payload:
4 The Request/Reply service puts a Request message on the WebSphere MQ
queue. The Request message contains the Request/Reply service's input
signature properties.
The Request/Reply service waits for a corresponding reply message from the
third-party application.
5 The Request/Reply service uses the Request document's input signature
MsgId as the filter criteria for a reply message CorrelId. If the message on the
specified reply queue matches the CorrelId filter criteria, then the message is
removed from the queue and the MQMD header information is copied to the
output document.
The service filters on the correlation ID object and retrieves the specified Reply
message from the queue. The Reply message contains the output signature
properties of the Request/Reply service.
Software AG assumes that the third-party application, which is integrated
with WebSphere MQ, will act as a message server to create a Reply message
and follow the above Request/Reply service paradigm.
Step Description
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 37
1 About the WebSphereMQ Adapter
Inquire Queue Manager/Queue Services
An Inquire Queue Manager/Queue service inquires the properties of a queue manager
such as dead letter queue name and connection count, and properties of a queue such as
current depth, open input count, and open output count. You can use this service to
design flow services where decisions can be taken based on the queried result.
Runtime Processing for Inquire Queue Manager/Queue Services
The following diagram illustrates how the Inquire Queue Manager/Queue service
inquires the properties of a Queue Manager and a Queue.
6 The Request/Reply service returns a Reply document that contains the
msgHeader fields and the replyMsgBody.
You define the Request/Reply service's output signature when you configure
the service. The fields that you select on the MQMD Header tab and the JMS
Properties tab in the adapter service become the service's output signature.
The reasonCode, conditionCode, and errorMsg properties are also returned in
the output signature's document. The Request/Reply service gets the reply
message from WebSphere MQ queue.
The following diagram illustrates the Request/Reply service's output signature
properties where the MQMD fields are copied back to the msgHeader
document and the payload is mapped to the replyMsgBody:
Step Description
1 About the WebSphereMQ Adapter
38 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Step Description
1 A flow or Java service, typically invoked by an Integration Server client,
initiates the Inquire Queue Manager/Queue service on Integration Server.
You configure the Inquire Queue Manager/Queue service, and the wrapping
flow or Java service, using Developer or Designer.
2 The Inquire Queue Manager/Queue service retrieves a connection from the
service's associated connection pool.
You configure and enable the adapter connection using Integration Server
Administrator. For more information about connection pooling, including the
runtime behavior of connection pools, see Connection Pools on page 25.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 39
1 About the WebSphereMQ Adapter
3 WebSphere MQ Adapter uses the Inquire Queue Manager/Queue service's
input document from the Inquire Queue Manager/Queue service's input
signature.
You define the Inquire Queue Manager/Queue service's input signature
(Queue Name), when you configure the service. The adapter inquires the
properties of the queue manager specified in the connection and also inquires
the properties of the first queue specified in the connection.
You can override the queue name by specifying the queue name in the
service's input signature.
The following diagram illustrates the Inquire Queue Manager/Queue service's
input signature, or input document:
4 The Inquire Queue Manager/Queue service returns a document that contains
the properties of the queue manager and the queue.
The reasonCode, conditionCode, and errorMsg properties are also returned in
the output signature's document. Using Developer or Designer, the fields that
you select on the Queue Manager Properties tab and the Queue Properties tab in the
adapter service become the service's output signature.
The following diagram illustrates the Inquire Queue Manager/Queue service's
output signature:
Step Description
1 About the WebSphereMQ Adapter
40 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
PCF Command Services
PCF Command service issues Programmable Command Format (PCF) commands to the
WebSphere MQ command server for execution.
The WebSphere MQ Programmable Command Formats (PCFs) define command and
reply messages that can be exchanged between a program and any queue manager (that
supports PCFs) in a network. You can use PCF commands in a systems management
application program for administration of WebSphere MQ objects: authentication
information objects, channels, channel listeners, namelists, process definitions, queue
managers, queues, services, and storage classes.
Runtime Processing for PCF Command Services
The following diagram illustrates how the PCF Command service executes a PCF
command.
Step Description
1 A flow or Java service, typically invoked by an Integration Server client,
initiates the PCF Command service on Integration Server.
You configure the PCF Command service, and the wrapping flow or Java
service, using Developer or Designer.
2 The PCF Command service retrieves a connection from the service's
associated connection pool.
You configure and enable the adapter connection using Integration Server
Administrator. For more information about connection pooling, including the
runtime behavior of connection pools, see Connection Pools on page 25.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 41
1 About the WebSphereMQ Adapter
Associating Connections and Adapter Services
This section summarizes the methods by which you can associate a connection with an
adapter service.
3 WebSphere MQ Adapter uses the input parameters of the PCF Command
service to generate a PCF command and posts the request to the queue
manager using the WebSphere MQ PCF Library.
The following diagram illustrates the PCF Command service's input
signature, or input document:
4 The Queue Manager executes the requested PCF command and returns the
response to the adapter.
The PCF Command service returns a message to Integration Server that
contains output signature properties. You define the PCF Command service's
output signature when you configure the service. The fields that you select on
the Response Parameters tab become the service's output signature.
The reasonCode, conditionCode, and errorMsg properties are also returned in
the output signature's document.
The following diagram illustrates the PCF Command service's output
signature:
Step Description
1 About the WebSphereMQ Adapter
42 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Specify a Default Connection at Design Time
When you configure an adapter service at design time, you specify a default connection
that the service is to use. The service will use this connection unless you override it using
one of the following methods:
For more information about configuring adapter services, see Adapter Services on
page 89.
When you configure a new adapter service, the service's overrideConnection
property is null. To read about the overrideConnection property, see Overriding
Connections in a Flow Service at Run Time on page 79.
Use Developer or Designer to Supply a Value for overrideConnection
at Design Time
At design time, use Developer or Designer to supply a value through the pipeline for the
overrideConnection property. Integration Server will use the connection parameters
identified in overrideConnection rather than the adapter service's default connection.
This method temporarily overrides the adapter service's default connection.
Use this method to change the target queue of an existing adapter service for a
specific flow.
If you use this method, the adapter will ignore connection management processing.
This could result, for example, in Integration Server exceeding the maximum number
of connections defined for this connection's pool (that is, the value defined with the
Maximum Pool Size parameter).
For more information about the overrideConnection property, and instructions on setting
its value with the Set Value icon, see Overriding Connections in a Flow Service at Run
Time on page 79.
Programmatically Supply a Value for overrideConnection at Run Time
At run time you can programmatically supply connection parameters in the
overrideConnection property. Integration Server will use the connection parameters
identified in overrideConnection rather than the adapter service's default connection.
This method temporarily overrides the adapter service's default connection.
Use this method when you do not know the identity of the target queue until run
time.
If you use this method, the adapter will ignore connection management processing.
This could result, for example, in Integration Server exceeding the maximum number
of connections defined for this connection's pool (that is, the value defined with the
Maximum Pool Size parameter).
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 43
1 About the WebSphereMQ Adapter
For more information about the overrideConnection property, and instructions on using
it, see Overriding Connections in a Flow Service at Run Time on page 79.
Programmatically Supply a Value for $connectionName at Run Time
At run time you can programmatically supply a connection name in the
$connectionName field. This field enables you to dynamically select the connection a
service uses to interact with the adapter's resource.
This method temporarily overrides the adapter service's default connection.
Use this method when you need to choose between a limited number of connections
at run time.
This method enables one service to interact with multiple, similar backend resources.
For example, a service can be defined to use a default connection that places a
message on an output queue. However, at run time you can override the default
connection and instead use another connection to interact with a different output
queue.
For more information about overriding a service's default connection at run time, see
Dynamically Changing a Service's Connection at Run Time on page 81.
Programmatically Change the Connection Associated with an
Adapter Service at Design Time
At design time you can use a built-in service to change the connection associated with an
adapter service. This built-in service is named pub.art.service:setAdapterServiceNodeConnection.
Using this function, you can change the specific connection associated with an adapter
service at design time so that you do not need to configure and maintain multiple adapter
services.
Note: This built-in service can be run at design time only; do not use it within an
Integration Server flow or Java service. You must run this service directly from Developer
or Designer by selecting the service and running it.
This method permanently changes the properties of a connection.
For details about built-in services, see the Integration Server built-in services reference
guide for your release. See About this Guide for specific document titles.
Adapter Notifications
WebSphere MQ Adapter provides listeners and listener notifications to perform the
following functions:
Monitor messages
1 About the WebSphereMQ Adapter
44 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Filter messages
Process messages
Listeners
A WebSphere MQ Adapter listener continually monitors a queue for messages. When a
message appears on a queue, the listener fetches the message, based on the filter criteria
that you selected when you configured the listener. The listener passes the message to the
listener notification. Unlike the Put and Get adapter services, you never invoke a listener
directly from a service or client. Instead, a listener is a real-time process that you
configure, enable, and disable using the IS Administrator.
All the listeners will stop functioning when the package containing the listener node
is disabled or when Integration Server shuts down.
All the listeners will start functioning when the package containing the listener node
is enabled or when Integration Server restarts.
WebSphere MQ Adapter has two listener types: single-queue listeners and multi-queue
listeners.
A Single-Queue Listener listens to a single queue configured in the connection.
A Multi-Queue Listener listens to multiple queues configured in the connection. This
substantially reduces the number of listeners that needs to be configured and
managed. When a multi-queue listener is configured, the adapter in turn creates a
single-queue listener for each queue specified in the connection. In effect, there is one
listener node (child) for each queue specified in the connection, and one multi-queue
listener node (parent). The parent node manages the life cycle
(enable/disable/update/delete) of all its child nodes.
All the child listeners are named after the queue they listen to, prefixed by the multi-
queue listener name provided. By default, the child listeners inherit all the properties
of the parent listener. Whenever the parent listener properties are changed, all the
child listeners of that parent are updated with the changed properties. The child
listeners can override the parent listener properties when you set the Inherit Parent
Listener's Properties parameter to false in the child listener.
For information about how to configure listeners, see Configuring New Listeners on
page 163.
Listener Notifications
A listener notification works in conjunction with a listener to filter and process messages
in WebSphere MQ Adapter. When a listener detects a message on a queue, the listener
performs a Get operation to retrieve the message, and passes the message to the listener
notification. The listener notification receives the message and performs an additional
filter on the messages, based on the filter criteria that you selected when you configured
the listener notification. The listener notification processes the message either
synchronously or asynchronously.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 45
1 About the WebSphereMQ Adapter
When notifications are used with multi-queue listeners, by default, the child listeners use
the notifications configured for the parent. You can register notifications with individual
child listeners, in which case these notifications will override the notifications inherited
from its parent.
WebSphere MQ Adapter has two listener notification types:
Asynchronous Listener Notifications
Synchronous Listener Notifications
Asynchronous Listener Notifications
When you create an asynchronous notification, WebSphere MQ Adapter creates a
publishable document type. The publishable document type defines the structure of the
document that includes the msgBody and msgHeader properties. At run time, after the
listener retrieves a message from the queue, the listener invokes the asynchronous
notification. The asynchronous notification publishes the document that has the structure
defined by the publishable document type created with the asynchronous notification.
An asynchronous listener notification can publish a document in either of the following
ways:
Publish to a Broker when Integration Server is connected to a Broker (default)
Publish locally to Integration Server when Integration Server is not connected to a
Broker
To process the message from the queue, you should create an Integration Server trigger
that subscribes to the document type that WebSphere MQ Adapter created with the
asynchronous notification. For more information about using triggers with services, see
the Integration Server publish-subscribe developers guide for your release. See About
this Guide for specific document titles.
Beginning with Integration Server 8.0, you can choose the destination to which
asynchronous notifications should publish messages. Specifically, you can choose
whether the asynchronous notification templates use JMS APIs to publish messages to
Integration Server or webMethods Broker APIs to publish notification messages to
webMethods Broker.
Note: To use the JMS protocol with asynchronous notifications, you must first configure a
JMS connection alias on Integration Server. For more information, see the Integration
Server administration guide for your release. See About this Guide for specific
document titles.
For steps for selecting a publish destination for asynchronous notification messages, see
Listener Notifications on page 176.
Synchronous Listener Notifications
When you create a synchronous listener notification, WebSphere MQ Adapter creates the
following document types:
1 About the WebSphereMQ Adapter
46 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Request Document. The synchronous Request document contains the msgBody,
msgHeader, queueManagerName, and queueName properties.
Reply Document. The synchronous Reply document contains the replyMsgBody and
msgHeader properties.
At run time the listener notification invokes a specified adapter service and passes it to
the specified Request document. The service returns the Reply document to
WebSphere MQ Adapter. The listener notification waits until the service has finished
processing the message before it initiates the next service. A synchronous listener
notification does not publish a document.
Synchronous adapter notifications execute flow services and return values from those
services. Integration Server 8.0 supports the following two execution modes to determine
how the notification executes a flow service and returns output:
Service Invoke mode: When this mode is selected, the adapter notification invokes a
flow service directly and returns values as output from that service.
Publish and Wait mode: When this mode is selected, the adapter notification publishes
the received data either to the local Integration Server or to the webMethods Broker
connected to that Integration Server by converting request documents into
publishable documents, and then waits for a reply. This mode is needed when a
synchronous adapter notification is represented as a receive step in a process model.
For steps for specifying execution modes for synchronous adapter notifications, see
Listener Notifications on page 176.
Listener Notification Templates
WebSphere MQ Adapter provides the following adapter notification templates:
Listener Notification Description
Asynchronous
Listener
Notification
Publishes a document type that Integration Server processes
asynchronously. That is, Integration Server does not wait until it
has finished processing a document before processing another
document.
For more information about configuring asynchronous
notifications, see the procedureConfiguring an Asynchronous
Listener Notification on page 178.
Synchronous
Listener
Notification
Invokes a service to process the message before receiving the
next message.
For more information about configuring synchronous
notifications, see Configuring an Asynchronous Listener
Notification on page 178.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 47
1 About the WebSphereMQ Adapter
Exactly Once Notification Feature in a Clustered Environment
Only transactional asynchronous listeners can use the Exactly Once notification feature in
a clustered Integration Server environment. The Exactly Once notification feature ensures
that notification data will not be duplicated even if a failure occurs during processing.
This is achieved by assigning unique IDs for each publishable document. After a
processing failure, Integration Server checks for duplicate records in storage and ignores
any duplicate IDs.
For more information on setting up and using the Exactly Once notification feature with a
transactional asynchronous listener in a clustered environment, see Using the Exactly
Once Notification Feature in a Clustered Environment on page 66.
Listener Transactionality
Listeners can either be transactional or non-transactional.
Transactional Listeners
If you enable a transactional listener, but have not enabled any notifications to process the
message, and the message passes through the listener filter criteria, then the message
does the following:
Rolls back to the queue
Eventually goes to the dead letter queue
Note: A transactional listener is associated with a transactional connection.
Non-Transactional Listeners
If you enable a non-transactional listener, but have not enabled any notifications to
process the message, and the message passes through the listener filter criteria, then the
message is lost.
Note: A non-transactional listener is associated with a non-transactional connection.
Runtime Processing of Listeners and Notifications
Runtime processing occurs in listeners and notifications in the following scenarios:
Listeners and asynchronous listener notifications
Listeners and synchronous listener notifications
Runtime Processing of Listeners and Asynchronous Listener Notifications
The following diagram and steps illustrate what happens when a listener retrieves a
message from a queue and passes the message to an asynchronous listener notification.
1 About the WebSphereMQ Adapter
48 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Step Description
1 The listener retrieves a connection from the service's associated connection
pool. The connection uses the WebSphere MQ libraries to monitor and listen
for messages on a queue.
2 The listener monitors the queue for messages.
3 When a message appears on the queue, the listener retrieves the message from
the queue and passes it to the asynchronous notification.
4 The asynchronous notification compares the message's MQMD Header fields
against the Filter Criteria fields specified for the notification. If all specified
criteria matches between the two sets of fields, then the asynchronous
notification will be invoked to publish the document.
If the specified criteria does not match between the message's MQMD Header
fields and the Filter Criteria fields, then the asynchronous notification is not
invoked to publish the document.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 49
1 About the WebSphereMQ Adapter
Runtime Processing of Listeners and Synchronous Listener Notifications
The following diagram and steps illustrate what happens when a listener retrieves a
message from the queue and invokes a synchronous listener notification.
5 The asynchronous notification creates a publishable document, which contains
the msgBody, msgHeader properties, JMS properties, queueManagerName,
queueName, and envelope information. The asynchronous notification
publishes the document that the service, which you created, processes at a
later time.
Note: For transactional connections, if an asynchronous notification processes
the message, then WebSphere MQ Adapter commits the message and removes
it from the queue. If none of the asynchronous notifications process the
message, then WebSphere MQ Adapter will roll back the message and make it
available for other applications.
6 The listener gets the next message from the queue, and WebSphere MQ
Adapter repeats steps 1 through 5.
7 Using an Integration Server trigger that you configured to use the
notification's publishable document, a flow or Java service that you configured
on Integration Server is invoked to process the message data in the publishable
document.
Step Description
1 About the WebSphereMQ Adapter
50 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Using Version Control Systems to Manage Adapter Elements
The adapter supports the Version Control System (VCS) Integration feature provided by
Designer. When you enable the feature in Integration Server, you can check adapter
packages or elements into and out of your version control system from Designer. For
more information about the VCS Integration feature, see Administering the VCS Integration
Feature.
Step Description
1 The listener retrieves a connection from the service's associated connection
pool. The connection uses the WebSphere MQ libraries to monitor and listen
for messages on a queue.
2 The listener monitors the queue for messages.
3 When a message appears, the listener retrieves the message from the queue.
The listener passes the message to the synchronous notification.
4 The synchronous notification compares the message's MQMD Header fields
against the Filter Criteria fields specified for the notification. If all specified
criteria matches between the two sets of fields, then the listener invokes the
synchronous notification to process the message.
If the specified criteria does not match between the message's MQMD Header
fields and the Filter Criteria fields, then the synchronous notification is not
invoked to process the message.
5 The synchronous notification creates the following documents types:
Request document
Reply document
The Request document contains the msgBody, msgHeader,
queueManagerName, and queueName properties. The synchronous
notification invokes the service that you selected when you configured the
synchronous notification and passes in the Request document.
The specified service processes the message and returns the Reply document
to WebSphere MQ Adapter. The Reply document contains the replyMsgBody,
msgHeader properties, and JMS properties.
Note: For transactional connections, if a synchronous notification processes the
message, then WebSphere MQ Adapter commits the message and removes it
from the queue. If the synchronous notifications do not process the message,
or if they throw an exception, then WebSphere MQ Adapter will rollback the
message and make it available for other applications.
6 After the service has processed the data in the Request document, then the
listener retrieves another message from the queue.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 51
1 About the WebSphereMQ Adapter
Beginning with Integration Server 8.2 SP3, the adapter supports the local service
development feature in Designer. This feature extends the functionality of the VCS
Integration feature to check package elements and their supporting files into and out of a
VCS directly from Designer. For more information about local service development and
how it compares to the VCS Integration feature, see webMethods Service Development Help.
Infrastructure Data Collector Support for the Adapter
Infrastructure Data Collector monitors the system and operational data associated with
webMethods run-time components such as Integration Servers, Broker Servers, Brokers,
and adapters, and reports the status of these components on Optimize for Infrastructure
or other external tools. When you start monitoring an Integration Server, Infrastructure
Data Collector automatically starts monitoring all ART-based adapters that are installed
on the Integration Server.
For information about monitored key performance indicators (KPIs) collected for the
monitored adapter components, see the Optimize documentation for your release. See
About this Guide for specific document titles.
Viewing the Adapter's Update Level
You can view the list of updates that have been applied to the adapter Updates field on the
adapter's About page in Integration Server Administrator.
Controlling Pagination
When using the adapter on Integration Server 8.0 and later, you can control the number
of items that are displayed on the adapter Connections screen and Notifications screen.
By default, 10 items are displayed per page. Click Next and Previous to move through the
pages, or click a page number to go directly to a page.
To change the number of items displayed per page, set the watt.art.page.size property
and specify a different number of items.
To set the number of items per page
1 From Integration Server Administrator, click Settings > Extended.
2 Click Edit Extended Settings. In the Extended Settings editor, add or update the
watt.art.page.size property to specify the preferred number of items to display per
page. For example, to display 50 items per page, specify:
watt.art.page.size=50
1 About the WebSphereMQ Adapter
52 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
3 Click Save Changes. The property appears in the Extended Settings list.
For more information about working with extended configuration settings, see the
Integration Server administration guide for your release. See About this Guide for
specific document titles.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 53
2 Installing, Upgrading, and Uninstalling
WebSphere MQ Adapter
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Installing WebSphereMQ Adapter 6.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Upgrading to WebSphereMQ Adapter 6.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Uninstalling WebSphereMQ Adapter 6.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
2 Installing, Upgrading, and Uninstalling WebSphereMQ Adapter
54 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Overview
This chapter explains how to use the Software AG Installer wizard to install, upgrade,
and uninstall webMethods WebSphere MQ Adapter 6.5. For complete information about
other installation methods or installing other webMethods products, use the
webMethods installation guide for your release. See About this Guide for specific
document titles.
Requirements
For a list of the operating systems, WebSphere MQ products, and webMethods products
supported by the adapter, see the webMethods Adapters System Requirements.
WebSphere MQ Adapter 6.5 has no hardware requirements beyond those of its host
Integration Server.
Installing WebSphere MQ Adapter 6.5
The instructions in this section explain how to use the Software AG Installer wizard to
install the WebSphere MQ Adapter. To install the adapter on AS/400, you must use
Installer's console mode. For more information, see the webMethods installation guide
for your release. See About this Guide for specific document titles.
Note: If you are installing the adapter in a clustered environment, you must install it on
each Integration Server in the cluster, and each installation must be identical. For more
information about working with the adapter in a clustered environment, see
WebSphere MQ Adapter in a Clustered Environment on page 63.
To install WebSphere MQ Adapter 6.5
1 Download Software AG Installer from the Empower Product Support website.
2 If you are installing the adapter on an existing Integration Server, shut down the
Integration Server.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 55
2 Installing, Upgrading, and Uninstalling WebSphereMQ Adapter
3 Start the Installer wizard.
Choose the webMethods release that includes the Integration Server on which to
install the adapter. For example, if you want to install the adapter on Integration
Server 8.2, choose the 8.2 release.
If you are installing on an existing Integration Server, specify the webMethods
installation directory that contains the host Integration Server. If you are installing
both the host Integration Server and the adapter, specify the installation directory
to use. Installer will install the adapter in the Integration Server_directory\packages
directory.
In the product selection list, select Adapters >webMethods WebSphere MQ Adapter6.5.
You can also choose to install documentation.
4 If you installed on a Windows system, add the mqjbndnn.dll file to the path system
environment variable using one of the methods below:
Add the WebSphereMQ_directory\java\lib directory to your path system
environment variable, where WebSphereMQ_directory is the directory in which
you installed the WebSphere MQ Server.
If the WebSphere MQ Adapter is installed on a remote machine, go to the
WebSphereMQ_directory\java\lib directory and copy the mqjbndnn.dll file into a
local directory that is in your path system environment variable, where nn is the
version number of the .dll file.
5 Copy the WebSphere MQ client .jar files to the host Integration Server. The adapter
requires these files to connect to the IBM WebSphere MQ server.
Important! If you do not copy the MQ client .jar files to Integration Server, the
WebSphere MQ Adapter fails to register itself with the webMethods Adapter
Runtime (WmART) and the WebSphere MQ Adapter link will not appear under the
Adapters panel in the Integration Server Administrator page.
Copy the com.ibm.mq.jar file in the WebSphereMQ_directory\java\lib directory to
the Integration Server_directory\packages\WmMQAdapter\code\jars directory.
Copy the jar file for your corresponding WebSphere MQ version:
For WebSphere MQ 5.x: Copy
WebSphereMQ_directory\java\lib\com.ibm.mq.pcf.jar to
Integration Server_directory\packages\WmMQAdapter\code\jars. This jar file
is available when you install the PCF Support Pack (WebSphere MQ Java
classes for PCF), available from the IBM Support site.
For WebSphere MQ 6.0: Copy
WebSphereMQ_directory\eclipse\plugins\com.ibm.mq.pcf_6.0.0\pcf.jar to
Integration Server_directory\packages\WmMQAdapter\code\jars
This jar file is available when you have MQ Explorer installed.
2 Installing, Upgrading, and Uninstalling WebSphereMQ Adapter
56 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
For WebSphere MQ 7.x: Copy the com.ibm.mq.commonservices.jar,
com.ibm.mq.headers.jar, com.ibm.mq.pcf.jar, and com.ibm.mq.jmqi.jar from
WebSphereMQ_directory\java\lib to
Integration Server_directory\packages\WmMQAdapter\code\jars.
These jar files are available when you have MQ Explorer installed.
6 Start the host Integration Server.
7 If you are going to use the adapter with Integration Server 8.0, apply fix
MQS_6.5_8.0_Fix1 or later.
Installing this fix provides support for pagination when viewing lists of the adapter's
connections, listeners, and notifications and also enables you to sort and filter the
lists. For more information about controlling pagination, sorting, and filtering when
viewing the adapter information, see Controlling Pagination on page 51.
Upgrading to WebSphere MQ Adapter 6.5
You cannot upgrade to WebSphere MQ Adapter 6.5 from pre-6.0 WebSphere MQ
Adapters or from MQSeries adapters 2.0, 2.1, or 3.0.
You can upgrade to WebSphere MQ Adapter 6.5 from WebSphere MQ Adapter 6.0 or 6.0
SP1. You can use WebSphere MQ Adapter 6.5 to run or edit services and listeners you
generated using WebSphere MQ Adapter 6.0 or 6.0 SP1.
The method you use to upgrade depends on whether you want to make a copy of the
existing adapter package. Making a copy enables you to revert to the earlier adapter
package later if necessary.
If you do not want to make a copy of the existing adapter package, uninstall the
existing adapter using instructions in the adapter's installation guide. Then install
WebSphere MQ Adapter 6.5 using the instructions in Installing WebSphere MQ
Adapter 6.5 on page 54.
If you do want to make a copy of the existing adapter package, install WebSphere MQ
Adapter 6.5 using the instructions in Installing WebSphere MQ Adapter 6.5 on
page 54. Installer will detect the existing adapter and ask whether you want to save a
copy of the adapter package. Click Yes. Installer saves the adapter package to the
Integration Server_directory\replicate\salvage folder and then continues with the
WebSphere MQ Adapter 6.5 installation.
Uninstalling WebSphere MQ Adapter 6.5
You use the Software AG Uninstaller wizard to uninstall the WebSphere MQ Adapter.
For instructions about using Uninstaller, see the webMethods installation guide for your
release. See About this Guide for specific document titles.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 57
2 Installing, Upgrading, and Uninstalling WebSphereMQ Adapter
To uninstall WebSphere MQ Adapter 6.5
1 Shut down the host Integration Server. You do not need to shut down any other
webMethods products or applications that are running on your machine.
2 Software AG Uninstaller will not delete any user-defined WebSphere MQ Adapter 6.5
components such as connections and adapter services. Because these components
will not work without the adapter, delete them manually, either at the file system
level or using Developer or Designer. For instructions, see the Developer users guide
or Designer Service Development online help for your release. See About this Guide
for specific document titles.
3 Start Uninstaller, selecting the webMethods installation directory that contains the
host Integration Server. In the product selection list, select Adapters >webMethods
WebSphere MQ Adapter6.5. You can also choose to uninstall documentation.
4 Restart the host Integration Server.
5 Uninstaller removes all WebSphere MQ Adapter 6.5-related files that were installed.
However, Uninstaller does not delete files created after you installed the adapter (for
example, user-created or configuration files), nor does it delete the adapter directory
structure. You can go to the Integration Server_directory\packages directory and delete
the WmMQAdapter directory.
2 Installing, Upgrading, and Uninstalling WebSphereMQ Adapter
58 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 59
3 Package Management
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
WebSphereMQ Adapter Package Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Group Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
WebSphereMQ Adapter in a Clustered Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
3 Package Management
60 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Overview
The following sections describe how to set up and manage your WebSphere MQ Adapter
packages, set up Access Control Lists (ACL), and use the adapter in a clustered
environment.
WebSphere MQ Adapter Package Management
WebSphere MQ Adapter is provided as a package called WmMQAdapter. You manage
the WmMQAdapter package as you would manage any package on the Integration
Server.
When you create connections, adapter services, adapter notifications, and adapter
listeners define them in user-defined packages rather than in the WmMQAdapter
package. Doing this will allow you to manage the packages more easily, especially when
you need to upgrade a deployed adapter. You may create all the connections and adapter
services of an adapter in one package, or you may distribute them among multiple
packages. For instructions on creating packages, see the Developer users guide or
Designer Service Development online help for your release. See About this Guide for
specific document titles.
As you create user-defined packages, use the package management functionality
provided in Developer or Designer to set the user-defined packages to have a
dependency on the WmMQAdapter package. That way, when the WmMQAdapter
package loads or reloads, the user-defined packages load automatically. See the following
diagram:
Package management tasks include:
Setting package dependencies, see Package Dependency Requirements and
Guidelines on page 61
Enabling Packages on page 61
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 61
3 Package Management
Disabling Packages on page 62
Package Dependency Requirements and Guidelines
The following are dependency requirements and guidelines for user-defined packages.
For instructions for setting package dependencies, see the Developer users guide or
Designer Service Development online help for your release. See About this Guide for
specific document titles.
By default, the WmMQAdapter package has a dependency on the WmART package.
Do not change this dependency.
A user-defined package must have a dependency on the WmMQAdapter package.
These dependencies ensure that at startup Integration Server automatically loads or
reloads all packages in the proper order: the WmART package first, the adapter
package next, and the user-defined packages last. The WmART package is
automatically installed when you install Integration Server. You should not need to
manually reload the WmART package.
If the connections and adapter services of an adapter are defined in different
packages, then:
A package that contains the connections must have a dependency on the adapter
package.
Packages that contain adapter services, adapter notifications, or adapter listeners
must depend on their associated connection package.
Keep connections for different adapters in separate packages so that you do not create
interdependencies between adapters. If a package contains connections for two
different adapters, and you reload one of the adapter packages, the connections for
both adapters will reload automatically.
Integration Server will not allow you to enable a package if it has a dependency on
another package that is disabled. That is, before you can enable your package, you
must enable all packages on which your package depends. For information about
enabling packages, see Enabling Packages on page 61.
Integration Server will allow you to disable a package even if another package that is
enabled has a dependency on it. Therefore, you must manually disable any user-
defined packages that have a dependency on the adapter package before you disable
the adapter package. For information about disabling packages, see Disabling
Packages on page 62.
You can name connections and adapter services with the same name provided that
they are in different packages and folders.
Enabling Packages
All packages are automatically enabled by default. Use the following procedure to enable
packages manually or re-enable packages you previously disabled.
3 Package Management
62 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Enabling an adapter package will not cause its associated user-defined packages to be
reloaded.
Important! Before you manually enable a user-defined package, you must first enable its
associated adapter package (WmMQAdapter).
To enable a package using Integration Server Administrator
1 Open Integration Server Administrator if it is not already open.
2 In the Packages menu of the navigation area, click Management.
3 Click No in the Enabled column for the package that you want to enable.
4 The server issues a prompt to verify that you want to enable the package.
When the package is enabled, Integration Server Administrator displays the icon
and Yes in the Enabled column.
Disabling Packages
When you want to temporarily prohibit access to the elements in a package, disable the
package. When you disable a package, the server unloads all of its elements from
memory. Disabling a package prevents Integration Server from loading that package at
startup.
Note: If your adapter has multiple user-defined packages, and you want to disable some
of them, disable the adapter package first. Otherwise, errors will be issued when you try
to access the remaining enabled user-defined packages.
To disable a package using Integration Server Administrator
1 Open Integration Server Administrator if it is not already open.
2 In the Packages menu of the navigation area, click Management.
3 Click Yes in the Enabled column for the package that you want to disable.
4 The server issues a prompt to verify that you want to disable the package. Click OK to
disable the package.
When the package is disabled, Integration Server Administrator displays No in the
Enabled column.
A disabled adapter will:
Remain disabled until you explicitly enable it using Integration Server Administrator.
Not be listed in webMethods Developer or Software AG Designer.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 63
3 Package Management
Group Access Control
To control which development group has access to which adapter services and adapter
notifications, use access control lists (ACLs). You can use ACLs to prevent one
development group from inadvertently updating the work of another group, or to allow
or deny access to services that are restricted to one group but not to others.
For general information about assigning and managing ACLs, see the Developer users
guide or Designer Service Development online help for your release. See About this
Guide for specific document titles.
WebSphere MQ Adapter in a Clustered Environment
Clustering is an advanced feature of the webMethods product suite that substantially
extends the reliability, availability, and scalability of webMethods Integration Server.
Clustering accomplishes this by providing the infrastructure and tools to deploy multiple
Integration Servers as if they were a single virtual server and to deliver applications that
leverage that architecture. Because this activity is transparent to the client, clustering
makes multiple servers look and behave as one. For details on webMethods Integration
Server clustering, see the Integration Server clustering guide for your release. See About
this Guide for specific document titles.
Integration Server 8.2 SP2 and higher supports the caching and clustering functionality
provided by Terracotta. Caching and clustering are configured at the Integration Server
level and WebSphere MQ Adapter uses the caching mechanism that is enabled on
Integration Server.
With clustering, you get the following benefits:
Load balancing. This feature, provided automatically when you set up a clustered
environment, allows you to spread the workload over several servers, thus improving
performance and scalability.
Failover support. Clustering enables you to avoid a single point of failure. If a server
cannot handle a request, or becomes unavailable, the request is automatically
redirected to another server in the cluster.
Note: Integration Server clustering redirects HTTP and HTTPS requests, but does not
redirect FTP or SMTP requests.
Scalability. You can increase your capacity even further by adding new machines
running Integration Server to the cluster.
3 Package Management
64 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Adapter Service Support in Clusters
Adapter services are supported in a clustered environment. In order for a cluster to
handle requests identically, you should ensure that the identical service is in each
Integration Server in the cluster so that if a given service is not available, the request can
be redirected and handled by another Integration Server in the cluster.
For more details about adapter services in clusters, see Clustering Considerations and
Requirements on page 64.
WebSphere MQ Adapter Notification Support in Clusters
WebSphere MQ Adapter supports transactional listeners with asynchronous notifications
in a clustered environment.
Duplicate Documents
Integration Server provides WebSphere MQ Adapter with support for duplicate
document detection in a cluster using its publish and subscribe facility.
Ordering of Documents
Neither WebSphere MQ Adapter nor WebSphere MQ guarantee the order of messages
received from WebSphere MQ. The application processing the notification documents
must handle any reordering of messages that is required.
Clustering Considerations and Requirements
The following considerations and requirements apply to WebSphere MQ Adapter in a
clustered environment. They assume that you have already configured the Integration
Server cluster. For details about webMethods clustering, see the Integration Server
clustering guide for your release. See About this Guide for specific document titles.
Requirements for Each Integration Server in a Cluster
The following table describes the requirements of each Integration Server in a given
cluster:
All Integration Servers
in a given cluster
must have identical... For Example...
Integration Server
versions
All Integration Servers in the cluster must be the same version,
with the same service packs and fixes applied.
Adapter packages All WebSphere MQ Adapter packages on one Integration Server
should be replicated to all other Integration Servers in the
cluster.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 65
3 Package Management
Considerations When Installing WebSphere MQ Adapter Packages
For each Integration Server in the cluster, use the standard WebSphere MQ Adapter
installation procedures for each machine, as described in Installing, Upgrading, and
Uninstalling WebSphere MQ Adapter on page 53.
Considerations When Configuring Connections with Connection Pooling
Enabled
When you configure a connection that uses connection pools in a clustered environment,
be sure that you do not exceed the total number of connections that can be opened
simultaneously for that queue.
For example, if you have a cluster of two Integration Servers with a connection
configured to a queue that supports a maximum of 100 connections opened
simultaneously, the total number of connections possible at one time must not exceed
100. This means that you cannot configure a connection with an initial pool size of 100
and replicate the connection to both servers, because there could be possibly a total of 200
connections opened simultaneously to this queue.
Adapter versions All WebSphere MQ Adapters in the cluster must be the same
version, with the same service packs and fixes applied.
User-defined
adapter packages
Each package that you have configured containing adapter
connections, adapter services, flow services, listeners, triggers,
and notifications for WebSphere MQ Adapter, must exist on all
of Integration Servers in the cluster, so that all Integration
Servers in the cluster can handle any given request.
To ensure consistency, we recommend that you create all
packages on one server, and replicate them to the other servers.
If you allow different servers to contain different services, you
might not derive the full benefits of clustering. For example, if a
client requests a service that resides in only one server, and that
server is unavailable, the request cannot be successfully
redirected to another server.
For information about replicating packages, see the chapter on
managing packages in the Integration Server administration
guide for your release. See About this Guide for specific
document titles.
Note: If you plan to use connection pools in a clustered
environment, see Considerations When Configuring
Connections with Connection Pooling Enabled on page 65.
All Integration Servers
in a given cluster
must have identical... For Example...
3 Package Management
66 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
In another example, consider a connection configured with an initial pool size of 10 and a
maximum pool size of 100. If you replicate this connection across a cluster with two
Integration Servers, it is possible for the connection pool size on both servers to exceed
the maximum number of queue connections that can be open at one time.
For information about configuring connections for WebSphere MQ Adapter, see
Configuring WebSphere MQ Adapter Connections on page 70.
For more general information about connection pools, see the Integration Server
administration guide for your release. See About this Guide for specific document
titles.
Considerations and Requirements for Notifications in a Clustered Environment
To ensure that documents are published exactly once, make sure the Exactly once
trigger property has Detect duplicates and Use history set to True when configuring
triggers for asynchronous notifications.
For asynchronous listener notifications to work correctly, the MsgID field in the
MQHeader must be unique. Therefore, do not filter listeners on the MsgID field.
Make sure the asynchronous notification's associated publishable document type is
publishable and is defined to a Broker, not defined as local only. These properties are
defined on the document type's Publication Properties tab.
Using the Exactly Once Notification Feature in a Clustered Environment
In order for the exactly once notification to work correctly for an asynchronous
notifications using a transactional listener, review the following considerations:
Specify a unique value for the MsgID property field
Make sure that the listener does not filter on the MsgID value
Note: It is assumed that the application that processes the resultant notification
documents will perform any necessary reordering. The order of the resultant notification
documents is not guaranteed in a clustered environment of Integration Server.
To use the exactly once notification feature for a transactional asynchronous listener notification
1 Install WebSphere MQ Adapter on all machines in the cluster. For detailed
instructions on how to install this adapter, see Installing, Upgrading, and
Uninstalling WebSphere MQ Adapter on page 53.
2 Install Integration Server. For complete installation instructions, see the webMethods
installation guide for your release. See About this Guide for specific document
titles.
3 Create separate packages for the connections, services, flows, listeners, triggers,
notifications on one of the machines in the cluster for deployment to the other
machines.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 67
3 Package Management
4 Verify that the PublishDocument is publishable and is defined to the Broker in the
PublishDocument properties. For detailed instructions on how to test a publishable
document type, see Testing Publishable Document Types on page 192.
5 Configure a trigger to use with the transactional asynchronous notification. For
detailed instructions on how to configure a trigger, see the Integration Server publish-
subscribe developers guide for your release. See About this Guide for specific
document titles.
6 When you configure the trigger for the transactional asynchronous notification using
Developer or Designer, make sure that you set the Exactly once trigger properties as
follows:
Detect duplicates = True
Use history = True
7 Deploy the packages with the adapter connections, adapter services, adapter flow
services, adapter listener, listener notifications, and triggers on the other machines in
the cluster.
Disabling the Redirection of Administrative Services
As mentioned in WebSphere MQ Adapter in a Clustered Environment on page 63, a
server that cannot handle a client's service request can automatically redirect the request
to another server in the cluster. However, WebSphere MQ Adapter uses certain
predefined administrative services that you should not allow to be redirected. These
services are used internally when you configure the adapter. If you allow these services to
be redirected, your configuration specifications might be saved on multiple servers,
which is an undesirable result. For example, if you create two WebSphere MQ Adapter
services, one might be stored on one server, while the other one might be stored on
another server. Remember that all adapter services must reside on all Integration Servers
in the cluster.
To disable the redirection of administrative services
1 Shut down Integration Server Administrator. For the procedure to do this, see the
Integration Server administration guide for your release. See About this Guide for
specific document titles.
2 Edit the following file:
Integration Server_directory\config\redir.cnf
3 Add the following line to the file:
<value name="wm.art">false</value>
4 Save the file and restart Integration Server.
3 Package Management
68 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 69
4 Adapter Connections
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Before Configuring or Managing Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Configuring WebSphereMQ Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Overriding Connections in a Flow Service at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Dynamically Changing a Service's Connection at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Viewing WebSphereMQ Adapter Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Editing WebSphereMQ Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Copying WebSphereMQ Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Deleting WebSphereMQ Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Enabling WebSphereMQ Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Disabling WebSphereMQ Adapter Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Configuring SSL Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
4 Adapter Connections
70 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Overview
The following sections provide instructions for configuring and managing
WebSphere MQ Adapter connections. For more information about how connections
work, see Adapter Connections on page 24.
Before Configuring or Managing Adapter Connections
The following procedure describes what you need to do before you create and configure
your WebSphere MQ Adapter connection.
Before you configure or manage an adapter connection
1 Install webMethods Integration Server and the WebSphere MQ Adapter on the same
machine. For details, see Installing, Upgrading, and Uninstalling WebSphere MQ
Adapter on page 53.
2 Make sure that you have webMethods administrator privileges so that you can access
the WebSphere MQ Adapter administrative screens. For information about setting
user privileges, see the Integration Server administration guide for your release. See
About this Guide for specific document titles.
3 Start Integration Server and Integration Server Administrator, if they are not already
running.
4 Using Integration Server Administrator, make sure that the WmMQAdapter package
is enabled. To verify the status of the WmMQAdapter package, see Enabling
Packages on page 61.
5 Using webMethods Developer or Software AG Designer, create a user-defined
package to contain the connection, if you have not already done so. For more
information about managing packages, see Package Management on page 59.
6 In order to create an adapter connection that connects to a WebSphere MQ queue, you
must ensure that the correct permissions are set for the user. For information about
setting permissions, see Setting Permissions in WebSphere MQ on page 23.
Configuring WebSphere MQ Adapter Connections
When you configure WebSphere MQ Adapter connections, you specify information that
Integration Server uses to connect to a queue and a queue manager. You configure
WebSphere MQ Adapter connections using Integration Server Administrator.
You can configure the following connection types with the WebSphere MQ Adapter:
WebSphere MQ Adapter Connection (Non-Transactional)
WebSphere MQ Adapter Transactional Connection
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 71
4 Adapter Connections
At design time, you must decide what type of connections to associate with adapter
services and adapter listeners to determine how you want them to process messages. For
example, a Get service requires a transactional connection to allow the WebSphere MQ
Adapter to roll back messages. The connection type that is associated with an adapter
listener also influences a listener notification, since notifications are associated with
listeners. To review the dependences between WmART, the WebSphere MQ Adapter,
adapter connections, adapter services, adapter listeners, and listener notifications, see the
figure in WebSphere MQ Adapter Package Management on page 60.
Important! If you are using the adapter with Integration Server 8.0 SP1 or earlier, adapter
services cannot use connections that are also used for adapter listeners. However,
listeners can share connections with other listeners.
For more information on how each service processes a message, see the appropriate run
time processing section for each service in About the WebSphere MQ Adapter on
page 15. For more information on how listeners perform when they are associated with a
non-transactional or transactional connection, see Behavior of Listeners on page 168.
For more information on how listener notifications perform when they are associated
with a non-transactional or transactional connection, see Behavior of Listener
Notifications on page 191.
To configure an adapter connection
1 In the Adapters menu in the Integration Server Administrator navigation area, click
WebSphere MQ Adapter.
2 On the Connections screen, click Configure New Connection.
3 On the Connection Types screen, to make a non-transactional connection, click
WebSphere MQ Connection to display the Configure Connection Type screen.
To make a transactional connection, click WebSphere MQ Transactional Connection to
display the Configure Connection Type screen.
4 Adapter Connections
72 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
4 In the WebSphere MQ Adapter section, specify values for the following fields:
5 In the Connection Properties section, use the following fields:
Parameter Description
Package The package in which to create the connection.
You must create the package using Developer or Designer
before you can specify it using this parameter. For general
information about creating packages, see the Developer users
guide or Designer Service Development online help for your
release. See About this Guide for specific document titles.
Create the connection in a user-defined package rather than
in the adapter's package. For other important considerations
when creating packages for the WebSphere MQ Adapter, see
Package Management on page 59.
Default: Package
Folder Name The folder in which to create the connection.
Connection Name The name you want to give the connection. Connection names
cannot have spaces or use special characters reserved by
Integration Server and Developer or Designer. For more
information about the use of special characters in package,
folder, and element names, see the Developer users guide or
Designer Service Development online help for your release.
See About this Guide for specific document titles.
Parameter Description
Queue Manager
Name
Required for a remote connection and for a local connection
to non-default Queue Managers.
The name of the Queue Manager to which you want to
connect.
The name you type must match the name of the Queue
Manager on the WebSphere MQ Queue Manager. This name
is case-sensitive. If you do not specify a Queue Manager
Name, the WebSphere MQ Adapter uses the default local
queue manager on the same machine the adapter is installed.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 73
4 Adapter Connections
Host Name Required for remote connection. The name of the machine on
which the WebSphere MQ Queue Manager is installed.
You can specify the IP address instead of the Host Name in
this field.
If you do not specify a Host Name or an IP address, the
WebSphere MQ Adapter does the following:
Uses the local Queue Manager binding mode, which
improves performance because the adapter is executing
on the same machine as the Queue Manager
Ignores the TCP/IP Port and Server Connection Channel
TCP/IP Port Optional. The port number where the WebSphere MQ Queue
Manager listens for client requests.
If you do not specify a port number, the WebSphere MQ
Adapter uses 1414 as the default.
Also, if you do not specify a Host Name, the WebSphere MQ
Adapter ignores the TCP/IP Port.
Server Connection
Channel
Required for remote connection. The name of the Server
Connection Channel assigned to a connection to the Server
from the client.
If you do not specify a Host Name, the WebSphere MQ
Adapter ignores the Server Connection Channel.
Note: This value is case sensitive. Maximum characters: 20.
CCSID Required. IBM's Coded Character Set Identifiers (CCSID)
used by the Integration Server. This numeric value specifies
the code page of the character-encoding scheme that the
webMethods machine is requesting to use. For valid CCSID
values, see IBM's WebSphere MQ documentation.
The CCSID specified for a remote connection is used only
when establishing the connection to the remote Queue
Manager.
User Id The user ID to connect to the Queue Manager, if the Queue
Manager is secured.
Password The password used with the user ID to connect to the Queue
Manager, if the Queue Manager is secured.
Retype Password Retype the password that you just entered.
Parameter Description
4 Adapter Connections
74 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Queue Name(s) The name of the Queue from which you want to send and
receive messages.
To select the queue names, perform one of the following
tasks:
Click the Find Queues button, and select one or more
queues from the drop-down menu.
Make sure that you specify the Queue Manager field before
selecting the Find Queues button. The WebSphere MQ
Adapter generates an error message if you have not
specified a value for the Queue Manager parameter.
Type one or more queue names in the Queue Name(s) field.
You can specify more than one Queue Name in this field
separated by a space. Specifying multiple queues allows
the Put service to broadcast a message to every queue in
the list. However, the list of queue names cannot contain
the name of a model queue.
The Get, Peek, and Request/Reply services only use the
first queue name in the list.
Dynamic Queue
Prefix
The prefix used when dynamically creating queues from a
model queue. If the queue specified in theQueue Namefield
refers to a model queue, then WebSphere MQ will
dynamically create a new queue when the WebSphere MQ
Adapter initializes the connection. The name of the new
queue will begin with this prefix, and will be globally unique.
Note: If the specified value does not end in an asterisk (*), the
name of the dynamically created queue is the value that you
specified in the Dynamic Queue Prefixfield.
Encoding Required. Numeric encoding used by Integration Server. This
value specifies the numeric-encoding scheme that Integration
Server is requesting to use.
The Encoding specified for a remote connection is used only
when establishing the connection to the remote Queue
Manager.
Default: 00273 - Native
Parameter Description
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 75
4 Adapter Connections
Send Exit Name The Java Class Name that contains the code the WebSphere
MQ Server will execute.
A Send Exit executes during the Put and Request/Reply
operations, before the message is placed on the queue. For
example, you could use this exit to encrypt or change the
message, based on information in the message header.
Send Exit Init Parms The initialization parameters that are the data values the
WebSphere MQ Server will pass to the Java class.
Receive Exit Name The Java Class Name that contains the code the WebSphere
MQ Server will execute.
A Receive Exit executes during the Get, Peek, and
Request/Reply operations. You can exit to filter or to change
messages based on information in the message header.
Receive Exit Init
Parms
Initialization parameters that are the data values the
WebSphere MQ Server will pass to the Java class.
Security Exit Name The Java Class Name that contains the code the WebSphere
MQ Server will execute.
A Security Exit allows you to customize the security flows
that occur when an attempt is made to connect to a queue
manager.
Security Exit Init
Parms
Initialization parameters that are the data values the
WebSphere MQ Server will pass to the Java class.
Parameter Description
4 Adapter Connections
76 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Cache Overridden
Connections
When you override a WebSphere MQ Adapter services'
connection parameters at run time, the WebSphere MQ
Adapter creates a new connection with the new parameters
and internally caches these connections to improve the
performance. However, in some cases the internal caching
can lead to large number of open connections. To avoid large
number of open connections, set this parameter to false.
Select how the connection is managed:
true Enables internal caching of overridden connections.
false Disables internal caching of overridden connections.
Default: true
Note: If you are using a connection configured using
WebSphere MQ Adapter 6.0, the connection refers to the watt
property watt.WmMQAdapter.Cache.Overridden.Connections. If this
watt property is not set, then WebSphere MQ Adapter sets
Cache Overridden Connection parameter to the default value
true.
Action before
Disconnecting an in-
transaction
Connection
This parameter is available only for transactional connections.
Select how the adapter must handle the transaction before
disconnecting:
COMMIT Commits the transaction before disconnecting.
ROLLBACK Rolls back the transaction before
disconnecting.
Default: COMMIT
Note: If you are using a connection configured using
WebSphere MQ Adapter 6.0, the connection refers to the watt
property watt.WmMQAdapter.actionBeforeDisconnect. If this watt
property is not set, then WebSphere MQ Adapter sets Action
before Disconnecting an in-transaction Connection to the default
value COMMIT.
SSL Keystore File This parameter is visible only when you set the
watt.WmMQAdapter.SSL.Support property to true.
The fully qualified file name of the SSL Keystore.
SSL Keystore
Password
This parameter is visible only when you set the
watt.WmMQAdapter.SSL.Support property to true.
The password associated with the SSL KeyStore.
Parameter Description
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 77
4 Adapter Connections
a In the Connection Management Properties section, use the following fields:
Retype SSL Keystore
Password
This parameter is visible only when you set the
watt.WmMQAdapter.SSL.Support property to true.
Retype the password that you just entered.
SSL Cipher Spec This parameter is visible only when you set the
watt.WmMQAdapter.SSL.Support property to true.
You can select any one of the following values:
DES_SHA_EXPORT
NULL_MD5
NULL_SHA
RC2_MD5_EXPORT
RC4_MD5_US
RC4_MD5_EXPORT
RC4_SHA_US
TRIPLE_DES_SHA_US
Default: DES_SHA_EXPORT
Parameter Description/Action
Enable Connection
Pooling
Enables the connection to use connection pooling.
For more information about connection pooling, see
Adapter Connections on page 24.
Default: true
Note: If you plan to enable connection pooling in a
clustered environment, consider the connection pool size.
For details, see Considerations When Configuring
Connections with Connection Pooling Enabled on
page 65.
Minimum Pool Size The minimum number of connection objects that remain
in the connection pool at all times. When the adapter
creates the pool, it creates this number of connections.
Default: 1
Parameter Description
4 Adapter Connections
78 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
6 Click Save Connection.
7 The connection that you configured appears on the adapter's Connections screen and
in Developer or Designer.
Maximum Pool Size The maximum number of connection objects that can exist
in the connection pool. When the connection pool has
reached its maximum number of connections, the adapter
will reuse any inactive connections in the pool or, if all
connections are active, it will wait for a connection to
become available.
Default: 10
Pool Size Increment If connection pooling is enabled, this field specifies the
number of connections by which the pool will be
incremented if connections are needed, up to the
maximum pool size.
Default: 1
Block Timeout
(msec)
If connection pooling is enabled, this field specifies the
number of milliseconds that the Integration Server will
wait to obtain a connection with the WebSphere MQ
Server before it times out and returns an error.
Default: 1000
Expire Timeout
(msec)
If connection pooling is enabled, this field specifies the
number of milliseconds that an inactive connection can
remain in the pool before it is closed and removed from
the pool. For example, to specify 10 seconds, specify 10000.
Enter 0 to specify no timeout.
Default: 1000
Note: Note that the adapter will never violate the Minimum
Connections parameter. These connections remain in the
pool regardless of how long they are inactive.
Startup Retry Count The number of times that the system should attempt to
initialize the connection pool at startup if the initial
attempt fails.
Default: 0
Startup Backoff
Timeout (sec)
The number of seconds that the system should wait
between attempts to initialize the connection pool.
Default: 10
Parameter Description/Action
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 79
4 Adapter Connections
8 By default, when you configure a connection, it is not enabled. For more information
about enabling connections, see Enabling WebSphere MQ Adapter Connections on
page 85.
Overriding Connections in a Flow Service at Run Time
At run time WebSphere MQ Adapter enables you to change the adapter service's queue
manager and queue. For example, when you override a service's connection, the
following takes place:
During run time, the service automatically re-creates a connection from a previous
invocation of the service with newly specified queues and a queue manager.
WebSphere MQ Adapter caches or stores the new connection for future use.
You can override a service's connection using the overrideConnection property in the
Developer or Designer Pipeline Editor. The overrideConnection property exists in the
Put, Get, Peek, and Request/Reply service's input and output signatures. When you
invoke these services with a flow service, the overrideConnection property also appears
in the Service In and Service Out sections of the Pipeline Editor for that service.
The overrideConnection property contains the following necessary objects to override a
connection in a service at run time:
queueManagerName
hostName
port
channel
CCSID
queueName
dynamicQueuePrefix
useLocalQueueManager
Encoding
If the queueName object specified in the overrideConnection property refers to a model
queue, then you should also specify the dynamicQueuePrefix object. The
dynamicQueuePrefix object specifies the prefix used to generate the name of a
dynamically generated queue. The adapter service returns this dynamically generated
queue name to the pipeline so that it can be reused.
For a complete list and a description of each object in the overrideConnection property,
refer to the Connection Properties section in Configuring WebSphere MQ Adapter
Connections on page 70. Also, refer to the instructions below to override connections
within a service using the Pipeline Editor.
4 Adapter Connections
80 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Note: This built-in service can be run at design time only; do not use it within an
Integration Server flow or Java service. You must run this service directly from Developer
or Designer by selecting the service and running it.
For details, see the Integration Server built-in services reference guide for your release.
See About this Guide for specific document titles.
To override a connection in a flow service
1 In the Pipeline Editor in Developer or Designer, invoke an adapter service from a
flow service. For more information on how to invoke adapter services from flow
services, see Using the Pipeline Editor to View and Set the msgBody on page 155.
2 In a flow service, you can use either the icon or the icon to override
connection parameters.
3 Use the icon to map the overrideConnection property from one service to the
overrideConnection property in another service. You map Pipeline Invariables to the
Service In overrideConnection fields in the input document.
The following example illustrates a link from the overrideConnection property in the
source or the Pipeline In of the Getexample service to the overrideConnection property
in the Service In of the Putexample service. The Pipeline In overrides the connection in
theService In, which means that the connection in the Getexample service overrides
the connection in the Putexample service. The Putexample service will now use the
connection, queue, and queue manager of the Getexample service.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 81
4 Adapter Connections
4 Use the icon to override the pipeline values of the overrideConnection property
fields in the service's Service In document.
For more information about linking and overriding properties between services
within the Pipeline Editor, see the Developer users guide or Designer Service
Development online help for your release. See About this Guide for specific
document titles.
Dynamically Changing a Service's Connection at Run Time
You can run a service using a connection other than the default connection that was
associated with the service when the service was created. To override the default, you
must code your flow to pass a value through the pipeline into a service's $connectionName
field.
For example, you have a flow whose purpose is to take input from one queue and direct
it to one of three output queues, each representing a department within your company -
billing, shipping, and personnel. Each document in the input queue contains a field
called Recipient. One WebSphere MQ service could act as a router, using the value in the
input document's Recipient field to set the value for $connectionName. Then the flow
would use $connectionName to dynamically pick a connection (output queue) to use to
send the input to the appropriate corporate department.
Keep in mind these restrictions when using dynamic connections:
The connection with which you override the default (that is, the value provided for
$connectionName) must be configured to use the same connection type as the default
connection.
The $connectionName field is present only in services that are:
Created with Developer 6.5 or later
Created with Developer 6.1 or earlier and edited with Developer 6.5 or later
Created with Designer
The adapter ignores the $connectionName field if you provide values for one or more
objects in the overrideConnection property.
For more information, see Programmatically Supply a Value for $connectionName at
Run Time on page 43.
Viewing WebSphere MQ Adapter Connection Parameters
You can view a connection's parameters from Integration Server Administrator or from
Developer or Designer.
4 Adapter Connections
82 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Viewing Connection Parameters Using Integration Server
Administrator
Perform the following procedure to view connection parameters with Integration Server.
To view the parameters for a WebSphere MQ Adapter connection using Integration Server
Administrator
1 In the Adapters menu in the navigation area of Integration Server Administrator, click
WebSphere MQ Adapter.
The Connections screen appears, listing all the current connections. You can control
the number of connections that are displayed on this screen. For more information,
see Controlling Pagination on page 51.
2 If you are using Integration Server 8.0 or later, you can sort information on the
Connections screen, click the Up and Down arrows at the top of the column you want
to sort.
3 If you are using Integration Server 8.0 or later, you can filter the list of connections as
follows:
a On the Connections screen, click Filter Connections.
b Type the criterion by which you want to filter into the Filter criteria box. Filtering is
based on the node name, not the connection alias. To locate all connections
containing specific alphanumeric characters, use asterisks (*) as wildcards. For
example, if you want to display all connections containing the string "abc", type
*abc* in the Filter criteria box.
c Click Submit. The Connections screen displays the connections that match the
filter criteria.
d To re-display all connections, click Show All Connections.
4 On the Connections screen, click the icon for the connection you want to see.
The View Connection screen displays the parameters for the connection. For
descriptions of the connection parameters, see Configuring WebSphere MQ Adapter
Connections on page 70.
5 Click Return to WebSphere MQ AdapterConnections to return to the main connections
screen.
Viewing Connection Parameters Using Developer or Designer
Perform the following procedure to view connection parameters with Developer or
Designer.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 83
4 Adapter Connections
To view the parameters for a WebSphere MQ Adapter connection using Developer or Designer
1 From the Developer or Designer navigation area, open the package and folder in
which the connection is located.
2 Double-click the connection you want to view.
The parameters for the connection appear in the Connection Information tab. For
descriptions of the connection parameters, see Configuring WebSphere MQ Adapter
Connections on page 70.
Editing WebSphere MQ Adapter Connections
If the login information changes, or if you want to redefine parameters that a connection
uses when connecting to a queue, you can update a connection's parameters using
Integration Server Administrator.
To edit a WebSphere MQ Adapter connection
1 In the Adapters menu in the navigation area of Integration Server Administrator, click
WebSphere MQ Adapter.
2 Make sure that the connection is disabled before editing. To disable the connection,
see Disabling WebSphere MQ Adapter Connections on page 85.
3 On the Connections screen, click the icon for the connection you want to edit.
The Edit Connection screen displays the current parameters for the connection.
Update the connection's parameters by typing or selecting the values you want to
specify.
For descriptions for the connection parameters, see Configuring WebSphere MQ
Adapter Connections on page 70.
Important! If you change the Queue Name parameter of the connection associated with
a multi-queue listener, you must also open the multi-queue listener for edit and save
the listener so that the adapter can re-create the listeners.
4 ClickSave Changes to save the connection and return to the Connections screen.
Copying WebSphere MQ Adapter Connections
You can copy an existing WebSphere MQ Adapter connection to create a new connection
with the same or similar connection properties without having to re-type or specify all of
the properties for the new connection. You copy adapter connections using Integration
Server Administrator.
4 Adapter Connections
84 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
To copy a WebSphere MQ Adapter connection
1 In the Adapters menu in the navigation area of Integration Server Administrator, click
WebSphere MQ Adapter.
2 On the Connections screen, click the icon for the connection you want to copy.
The Copy Connection screen displays the current parameters for the connection you
want to copy. Name the new connection and edit any connection parameters as
needed by typing or selecting the values you want to specify.
Note: When you copy a connection, the new connection does not save the password of
the original connection. You must enter and then retype the password before you can
save the new connection.
For descriptions of the connection parameters, see Configuring WebSphere MQ
Adapter Connections on page 70.
3 Click Save Connection to save the connection and return to the Connections screen.
Deleting WebSphere MQ Adapter Connections
If you no longer want to use a particular WebSphere MQ Adapter connection, you can
delete it by following the instructions in this section. You delete adapter connections
using Integration Server Administrator.
If you delete a WebSphere MQ Adapter connection, the adapter services and listeners
that are defined to use the connection will no longer work unless you change the
connection an adapter service uses.
You can assign a different connection to an adapter service and re-use the service. To do
this, you use the built-in webMethods function
pub.art.service:setAdapterServiceNodeConnection. For more information, see Programmatically
Change the Connection Associated with an Adapter Service at Design Time on page 43.
To delete a WebSphere MQ Adapter connection
1 In the Adapters menu in the navigation area of Integration Server Administrator, click
WebSphere MQ Adapter.
2 Make sure that the connection is disabled before deleting. To disable the connection,
see Disabling WebSphere MQ Adapter Connections on page 85.
3 On the Connections screen, click for the connection you want to delete.
Integration Server deletes the adapter connection.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 85
4 Adapter Connections
Enabling WebSphere MQ Adapter Connections
A WebSphere MQ Adapter connection must be enabled before you can configure any
adapter service using the connection, or before an adapter service can use the connection
at run time. You enable adapter connections using Integration Server Administrator.
Note: When you reload a package that contains enabled connections, the connections will
automatically be enabled when the package reloads. If the package contains connections
that are disabled, they will remain disabled when the package reloads.
To enable a WebSphere MQ Adapter connection
1 In the Adapters menu in the navigation area of Integration Server Administrator, click
WebSphere MQ Adapter.
2 On the Connections screen, click No in the Enabledcolumn for the connection you want
to enable.
Integration Server Administrator enables the adapter connection and displays and
Yes in the Enabledcolumn.
Disabling WebSphere MQ Adapter Connections
WebSphere MQ Adapter connections must be disabled before you can edit or delete the
connections. You disable the adapter connections using Integration Server Administrator.
To disable a WebSphere MQ Adapter connection
1 In the Adapters menu in the navigation area of Integration Server Administrator, click
WebSphere MQ Adapter.
2 On the Connections screen, click Yes in the Enabled column for the connection that
you want to disable.
Integration Server Administrator disables the adapter connection and you see a No in
the Enabled column.
Configuring SSL Connections
To establish a Secure Socket Layer (SSL) connection between an Integration Server and a
WebSphere MQ Server, each server must have access to its own private key and its
partner's certificates.
This section provides instructions to enable WebSphere MQ Adapter to communicate
with a WebSphere MQ SSL.
Step 1: Configure the Integration Server Property on page 86
4 Adapter Connections
86 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Step 2: Apply Private and Public Keys on page 86
Step 3: Apply Private Key and Certificates for the Adapter Connection on page 87
Step 4: Configure the Cipher Spec Property on page 88
Step 1: Configure the Integration Server Property
To enable an SSL connection in Integration Server
1 In Integration Server Administrator, select Settings > Extended.
2 Set the watt.WmMQAdapter.SSL.Support property to true. If the property does not exist,
then add it.
Step 2: Apply Private and Public Keys
This step obtains a private key - public key pair for the Queue Manager by applying the
private key certificate to the Queue Manager and the corresponding public key certificate
to Integration Server.
Obtaining the private key certificate for the Queue Manager should be obtained from a
third party Certificate Authority (CA).
Applying Private Key to Queue Manager
Perform the following procedure to apply the private key to the queue manager.
To apply the private key to the Queue Manager
In WebSphere MQ 5.3, select the Manage SSL Certificates options in WebSphere MQ
Explorer. Select the certificate and assign it to the Queue Manager.
Note: Be sure to use the Assign option and not the Add option. A certificate can only be
assigned if it contains a private key.
In WebSphere MQ 6.0 and 7.x:
a Use the IBM Key Management Utility to import the private key of the Queue
Manager into the IBM keystore file.
b Specify the name of the keystore file against the Queue Manager. To do so, select
the Queue Manager > SSL > Key Repository property in the WebSphere MQ Explorer.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 87
4 Adapter Connections
Applying Public Key to Integration Server
Each private key assigned to a Queue Manager will have a corresponding public key.
Assign the corresponding public key to Integration Server. If the public key is not
supplied by the CA, you can generate one from a private key using any Certificate
Management Tool.
To apply the public key to Integration Server
1 Import the public key certificate into the lib\security\cacerts file of the Integration
Server jvm. You can import the certificate using java keytool utility (-import option).
2 Ensure that the path of cacerts file and the password are included as jvm parameters,
in the server.bat.
For example:
-Djavax.net.ssl.trustStore=D:\IntegrationServer\jvm\lib\security\cacerts
-Djavax.net.ssl.trustStorePassword=changeit
Note: This step might not be required for all jvms.
Step 3: Apply Private Key and Certificates for the Adapter Connection
You can obtain the private key certificate for the WebSphere MQ Adapter connection
from a third party Certificate Authority (CA).
OR
A private key - public key pair can be generated using java keytool (-genkey option).
Applying Private Key to Adapter Connection
Perform the following procedure to apply the private key to an adapter connection.
To apply the private key to an adapter connection
1 Import the certificate obtained from the CA to a java keystore. Make sure that the
private key is also imported.
Note: If the private key - public key certificate is created using java keytool, this step is
not required.
4 Adapter Connections
88 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
2 Specify the following parameters in the MQ Adapter connection properties:
SSL Keystore file: Java keystore file name (created above). Complete path of the file
is required.
SSL Keystore Password: Password for the keystore.
Retype SSL Keystore Password: Retype the keystore password that you just entered.
Applying Public Key to Queue Manager
Each private key assigned to Integration Server will have a corresponding public key.
Assign the corresponding public key to the Queue Manager. If the public key is not
supplied by the CA, you can generate one from a private key using any Certificate
Management Tool.
OR
From a java keystore, the public key can be generated using java keytool (-export option).
To apply the public key to the Queue Manager
In WebSphere MQ 5.3, select Manage SSL Certificates options in the WebSphere MQ
Explorer. Use the Add option.
In WebSphere MQ 6.0 and 7.x:
a Use the IBM Key Management Utility to import the public key of the Queue
Manager into the IBM keystore file.
b Specify the name of the keystore file against the Queue Manager. To do so, select
the Queue Manager > SSL > Key Repository property in the WebSphere MQ Explorer.
Step 4: Configure the Cipher Spec Property
Perform the following procedure to configure the Cipher Spec property.
To configure the Cipher Spec property
1 Select Queue Manager > Advanced > Channels > Server Connection Channel > Property > SSL >
CipherSpec property in the WebSphere MQ Explorer.
2 Navigate to the MQ Adapter connection properties. Select the same SSL Cipher Spec
property as selected in WebSphere MQ Explorer.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 89
5 Adapter Services
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Before Configuring or Managing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Using Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Configuring Put Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Configuring Get Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Configuring Peek Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Configuring Request/Reply Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Configuring Inquire Queue Manager/Queue Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Configuring PCF Command Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Throwing Exceptions on Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Working with Messages in a Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Working with Messages in a Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Using the Pipeline Editor to View and Set the msgBody . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Testing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Viewing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Editing Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Deleting Adapter Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Enabling Automatic Data Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Reloading Adapter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
5 Adapter Services
90 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Overview
This chapter describes how to configure and manage WebSphere MQ Adapter services.
For detailed descriptions of the available WebSphere MQ Adapter services, see Adapter
Services on page 26.
Before Configuring or Managing Adapter Services
Perform the following tasks before configuring or managing adapter services.
Before you configure or manage an adapter service
1 Start Integration Server and Integration Server Administrator, if they are not already
running.
2 Make sure you have webMethods administrator privileges so that you can access the
WebSphere MQ Adapter administrative screens. For more information about setting
user privileges, see the Integration Server administration guide for your release. See
About this Guide for specific document titles.
3 Using Integration Server Administrator, make sure that the WmMQAdapter package
is enabled. For instructions, see Enabling Packages on page 61.
4 Using Integration Server Administrator, configure an adapter connection to use with
the adapter service. For instructions, see Configuring WebSphere MQ Adapter
Connections on page 70.
5 Start webMethods Developer or Software AG Designer if it is not already running.
Note: If you are using Developer 6.1 or later, use the Edit perspective for all
procedures unless stated otherwise. If you are using Designer, use the Service
Development perspective. For more information, see the Developer users guide or
Designer Service Development online help for your release. See About this Guide
for specific document titles.
6 Make sure that you enable the Automatic data validation. For detailed instructions on
how to enable automatic data validation, see Enabling Automatic Data Validation
on page 158.
7 Using Developer or Designer, create a user-defined package to contain the service, if
you have not already done so. When you configure adapter services, you should
always define them in user-defined packages rather than in the WmMQAdapter
package. For more information about managing packages for the adapter, see
Package Management on page 59.
8 In order to run an adapter service that connects to a WebSphere MQ queue, you must
ensure that the correct permissions are set for the user. For information about setting
permissions, see Setting Permissions in WebSphere MQ on page 23.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 91
5 Adapter Services
Using Adapter Services
The following table lists the tasks required to use adapter services:
Configuring Put Services
The Put service delivers a message to a specified queue. For more information about Put
services, see Put Services on page 28. You configure WebSphere MQ Adapter services
using Developer or Designer.
To configure a Put service
1 Review the steps in Before Configuring or Managing Adapter Services on page 90.
2 Start Developer or Designer.
3 Perform one of the following:
If you are using Developer, select File > New > Adapter Service and click Next.
If you are using Designer, perform the following:
Task Description Use this tool...
1 Configure an adapter connection. For details,
see Adapter Connections on page 69.
Integration Server
Administrator
2 Select the appropriate adapter service template
and configure the adapter service. Refer to the
appropriate service section in this chapter for
more information on configuring adapter
services.
Developer or Designer
3 If you plan to use an Integration Server flow or
Java service to invoke the adapter service,
design the flow or Java service to use this
adapter service. For details, see the Developer
users guide or Designer Service Development
online help for your release. See About this
Guide for specific document titles.
To refer to an example of invoking adapter
services from flow services or java services, see
Using the Pipeline Editor to View and Set the
msgBody on page 155.
Developer or Designer
4 Manage the adapter service. See Package
Management on page 59 and Logging and
Exception Handling on page 197.
Developer or Designer and
Integration Server
Administrator
5 Adapter Services
92 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
i Right-click the package in which the service should be contained and select
New > Adapter Service.
ii Select the parent namespace and type a name for the adapter service.
iii Click Next.
4 Select WebSphere MQ Adapter as the adapter type and click Next.
5 Select the appropriate Adapter Connection Name and click Next.
Important! If you are using the adapter with Integration Server 8.0 SP1 or earlier,
adapter services cannot use connections that are also used for adapter listeners.
6 From the list of available templates, select the Put Service template and do one of the
following:
If you are using Developer, click Next, select a package and folder to contain the
service, type a unique name for the service, and click Finish.
If you are using Designer, click Finish.
The adapter service editor for the Put service appears. You can select the Adapter
Settings tab at any time to confirm adapter service properties such as Adapter Name,
Adapter Connection Name, and Adapter Service Template, as necessary.
7 Select the Put Service tab to identify message processing features to use with this
adapter service.
Specify values for the following fields:
Field Description/Action
Dead Letter Queue
Name
The name of the queue that will contain any messages that
could not reach their destination.
If you do not specify a value for this field, then
WebSphere MQ Adapter sends the message to the system
dead letter queue (SYSTEM.DEAD.LETTER.QUEUE) for that
queue manager.
Dead Letter Queue
Manager Name
The name of the queue manager for the dead letter queue.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 93
5 Adapter Services
Headers to include in
Dead Letter Message
Select which headers to include in the message sent to the
dead letter queue:
None Does not include any headers along with the original
payload in the message sent to the dead letter queue.
DLH Includes only the DLH header along with the original
payload in the message sent to the dead letter queue.
MQMD Includes only the MQMD header along with the
original payload in the message sent to the dead letter
queue.
DLH_&_MQMD Includes both DLH and MQMD headers
along with the original payload in the message sent to the
dead letter queue.
Default: DLH_&_MQMD
Note: If you are using a Put service configured using
WebSphere MQ Adapter, the service refers to the watt
property watt.WmMQAdapter.deadLetterMessageHeaders. If this watt
property is not set, then WebSphere MQ Adapter sets the
Headers to include in Dead Letter Message parameter to the
default value DLH_&_MQMD.
Backout Threshold The number of times the service will attempt to send the
message before it is sent to the dead letter queue.
For example, specify 2 to attempt to send the message twice.
Default: 1
Throw Exception on
Failure?
Select whether the service throws an exception on failure:
Checked Throws an exception when the adapter service
returns error codes.
Unchecked Returns any error codes or error messages to
the service's output signature.
Default: Checked
Field Description/Action
5 Adapter Services
94 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
8 Select the MQMD Header tab to specify which msgHeader property fields and constant
values the service will use.
Use the following icons to manage the rows on the MQMD Header tab:
To define new input or output field names, select the icon (or the Fill in all
rows to the icon).
To change the order of the input or output fields to ensure the parameters are
parsed in the correct order, use the or icons.
To delete any input field names or output field names, use the icon.
The msgHeader property fields that you select from the Input Field Name column
appear on the Input/Output tab in the Input signature for this adapter service. The
msgHeader property fields that you select from the Output Field Name column appear
on the Input/Output tab in the Output signature for this adapter service.
You can add the following msgHeader property fields to the Input Field Name column
and the Output Field Name column. In the Constant Value column, specify values for the
default property fields. Also, you can override the property fields at run time, using
the Pipeline Editor. However, you cannot modify certain "output only" properties,
such as PutDate and PutTime.
msgHeader Property Data Type Maximum Field Length for Constant Value
AccountingToken* String 32 alphanumeric single-byte characters
AccountingTokenByteArray* Byte Array 32 bytes
ApplIdentityData String 32 alphanumeric single-byte characters
ApplOriginData String 4 alphanumeric single-byte characters
BackoutCount String 4 digits
CodedCharSetId String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of MQCCSI_Q_MGR.
CorrelId* String 24 alphanumeric single-byte characters
CorrelationIdByteArray* Byte Array 24 bytes
Encoding String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of 00273 - Native.
Expiry String 4 digits
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 95
5 Adapter Services
Feedback String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of MQFB_NONE.
Format String 8 alphanumeric single-byte characters
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of (NONE).
GroupId* String 24 alphanumeric single-byte characters
GroupIdByteArray* Byte Array 24 bytes
MsgFlags String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of NONE.
MsgId* String 24 alphanumeric single-byte characters
MsgIdByteArray* Byte Array 24 bytes
MsgType String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of Datagram.
MsgSeqNumber String 4 digits
Offset String 4 digits
OriginalLength String 4 digits
Persistence String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of Not Persistent.
msgHeader Property Data Type Maximum Field Length for Constant Value
5 Adapter Services
96 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Note: An asterisk * indicates that you can enter these properties either as a string or as
a byte array. For example, AccountingToken and AccountingTokenByteArray refer to the
same msgHeader property. If you specify values for both properties, then the byte
array value will be used.
9 Select the JMS Properties tab to identify the optional JMS property fields for the
adapter service. The JMS property fields appear on the Input/Output tab in the Input
signature document for this adapter service.
Use the following icons to manage the rows on the JMS Properties tab:
To define new JMS property fields, select the icon (or the Fill in all rows to the
icon).
To change the order of JMS property fields to ensure the parameters are parsed in
the correct order, use the or icons.
To delete any JMS property fields, use the icon.
You can add the following optional JMS property fields:
Priority String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value based on the default
priority of the queue.
PutApplName String 24 alphanumeric single-byte characters
PutApplType String 4 digits
PutDate String 8 digits
PutTime String 8 digits
ReplytoQueueMgr String 48 alphanumeric single-byte characters
ReplyToQ String 48 alphanumeric single-byte characters
Report String 4 digits
UserIdentifier String 12 alphanumeric single-byte characters
JMS Property Data Type
JMSDestination String
JMSExpiration String
JMSPriority String
msgHeader Property Data Type Maximum Field Length for Constant Value
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 97
5 Adapter Services
Note: An "X" in the JMS property name indicates that the property is provider-specific.
The remaining JMS properties are generic, delivered by any JMS provider.
You can also add your own folders and properties to the JMS Properties.
Use the following icons to manage the rows for User-Defined Properties on the JMS
Properties tab:
To define new folders and properties, select the icon.
Enter the new folder and property. For example, enter "jms.usr.usr1". The "jms"
and "usr" are the names of the folders and "usr1" is the name of the property.
All the folders and properties you add will be under JMSProperties as part of the
input signature of the adapter service.
JMSDeliveryMode String
JMSCorrelationID String
JMSCorrelationIDByteArray Byte Array
JMSReplyTo String
JMSType String
JMSMessageID String
JMSTimestamp String
JMSRedelivered String
JMSXGroupID String
JMSXGroupIdByteArray Byte Array
JMSXGroupSeq String
JMSXUserID String
JMSXAppID String
JMSXDeliveryCount String
MCDMessageDomain String
MCDMessageSet String
MCDMessageFormat String
JMS Property Data Type
5 Adapter Services
98 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Note: The property name has to be prefixed with a folder name. You cannot use
"JMSProperties" and "mcd" as the first folder name.
The property name has to be prefixed with a folder name. You cannot use
"JMSProperties" and "mcd" as the first folder name.
To change the order of User-Defined property fields to ensure the parameters are
parsed in the correct order, use the or icons.
To delete any User-Defined property fields, use the Remove row icon .
The Input/Output, Settings, Audit, Permissions, and Results tabs apply to all services that
you configure using versions of Developer earlier than 6.1. For more information, see
the Developer users guide for your release. See About this Guide for specific
document titles.
When using Designer or Developer 6.1 or later, Designer or Developer contains only
the Adapter Settings and Input/Output tabs. The information from the Audit and
Permissions tabs appears in the Properties panel, and the information from the Results
tab appears in the Results panel in Developer or the Service Results panel in Designer.
For more information, see the Developer users guide or Designer Service
Development online help for your release. See About this Guide for specific
document titles.
10 From the File menu, select Save.
Using Put Services
The input and output signatures for the Put service are located on the Input/Output tab of
Developer or Designer.
Input Signature Properties for the Put Service
When you configure the Put service, the following overrideConnection properties
automatically appear in the input signature of the Put service on the Input/Output tab:
Note: An asterisk * indicates that if you set the dynamicQueuePrefix at run time, then you
also need to set the queueName.
Note: A plus + indicates that there is a description for this property below this table.
Property Data Type
queueManagerName String
hostName String
port String
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 99
5 Adapter Services
For a description of each data type, see the list of parameters in Configuring
WebSphere MQ Adapter Connections on page 70.
When you configure a Put service, useLocalQueueManager is in the input signature under
override connection parameter. You can set the value for useLocalQueueManager in the
Pipeline Editor. If you add a value other than Yes or No in this field, then WebSphere MQ
Adapter sets the value to No.
Yes The Put service uses the existing connection (configured for this service) to send
messages to the specified queue on the remote queue manager.
No The Put service creates a new connection to the remote queue manager and sends
the message to the specified queue on the remote queue manager.
For proper operation, the local queue manager needs to know the route to the remote
location (that is, the transmission queue). When an application puts messages that are
destined for a remote queue manager, the local queue manager adds a transmission
header to the message before putting the message on the transmission queue with the
same name as the remote queue manager. The transmission header contains the name of
the destination queue and queue manager, that is, the addressing information. The
receiving channel removes the transmission header and uses the information in it to
locate the destination queue. To configure your local queue and remote queue managers:
1 Define a Transmission queue on the local queue manager. The transmission queue
name must be same as the remote queue manager name.
2 Define a Sender channel at the local queue manager and specify the transmission
queue to be used. Use the transmission queue defined in the previous step.
3 Define a Receiver channel at the remote queue manager. The receiver channel name
must be same as the sender channel name.
Tip! For more information on configuring your local queue and remote queue managers,
see WebSphere MQ Intercommunication.pdf (SC34-6587). Refer to "Chapter 1: Concepts of
Intercommunication" and "Chapter 2: Making Your Applications Communicate" for
instructions on enabling communication between two Queue Managers.
The following properties, except for msgBody and msgBodyByteArray properties, are
passed from the Put Service tab in Developer or Designer to the input signature of the Put
service:
channel String
CCSID String
queueName* String
dynamicQueuePrefix* String
useLocalQueueManager+ String
encoding String
Property Data Type
5 Adapter Services
100 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
WebSphere MQ Adapter passes the following optional input fields from the JMS
Properties tab in Developer or Designer to the input signature of the Put service. The data
types for the JMS Properties are documented as they appear in Developer or Designer.
Note: All the User-Defined Properties specified will also be passed to the input signature.
Property Description
deadLetterQueueName A String that contains the name of the queue that will contain
any messages that could not reach their destination.
You set the value of this property in the Pipeline Editor, which
overwrites any value set on the Put Service tab.
deadLetterQueueManag
erName
A String that contains the name of the queue manager for the
dead letter queue.
You set the value of this property in the Pipeline Editor, which
overwrites any value set on the Put Service tab.
deadLetterMessageHea
ders
A String that contains the headers to include in the message
sent to the dead letter queue.
You set the value of this property in the Pipeline Editor, which
overwrites any value set on the Put Service tab.
None Includes any headers along with the original payload
in the message sent to the dead letter queue.
DLH Includes only the DLH header along with the original
payload in the message sent to the dead letter queue.
MQMD Includes only the MQMD header along with the
original payload in the message sent to the dead letter
queue.
DLH_&_MQMD Includes both DLH and MQMD headers
along with the original payload in the message sent to the
dead letter queue.
Default: DLH_&_MQMD
msgBody The contents of the payload.
Note: The msgBody is only available via the input signature for
the Put service, located on the Input/Output tab.
msgBodyByteArray The contents of the payload in a byte array.
Note: The msgBodyByteArray is only available via the input
signature for the Put service, located on the Input/Output tab.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 101
5 Adapter Services
For a complete description of the JMS Property properties and their uses, refer to your
JMS provider's user documentation.
Note: An "X" in the JMS property name indicates that the property is provider specific.
The remaining JMS properties are generic, delivered by any JMS provider.
WebSphere MQ Adapter passes the following optional input fields from the MQMD Header
tab in Developer or Designer to the input signature of the Put service. The data types for
the msgHeader properties are documented as they appear in Developer or Designer.
For a complete description of the msgHeader properties and their uses, refer to IBM's
WebSphere MQ user documentation.
JMS Property Data Type
JMSDestination String
JMSExpiration String
JMSPriority String
JMSDeliveryMode String
JMSCorrelationID String
JMSCorrelationIDByteArray String
JMSReplyTo String
JMSType String
JMSMessageID String
JMSTimestamp String
JMSRedelivered String
JMSXGroupID String
JMSXGroupIdByteArray String
JMSXGroupSeq String
JMSXUserID String
JMSXAppID String
JMSXDeliveryCount String
MCDMessageDomain String
MCDMessageSet String
MCDMessageFormat String
msgHeader Property Data Type
AccountingToken* String
5 Adapter Services
102 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
AccountingTokenByteArray* Object
ApplIdentityData String
ApplOriginData String
BackoutCount String
CodedCharSetId String
CorrelId* String
CorrelationIdByteArray* Object
Encoding String
Expiry String
Feedback String
Format String
GroupId* String
GroupIdByteArray* Object
MsgFlags String
MsgId* String
MsgIdByteArray* Object
MsgType String
MsgSeqNumber String
Offset String
OriginalLength String
Persistence String
Priority String
PutApplName String
PutApplType String
PutDate String
PutTime String
ReplytoQueueMgr String
ReplyToQ String
Report String
UserIdentifier String
msgHeader Property Data Type
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 103
5 Adapter Services
Note: An asterisk * indicates that you can enter these properties either as a string or as a
byte array. For example, AccountingToken and AccountingTokenByteArray refer to the same
msgHeader property. If you specify values for both properties, then the byte array value
will be used.
Output Signature Properties for the Put Service
When you configure the Put service, the following output properties automatically
appear in the output signature of the Put service on the Input/Output tab:
When you configure the Put service, the following overrideConnection properties
automatically appear in the output signature of the Put service on the Input/Output tab:
Note: An asterisk * indicates that if you set the dynamicQueuePrefix at run time, then you
also need to set the queueName.
For a description of each data type, see the list of parameters in Configuring
WebSphere MQ Adapter Connections on page 70.
WebSphere MQ Adapter passes the following optional output fields from the MQMD
Header tab in Developer or Designer to the output signature of the Put service. The data
types for the msgHeader properties are documented as they appear in Developer or
Designer.
Property Description
reasonCode A String that contains the reasonCode of the MQ Series
operation.
conditionCode A String that contains the conditionCode of the MQ Series
operation.
errorMsg A String that appears in the output signature only when the
adapter service fails.
Property Data Type
queueManagerName String
hostName String
port String
channel String
CCSID String
queueName* String
dynamicQueuePrefix* String
encoding String
5 Adapter Services
104 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
For a complete description of the msgHeader properties and their uses, refer to IBM's
WebSphere MQ user documentation.
msgHeader Property Data Type
AccountingToken String
AccountingTokenByteArray Object
ApplIdentityData String
ApplOriginData String
BackoutCount String
CodedCharSetId String
CorrelId String
CorrelationIdByteArray Object
Encoding String
Expiry String
Feedback String
Format String
GroupId String
GroupIdByteArray Object
MsgFlags String
MsgId String
MsgIdByteArray Object
MsgType String
MsgSeqNumber String
Offset String
OriginalLength String
Persistence String
Priority String
PutApplName String
PutApplType String
PutDate String
PutTime String
ReplytoQueueMgr String
ReplyToQ String
Report String
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 105
5 Adapter Services
Configuring Get Services
The Get service retrieves and removes a message from a specified queue. For more
information about Get services, see Get Services on page 30. You configure
WebSphere MQ Adapter services using Developer or Designer.
To configure a Get service
1 Review the steps in Before Configuring or Managing Adapter Services on page 90.
2 Start Developer or Designer.
3 Perform one of the following:
If you are using Developer, select File > New > Adapter Serviceand click Next.
If you are using Designer, perform the following:
i Right-click the package in which the service should be contained and select
New > Adapter Service.
ii Select the parent namespace and type a name for the adapter service.
iii Click Next.
4 Select WebSphere MQ Adapter as the adapter type and click Next.
5 Select the appropriate Adapter Connection Name and click Next.
Important! If you are using the adapter with Integration Server 8.0 SP1 or earlier,
adapter services cannot use connections that are also used for adapter listeners.
6 From the list of available templates, select the Get Service template and do one of the
following:
If you are using Developer, click Next, select a package and folder to contain the
service, type a unique name for the service, and click Finish.
If you are using Designer, click Finish.
The adapter service editor for the Get service appears. You can select the Adapter
Settings tab at any time to confirm adapter service properties such as Adapter Name,
Adapter Connection Name, and Adapter Service Template, as necessary.
7 Select the Get Service tab to identify message processing features to use with this
adapter service.
Specify values for the following fields:
UserIdentifier String
msgHeader Property Data Type
5 Adapter Services
106 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Field Description/Action
Wait Interval (msec) The time period that the service waits for a message to appear
on the queue. Enter this value in milliseconds.
Default: 60000
Dead Letter Queue
Name
The name of the queue that will contain any messages that
could not reach their destination.
If you do not specify a value for this field, then
WebSphere MQ Adapter does not move the message to the
dead letter queue if the message could not reach its
destination.
Dead Letter Queue
Manager Name
The name of the queue manager for the dead letter queue.
Headers to include in
Dead Letter Message
Select which headers to include in the message sent to the
dead letter queue:
None Includes any headers along with the original
payload in the message sent to the dead letter queue.
DLH Includes only the DLH header along with the original
payload in the message sent to the dead letter queue.
MQMD Includes only the MQMD header along with the
original payload in the message sent to the dead letter
queue.
DLH_&_MQMD Includes both DLH and MQMD headers
along with the original payload in the message sent to the
dead letter queue.
Default: DLH_&_MQMD
Note: If you are using a Get service configured using
WebSphere MQ Adapter, the service refers to the watt
property watt.WmMQAdapter.deadLetterMessageHeaders. If this watt
property is not set, then WebSphere MQ Adapter sets the
Headers to include in Dead Letter Message parameter to the
default value DLH_&_MQMD.
Backout Threshold The number of times the service will attempt to get the
message before it is sent to the dead letter queue.
For example, specify 2 to attempt to get the message twice.
Default: 1
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 107
5 Adapter Services
Open Queue in
Shared Mode?
Select how the queue is opened:
Checked In shared mode, allows simultaneous access to
the queue by other applications.
Unchecked In exclusive mode, prevents simultaneous
access to the queue by other applications.
Default: Checked
Convert Application
Data?
Select whether the service converts the message to the local
character set and encoding:
Checked Converts the messages read using this service to
the local character set and encoding.
Unchecked Does not convert the messages read using this
service to the local character set and encoding.
Default: Checked
Note: If the property is checked and the message format does
not match the local character set and encoding, a warning
message appears.
Note: If you are using a Get service configured using
WebSphere MQ Adapter, the default value is Checked.
Throw Exception on
Failure?
Select whether the service throws an exception on failure:
Checked Throws an exception when the adapter service
returns error codes.
Unchecked Returns any error codes or error messages to
the service's output signature.
Default: Checked
Field Description/Action
5 Adapter Services
108 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
8 Select the MQMD Header tab to specify which selectionCriteria property fields and
constant values the service will use. Selection criteria refers to the specific values that
must be present in the header of the actual message in order for the adapter to
retrieve it from the WebSphere MQ.
The selectionCriteria property fields that you select appear on the Input/Output tab in
the Input signature for this adapter service. Use the following icons to manage the
rows on the MQMD Header tab:
To define new selectionCriteria property fields, select the icon (or the Fill in all
rows to the icon).
To ensure the parameters are parsed in the correct order, use the or icons to
change the order of the selectionCriteria property fields or the output field names.
To delete any selectionCriteria property fields or output field names, use the
icon.
In the Constant Value column, specify default values for any of the property fields. You
can override these values at run time. You can add the following optional
selectionCriteria property fields:
Note: An asterisk * indicates that you can enter these properties either as a string or as
a byte array. For example, CorrelId and CorrelationByteArray refer to the same
msgHeader property. If you specify values for both properties, then the byte array
value will be used.
From the MQMD Header tab, you can also select which msgHeader property fields the
service will use. The msgHeader property fields that you select appear on the
Input/Output tab in the Output signature for this adapter service.
selectionCriteria
Property Data Type Maximum Field Length for Constant Value
CorrelId* String 24 alphanumeric single-byte characters
CorrelationByteArray* Byte Array 24 bytes
GroupId* String 24 alphanumeric single-byte characters
GroupIdByteArray* Byte Array 24 bytes
MsgId* String 24 alphanumeric single-byte characters
MsgIdByteArray* Byte Array 24 bytes
MsgSeqNumber String 4 digits
Offset String 4 digits
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 109
5 Adapter Services
Use the following icons to manage rows on the MQMD Headertab:
To define new msgHeader property fields, select the icon (or the Fill in all rows
to the icon).
To ensure the parameters are parsed in the correct order, use the or icons to
change the order of the msgHeader property fields or the output field names.
To delete any msgHeader property fields or output field names, use the icon.
You can add the following optional msgHeader property fields to the Output Field
Name column:
msgHeader Property Data Type
AccountingToken String
AccountingTokenByteArray Byte Array
ApplIdentityData String
ApplOriginData String
BackoutCount String
CodedCharSetId String
CorrelId String
CorrelationIdByteArray Byte Array
Encoding String
Expiry String
Feedback String
Format String
GroupId String
GroupIdByteArray Byte Array
MsgFlags String
MsgId String
MsgIdByteArray Byte Array
MsgType String
MsgSeqNumber String
Offset String
OriginalLength String
Persistence String
Priority String
5 Adapter Services
110 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
9 Select the JMS Properties tab to identify the optional JMS property fields for the
adapter service. The JMS property fields on the Input/Output tab in the Output signature
document for this adapter service.
Use the following icons to insert or delete rows:
To define new JMS property fields, select the icon (or the Fill in all rows to the
icon).
To change the order of JMS property fields to ensure the parameters are parsed in
the correct order, use the or icons.
To delete any JMS property fields, use the icon.
You can add the following optional JMS property fields:
PutApplName String
PutApplType String
PutDate String
PutTime String
ReplytoQueueMgr String
ReplyToQ String
Report String
UserIdentifier String
JMS Property Data Type
JMSDestination String
JMSExpiration String
JMSPriority String
JMSDeliveryMode String
JMSCorrelationID String
JMSCorrelationIDByteArray Byte Array
JMSReplyTo String
JMSType String
JMSMessageID String
JMSTimestamp String
JMSRedelivered String
JMSXGroupID String
msgHeader Property Data Type
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 111
5 Adapter Services
Note: An "X" in the JMS property name indicates that the property is provider specific.
The remaining JMS properties are generic, delivered by any JMS provider.
You can also add your own folders and properties to the JMS Properties.
Use the following icons to manage the rows for User-Defined Properties on the JMS
Properties tab:
To define new folders and properties, select the icon.
Enter the new folder and property. For example, enter "jms.usr.usr1". The "jms"
and "usr" are the names of the folders and "usr1" is the name of the property.
All the folders and properties you add will be under JMSProperties as part of the
output signature of the adapter service.
Note: The property name has to be prefixed with a folder name. You cannot use
"JMSProperties" and "mcd" as the first folder name.
To change the order of User-Defined property fields to ensure the parameters are
parsed in the correct order, use the or icons.
To delete any User-Defined property fields, use the icon.
The Input/Output, Settings, Audit, Permissions, and Results tabs apply to all services that
you configure using versions of Developer earlier than 6.1. For more information, see
the Developer users guide for your release. See About this Guide for specific
document titles.
When using Designer or Developer 6.1 or later, Designer or Developer contains only
the Adapter Settings and Input/Output tabs. The information from the Audit and
Permissions tabs appears in the Properties panel, and the information from the Results
tab appears in the Results panel (in Developer) or the Service Results panel (in
JMSXGroupIdByteArray Byte Array
JMSXGroupSeq String
JMSXUserID String
JMSXAppID String
JMSXDeliveryCount String
MCDMessageDomain String
MCDMessageSet String
MCDMessageFormat String
JMS Property Data Type
5 Adapter Services
112 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Designer). For more information, see the Developer users guide or Designer Service
Development online help for your release. See About this Guide for specific
document titles.
10 From the File menu, select Save.
Using Get Services
The input and output signatures for the Get service are located on the Input/Output tab of
Developer or Designer.
Input Signature Properties for the Get Service
When you configure the Get service, the following overrideConnection properties
automatically appear in the input signature of the Get service on the Input/Output tab:
Note: An asterisk * indicates that if you set the dynamicQueuePrefix at run time, then you
also need to set the queueName.
For a description of each data type, see the list of parameters in Configuring
WebSphere MQ Adapter Connections on page 70.
The following properties are passed from the Get Service tab in the Developer or Designer
to the input signature of the Get service:
Property Data Type
queueManagerName String
hostName String
port String
channel String
CCSID String
queueName* String
dynamicQueuePrefix* String
encoding String
Property Description
waitInterval The time period that the service waits for a message to appear
on the queue. Enter this value in milliseconds.
You set the value of this Integer in the Pipeline Editor, which
overwrites the value set on the Get Service tab.
Default: 60000
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 113
5 Adapter Services
The WebSphere MQ Adapter passes the following optional input properties from the
MQMD Header tab in Developer or Designer to the input signature of the Get service. The
data types for the selectionCriteria properties are documented as they appear in
Developer or Designer.
Also, if values are specified for these properties, then WebSphere MQ Adapter will only
receive messages from the queue that match the specified criteria. For a complete
description of the selectionCriteria properties and their uses, refer to IBM's WebSphere
MQ user documentation.
deadLetterQueueName A String that contains the name of the queue that will contain
any messages that could not reach their destination.
You set the value of this property in the Pipeline Editor, which
overwrites any value set on the Get Service tab.
deadLetterQueueMana
gerName
A String that contains the name of the queue manager for the
dead letter queue.
You set the value of this property in the Pipeline Editor, which
overwrites any value set on the Get Service tab.
deadLetterMessageHe
aders
A String that contains the headers to include in the message
sent to the dead letter queue.
You set the value of this property in the Pipeline Editor, which
overwrites any value set on the Get Service tab.
None Includes any headers along with the original payload
in the message sent to the dead letter queue.
DLH Includes only the DLH header along with the original
payload in the message sent to the dead letter queue.
MQMD Includes only the MQMD header along with the
original payload in the message sent to the dead letter
queue.
DLH_&_MQMD Includes both DLH and MQMD headers along
with the original payload in the message sent to the dead
letter queue.
Default: DLH_&_MQMD
selectionCriteria Property Data Type
CorrelId String
CorrelationIdByteArray Object
GroupId String
GroupIdByteArray Object
Property Description
5 Adapter Services
114 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Output Signature Properties for the Get Service
When you configure the Get service, the following output properties automatically
appear in the output signature of the Get service on the Input/Output tab:
When you configure the Get service, the following overrideConnection properties
automatically appear in the output signature of the Get service on the Input/Output tab:
Note: An asterisk * indicates that if you set the dynamicQueuePrefix at run time, then you
also need to set the queueName.
MsgId String
MsgIdByteArray Object
MsgSeqNumber String
Offset String
Property Description
msgBody The contents of the payload.
Note: The msgBody is only available via the output signature for
the Get service, located on the Input/Output tab.
msgBodyByteArray The contents of the payload in a byte array.
Note: The msgBodyByteArray is only available via the output
signature for the Get service, located on the Input/Output tab.
reasonCode A String that contains the reasonCode of the MQ Series
operation.
conditionCode A String that contains the conditionCode of the MQ Series
operation.
errorMsg A String that appears in the output signature only when the
adapter service fails.
Property Data Type
queueManagerName String
hostName String
port String
channel String
selectionCriteria Property Data Type
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 115
5 Adapter Services
For a description of each data type, see the list of parameters in Configuring
WebSphere MQ Adapter Connections on page 70.
WebSphere MQ Adapter passes the following optional output properties from the JMS
Properties tab in Developer or Designer to the output signature of the Get service. The
data types for the JMS Properties are documented as they appear in Developer or
Designer.
Note: All the User-Defined Properties specified will also be passed to the output
signature.
For a complete description of the JMS Property properties and their uses, refer to your
JMS provider's user documentation.
CCSID String
queueName* String
dynamicQueuePrefix* String
encoding String
JMS Properties Data Type
JMSDestination String
JMSExpiration String
JMSPriority String
JMSDeliveryMode String
JMSCorrelationID String
JMSCorrelationIDByteArray String
JMSReplyTo String
JMSType String
JMSMessageID String
JMSTimestamp String
JMSRedelivered String
JMSXGroupID String
JMSXGroupIdByteArray String
JMSXGroupSeq String
JMSXUserID String
JMSXAppID String
JMSXDeliveryCount String
Property Data Type
5 Adapter Services
116 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Note: An "X" in the JMS property name indicates that the property is provider specific.
The remaining JMS properties are generic, delivered by any JMS provider.
WebSphere MQ Adapter passes the following optional output properties from the MQMD
Header tab in Developer or Designer to the output signature of the Get service. The data
types for the msgHeader properties are documented as they appear in Developer or
Designer.
For a complete description of the msgHeader properties and their uses, refer to IBM's
WebSphere MQ user documentation.
MCDMessageDomain String
MCDMessageSet String
MCDMessageFormat String
msgHeader Property Data Type
AccountingToken String
AccountingTokenByteArray Object
ApplIdentityData String
ApplOriginData String
BackoutCount String
CodedCharSetId String
CorrelId String
CorrelationIdByteArray Object
Encoding String
Expiry String
Feedback String
Format String
GroupId* String
GroupIdByteArray Object
MsgFlags String
MsgId String
MsgIdByteArray Object
MsgType String
MsgSeqNumber String
JMS Properties Data Type
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 117
5 Adapter Services
Configuring Peek Services
The Peek service retrieves a copy of a message without removing the original message
from a specified queue. For more information about Peek services, see Peek Services on
page 32. You configure WebSphere MQ Adapter services using Developer or Designer.
To configure a Peek service
1 Review the steps in Before Configuring or Managing Adapter Services on page 90.
2 Start Developer or Designer.
3 Perform one of the following:
If you are using Developer, select File > New > Adapter Service and click Next.
If you are using Designer, perform the following:
i Right-click the package in which the service should be contained and select
New > Adapter Service.
ii Select the parent namespace and type a name for the adapter service.
iii Click Next.
4 Select WebSphere MQ Adapter as the adapter type and click Next.
Offset String
OriginalLength String
Persistence String
Priority String
PutApplName String
PutApplType String
PutDate String
PutTime String
ReplytoQueueMgr String
ReplyToQ String
Report String
UserIdentifier String
msgHeader Property Data Type
5 Adapter Services
118 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
5 Select the appropriate Adapter Connection Name and click Next.
Important! If you are using the adapter with Integration Server 8.0 SP1 or earlier,
adapter services cannot use connections that are also used for adapter listeners.
6 From the list of available templates, select the Peek template and do one of the
following:
If you are using Developer, click Next, select a package and folder to contain the
service, type a unique name for the service, and click Finish.
If you are using Designer, click Finish.
The adapter service editor for the Peek service appears. You can select the Adapter
Settings tab at any time to confirm adapter service properties such as Adapter Name,
Adapter Connection Name, and Adapter Service Template, as necessary.
7 Select the Peek Service tab to identify message processing features to use with this
adapter service.
Specify values for the following fields:
Field Description/Action
Wait Interval (msec) The time period that the service waits for a message to appear
on the queue. Enter this value in milliseconds.
Default: 60000
Convert Application
Data?
Select whether the service converts the message to the local
character set and encoding:
Checked The messages read using this service will be
converted to the local character set and encoding.
Unchecked The messages read using this service will not be
converted to the local character set and encoding.
Default: Checked
Note: If the property is checked and the message format does
not match the local character set and encoding, a warning
message appears.
Note: If you are using a Peek service configured using
WebSphere MQ Adapter, the default value is Checked.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 119
5 Adapter Services
8 Select the MQMD Header tab to specify which selectionCriteria property fields and
constant values the service will use. Selection criteria refers to the specific values that
must be present in the header of the actual message in order for the adapter to
retrieve it from the WebSphere MQ.
The selectionCriteria property fields appear on the Input/Output tab in the Input
signature document for this adapter service. Use the following icons to manage the
rows on the MQMD Header tab:
Select the Insert Row icon (or the Fill in all rows to the table icon ) to define
new selectionCriteria property fields and new output field names.
If necessary, use the Shift Up or Shift Down icons to change the order of the
selectionCriteria property fields or the output field names to ensure the
parameters are parsed in the correct order.
Use the Remove row icon to delete any selectionCriteria property fields or
output field names.
In the Constant Value column, specify default values for any of the property fields. You
can override these values at run time.You can add the following optional
selectionCriteria property fields:
Throw Exception on
Failure?
Select whether the service should throw an exception on
failure:
Checked Throws an exception when the adapter service
returns error codes.
Unchecked Returns any error codes or error messages to
the service's output signature.
Default: Checked
Reset Cursor before
Operation?
The value of the resetCursor is set on the Peek Service tab in
Developer or Designer.
yes The Peek service starts at the beginning of the queue
and gets a copy of the first message.
no The Peek service retrieves a copy of the next message in
the queue relative to the last message that the Peek service
retrieved.
Default: yes
Note: You can also set the value for the Reset Cursor before
Operation field in the Pipeline Editor. If you add a value other
than yes or no in this field, then WebSphere MQ Adapter
automatically sets the value to no.
Field Description/Action
5 Adapter Services
120 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Note: An asterisk * indicates that you can enter these properties either as a string or as
a byte array. For example, CorrelId and CorrelationByteArray refer to the same
msgHeader property. If you specify values for both properties, then the byte array
value will be used.
9 The msgHeader property fields appear on the Input/Output tab in the Output signature
document for this adapter service. Add the following optional msgHeader property
fields to the Output Field Name column:
selectionCriteria
Property Data Type Maximum Field Length for Constant Value
CorrelId* String 24 alphanumeric single-byte characters
CorrelationByteArray* Byte Array 24 bytes
GroupId* String 24 alphanumeric single-byte characters
GroupIdByteArray* Byte Array 24 bytes
MsgId* String 24 alphanumeric single-byte characters
MsgIdByteArray* Byte Array 24 bytes
MsgSeqNumber String 4 digits
Offset String 4 digits
msgHeader Property Data Type
AccountingToken String
AccountingTokenByteArray Byte Array
ApplIdentityData String
ApplOriginData String
BackoutCount String
CodedCharSetId String
CorrelId String
CorrelationIdByteArray Byte Array
Encoding String
Expiry String
Feedback String
Format String
GroupId String
GroupIdByteArray Byte Array
MsgFlags String
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 121
5 Adapter Services
10 Select the JMS Properties tab to identify the optional JMS property fields for the
adapter service. The JMS property fields appear on the Input/Output tab in the Output
signature document for this adapter service.
Use the following icons to insert or delete rows:
To define new JMS property fields, select the Insert Row icon (or the Fill in all
rows to the table icon ).
To change the order of JMS property fields to ensure the parameters are parsed in
the correct order, use the Shift Up or Shift Down icons.
To delete any JMS property fields, use the Remove row icon .
You can add the following optional JMS property fields:
MsgId String
MsgIdByteArray Byte Array
MsgType String
MsgSeqNumber String
Offset String
OriginalLength String
Persistence String
Priority String
PutApplName String
PutApplType String
PutDate String
PutTime String
ReplytoQueueMgr String
ReplyToQ String
Report String
UserIdentifier String
JMS Property Data Type
JMSDestination String
JMSExpiration String
JMSPriority String
JMSDeliveryMode String
msgHeader Property Data Type
5 Adapter Services
122 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Note: An "X" in the JMS property name indicates that the property is provider specific.
The remaining JMS properties are generic, delivered by any JMS provider.
You can also add your own folders and properties to the JMS Properties.
Use the following icons to manage the rows for User-Defined Properties on the JMS
Properties tab:
To define new folders and properties, select the Insert Row icon .
Enter the new folder and property. For example, enter "jms.usr.usr1". The "jms"
and "usr" are the names of the folders and "usr1" is the name of the property.
All the folders and properties you add will be under JMSProperties as part of the
output signature of the adapter service.
Note: The property name has to be prefixed with a folder name. You cannot use
"JMSProperties" and "mcd" as the first folder name.
To change the order of User-Defined property fields to ensure the parameters are
parsed in the correct order, use the Shift Up or Shift Down icons.
To delete any User-Defined property fields, use the Remove row icon .
JMSCorrelationID String
JMSCorrelationIDByteArray Byte Array
JMSReplyTo String
JMSType String
JMSMessageID String
JMSTimestamp String
JMSRedelivered String
JMSXGroupID String
JMSXGroupIdByteArray Byte Array
JMSXGroupSeq String
JMSXUserID String
JMSXAppID String
JMSXDeliveryCount String
MCDMessageDomain String
MCDMessageSet String
MCDMessageFormat String
JMS Property Data Type
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 123
5 Adapter Services
The Input/Output, Settings, Audit, Permissions, and Results tabs apply to all services that
you configure using versions of Developer earlier than 6.1. For more information, see
the Developer users guide for your release. See About this Guide for specific
document titles.
When using Designer or Developer 6.1 or later, Designer or Developer contains only
the Adapter Settings and Input/Output tabs. The information from the Audit and
Permissions tabs appears in the Properties panel, and the information from the Results
tab appears in the Results panel in Developer or the Service Results panel in Designer.
For more information, see the Developer users guide or Designer Service
Development online help for your release. See About this Guide for specific
document titles.
11 From the File menu, select Save.
Using the Peek Service
The input and output signatures for the Peek service are located on the Input/Output tab of
Developer or Designer.
Input Signature Properties for the Peek Service
When you configure the Peek service, the following properties are passed from the Peek
Service tab in Developer or Designer to the input signature of the Peek service:
Property Description
waitInterval The time period that the service waits for a message to appear on
the queue. Enter this value in milliseconds.
You set the value of this Integer in the Pipeline Editor, which
overwrites the value set on the Peek Service tab.
Default: 60000
5 Adapter Services
124 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
When you configure the Peek service, the following overrideConnection properties
automatically appear in the input signature of the Peek service on the Input/Output tab:
resetCursor A String that contains the value of the resetCursor is set on the
Peek Service tab.
Set the Reset Cursor before Operation field on the Peek Service tab to
either:
Yes The Peek service starts at the beginning of the queue and
gets a copy of the first message.
No The Peek service retrieves a copy of the next message in
the queue relative to the last message that the Peek service
retrieved.
Default: Yes
Note: You can also set the value for the Reset Cursor before
Operation field in the Pipeline Editor. If you add a value other
than Yes or No in this field, then WebSphere MQ Adapter
automatically sets the value to No.
waitInterval The time period that the service waits for a message to appear on
the queue. Enter this value in milliseconds.
You set the value of this Integer in the Pipeline Editor, which
overwrites the value set on the Peek Service tab.
Default: 60000
resetCursor A String that contains the value of the resetCursor is set on the
Peek Service tab.
Set the Reset Cursor before Operation field on the Peek Service tab to
either:
Yes The Peek service starts at the beginning of the queue and
gets a copy of the first message.
No The Peek service retrieves a copy of the next message in
the queue relative to the last message that the Peek service
retrieved.
Default: Yes
Note: You can also set the value for the Reset Cursor before
Operation field in the Pipeline Editor. If you add a value other
than Yes or No in this field, then WebSphere MQ Adapter
automatically sets the value to No.
Property Description
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 125
5 Adapter Services
Note: An asterisk * indicates that if you set the dynamicQueuePrefix at run time, then you
also need to set the queueName.
For a description of each data type, see the list of parameters in Configuring
WebSphere MQ Adapter Connections on page 70.
WebSphere MQ Adapter passes the following optional input properties from the MQMD
Headertab in Developer or Designer to the input signature of the Peek service. The data
types for the selectionCriteria properties are documented as they appear in Developer or
Designer.
Also, if values are specified for these properties, then WebSphere MQ Adapter will only
receive messages from the queue that match the specified criteria. For a complete
description of the selectionCriteria properties and their uses, refer to IBM's WebSphere
MQ user documentation.
Output Signature Properties for the Peek Service
When you configure the Peek service, the following output properties automatically
appear in the output signature of the Peek service on the Input/Output tab:
Property Data Type
queueManagerName String
hostName String
port String
channel String
CCSID String
queueName* String
dynamicQueuePrefix* String
encoding String
selectionCriteria Property Data Type
CorrelId String
CorrelationIdByteArray Object
GroupId String
GroupIdByteArray Object
MsgId String
MsgIdByteArray Object
MsgSeqNumber String
Offset String
5 Adapter Services
126 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
When you configure the Peek service, the following overrideConnection properties
automatically appear in the output signature of the Peek service on the Input/Output tab:
Note: An asterisk * indicates that if you set the dynamicQueuePrefix at run time, then you
also need to set the queueName.
For a description of each data type, see the list of parameters in Configuring
WebSphere MQ Adapter Connections on page 70.
WebSphere MQ Adapter passes the following optional output properties from the MQMD
Header tab in Developer or Designer to the output signature of the Peek service. The data
types for the msgHeader properties are documented as they appear in Developer or
Designer.
Property Description
msgBody The contents of the payload.
Note: The msgBody is only available via the output signature for
the Peek service, located on theInput/Output tab.
msgBodyByteArray The contents of the payload in a byte array.
Note: The msgBodyByteArray is only available via the output
signature for the Peek service, located on the Input/Output tab.
reasonCode A String that contains the reasonCode of the MQ Series
operation.
conditionCode A String that contains the conditionCode of the MQ Series
operation.
errorMsg A String that appears in the output signature only when the
adapter service fails.
Property Data Type
queueManagerName String
hostName String
port String
channel String
CCSID String
queueName* String
dynamicQueuePrefix* String
encoding String
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 127
5 Adapter Services
For a complete description of the msgHeader properties and their uses, refer to IBM's
WebSphere MQ user documentation.
msgHeader Property Data Type
AccountingToken String
AccountingTokenByteArray Object
ApplIdentityData String
ApplOriginData String
BackoutCount String
CodedCharSetId String
CorrelId String
CorrelationIdByteArray Object
Encoding String
Expiry String
Feedback String
Format String
GroupId String
GroupIdByteArray Object
MsgFlags String
MsgId String
MsgIdByteArray Object
MsgType String
MsgSeqNumber String
Offset String
OriginalLength String
Persistence String
Priority String
PutApplName String
PutApplType String
PutDate String
PutTime String
ReplytoQueueMgr String
ReplyToQ String
Report String
5 Adapter Services
128 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
WebSphere MQ Adapter passes the following optional output properties from the JMS
Properties tab in Developer or Designer to the output signature of the Peek service. The
data types for the JMS Properties are documented as they appear in Developer or
Designer.
Note: All the User-Defined Properties specified will also be passed to the output
signature.
For a complete description of the JMS Property properties and their uses, refer to your
JMS provider's user documentation.
UserIdentifier String
JMS Properties Data Type
JMSDestination String
JMSExpiration String
JMSPriority String
JMSDeliveryMode String
JMSCorrelationID String
JMSCorrelationIDByteArray String
JMSReplyTo String
JMSType String
JMSMessageID String
JMSTimestamp String
JMSRedelivered String
JMSXGroupID String
JMSXGroupIdByteArray String
JMSXGroupSeq String
JMSXUserID String
JMSXAppID String
JMSXDeliveryCount String
MCDMessageDomain String
MCDMessageSet String
MCDMessageFormat String
msgHeader Property Data Type
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 129
5 Adapter Services
Note: An "X" in the JMS property name indicates that the property is provider specific.
The remaining JMS properties are generic, delivered by any JMS provider.
Configuring Request/Reply Services
The Request/Reply service delivers a message to a specified queue, and retrieves a
corresponding response message.
For more information about adapter services, see Request/Reply Services on page 35.
You configure WebSphere MQ Adapter services using Developer or Designer.
To configure a Request/Reply service
1 Review the steps in Before Configuring or Managing Adapter Services on page 90.
2 Start Developer or Designer.
3 Perform one of the following:
If you are using Developer, select File > New > Adapter Service and click Next.
If you are using Designer, perform the following:
i Right-click the package in which the service should be contained and select
New > Adapter Service.
ii Select the parent namespace and type a name for the adapter service.
iii Click Next.
4 Select WebSphere MQ Adapter as the adapter type and click Next.
5 Select the appropriate Adapter Connection Name and click Next.
Important! The Request/Reply service requires a non-transactional connection. This
service does not support transactional connections because it sends a request message
and waits for a reply message before the service returns to Integration Server. In
addition, if you are using the adapter with Integration Server 8.0 SP1 or earlier,
adapter services cannot use connections that are also used for adapter listeners.
6 From the list of available templates, select the Request/Reply template and do one of
the following:
If you are using Developer, click Next, select a package and folder to contain the
service, type a unique name for the service, and click Finish.
If you are using Designer, click Finish.
The adapter service editor for the Request/Reply service appears. You can select the
Adapter Settings tab at any time to confirm adapter service properties such as Adapter
Name, Adapter Connection Name, and Adapter Service Template, as necessary.
5 Adapter Services
130 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
7 Select the Request/Reply tab to identify message processing features to use with this
adapter service.
Specify values for the following fields:
Field Description/Action
Wait Interval (msec) The time period that the service waits for a reply message to
appear on the queue. Enter this value in milliseconds.
Default: 60000
Dead Letter Queue
Name
The name of the queue that will contain any messages that
could not reach their destination.
If you do not specify a value for this field, then
WebSphere MQ Adapter will:
Not do anything with an undeliverable inbound (Reply)
message.
Write an undeliverable outbound (Request) message to
the system dead letter queue
(SYSTEM.DEAD.LETTER.QUEUE) for that queue
manager.
Dead Letter Queue
Manager Name
The name of the queue manager for the dead letter queue.
Headers to include in
Dead Letter Message
Select which headers to include in the message sent to the
dead letter queue:
None Includes any headers along with the original
payload in the message sent to the dead letter queue.
DLH Includes only the DLH header along with the original
payload in the message sent to the dead letter queue.
MQMD Includes only the MQMD header along with the
original payload in the message sent to the dead letter
queue.
DLH_&_MQMD Includes both DLH and MQMD headers
along with the original payload in the message sent to the
dead letter queue.
Default: DLH_&_MQMD
Note: If you are using a Request/Reply service configured
using WebSphere MQ Adapter, the service refers to the watt
property watt.WmMQAdapter.deadLetterMessageHeaders. If this watt
property is not set, then WebSphere MQ Adapter sets Headers
to include in Dead Letter Message parameter to a default value
DLH_&_MQMD.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 131
5 Adapter Services
Backout Threshold The number of times the service will attempt to send the
Request message or receive the Reply message before it is
sent to the dead letter queue.
For example, specify 2 to attempt to send the message twice
Default: 1
Open Queue in
Shared Mode?
Select how the queue should be opened:
Checked In shared mode, allows simultaneous access to
the queue by other applications.
Unchecked In exclusive mode, prevents simultaneous
access to the queue by other applications.
Default: Checked
Convert Application
Data?
Select whether the service converts the message to the local
character set and encoding:
Checked Converts the messages read using this service to
the local character set and encoding.
Unchecked Does not convert the messages read using this
service to the local character set and encoding.
Default: Checked
Note: If the property is checked and the message format does
not match the local character set and encoding, a warning
message appears.
Note: If you are using a Request/Reply service configured
using WebSphere MQ Adapter, the default value is Checked.
Throw Exception on
Failure?
Select whether the service should throw an exception on
failure:
Checked Throws an exception when the adapter service
returns error codes.
Unchecked Returns any error codes or error messages to
the service's output signature.
Default: Checked
Field Description/Action
5 Adapter Services
132 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
8 Select the MQMD Header tab to specify which msgHeader property fields and constant
values the service will use.
Use the following icons to manage the rows in the MQMD Header tab:
Select the icon (or the Fill in all rows to the icon) to define new input or
output field names.
If necessary, use the or icons to change the order of the input or output
fields to ensure the parameters are parsed in the correct order.
Use the icon to delete input field names or output field names.
The msgHeader property fields that you select from the Input Field Name column
appear on the Input/Output tab in the Input signature for this adapter service. The
msgHeader property fields that you select from the Output Field Name column appear
on the Input/Output tab in the Output signature for this adapter service.
You can add the following msgHeader property fields to the Input Field Name column
and the Output Field Name column. In the Constant Value column, specify values for the
default property fields. Also, you can override the property fields at run time, using
the Pipeline Editor. However, you cannot modify certain "output only" properties,
such as PutDate and PutTime.
Note: An asterisk * indicates that you can enter these properties either as a string or as
a byte array. For example, AccountingToken and AccountingTokenByteArray refer to the
same msgHeader property. If you specify values for both properties, then the byte
array value will be used.
msgHeader Property Data Type Maximum Field Length for Constant Value
AccountingToken* String 32 alphanumeric single-byte characters
AccountingTokenByteArray* Byte Array 32 bytes
ApplIdentityData String 32 alphanumeric single-byte characters
ApplOriginData String 4 alphanumeric single-byte characters
BackoutCount String 4 digits
CodedCharSetId String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of MQCCSI_Q_MGR.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 133
5 Adapter Services
CorrelId* String 24 alphanumeric single-byte characters
Note: The MsgId value in the Request
message maps to the CorrelationID in
the Reply message.
CorrelationIdByteArray* Byte Array 24 bytes
Encoding String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of 00273 - Native.
Expiry String 4 digits
Feedback String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of MQFB_NONE.
Format String 8 alphanumeric single-byte characters
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of NONE.
GroupId* String 24 alphanumeric single-byte characters
GroupIdByteArray* Byte Array 24 bytes
MsgFlags String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of NONE.
MsgId* String 24 alphanumeric single-byte characters
Note: The MsgId value in the Request
message maps to the CorrelationID in
the Reply message.
MsgIdByteArray* Byte Array 24 bytes
msgHeader Property Data Type Maximum Field Length for Constant Value
5 Adapter Services
134 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
MsgType String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of Datagram.
MsgSeqNumber String 4 digits
Offset String 4 digits
OriginalLength String 4 digits
Persistence String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of Not Persistent.
Priority String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value based on the default
priority of the queue.
PutApplName String 24 alphanumeric single-byte characters
PutApplType String 4 digits
PutDate String 8 digits
PutTime String 8 digits
ReplytoQueueMgr String 48 alphanumeric single-byte characters
ReplyToQ String 48 alphanumeric single-byte characters
Important! ReplyToQ is a required field.
Report String 4 digits
UserIdentifier String 12 alphanumeric single-byte characters
msgHeader Property Data Type Maximum Field Length for Constant Value
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 135
5 Adapter Services
9 Select the JMS Properties tab to identify the optional JMS property fields for the
adapter service. The JMS property fields appear on the Input/Output tab in the Output
signature document for this adapter service.
Use the following icons to insert or delete rows:
Select the icon (or the Fill in all rows to the icon) to define new JMS property
fields.
If necessary, use the or icons to change the order of JMS property fields to
ensure the parameters are parsed in the correct order.
Use the icon to delete any JMS property fields.
You can add the following optional JMS property fields:
JMS Property Data Type
JMSDestination String
JMSExpiration String
JMSPriority String
JMSDeliveryMode String
JMSCorrelationID String
JMSCorrelationIDByteArray Byte Array
JMSReplyTo String
JMSType String
JMSMessageID String
JMSTimestamp String
JMSRedelivered String
JMSXGroupID String
JMSXGroupIdByteArray Byte Array
JMSXGroupSeq String
JMSXUserID String
JMSXAppID String
JMSXDeliveryCount String
MCDMessageDomain String
MCDMessageSet String
MCDMessageFormat String
5 Adapter Services
136 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Note: An "X" in the JMS property name indicates that the property is provider specific.
The remaining JMS properties are generic, delivered by any JMS provider.
You can also add your own folders and properties to the JMS Properties.
Use the following icons to manage the rows for User-Defined Properties on the JMS
Properties tab:
To define new folders and properties, select the icon.
Enter the new folder and property. For example, enter "jms.usr.usr1". The "jms"
and "usr" are the names of the folders and "usr1" is the name of the property.
All the folders and properties you add will be under JMSProperties as part of the
output signature of the adapter service.
Note: The property name has to be prefixed with a folder name. You cannot use
"JMSProperties" and "mcd" as the first folder name.
The property name has to be prefixed with a folder name. You cannot use
"JMSProperties" and "mcd" as the first folder name.
To change the order of User-Defined property fields to ensure the parameters are
parsed in the correct order, use the or icons.
To delete any User-Defined property fields, use the icon.
The Input/Output, Settings, Audit, Permissions, and Results tabs apply to all services that
you configure using versions of Developer earlier than 6.1. For more information, see
the Developer users guide for your release. See About this Guide for specific
document titles.
When using Designer or Developer 6.1 or later, Designer or Developer contains only
the Adapter Settings and Input/Output tabs. The information from the Audit and
Permissions tabs appears in the Properties panel, and the information from the Results
tab appears in the Results panel in Developer or the Service Results panel in Designer.
For more information, see the Developer users guide or Designer Service
Development online help for your release. See About this Guide for specific
document titles.
10 From the File menu, select Save.
Using the Request/Reply Service
The input and output signatures for the Request/Reply service are located on the
Input/Output tab in Developer or Designer. Each input and output signature contains
properties for the Request/Reply service.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 137
5 Adapter Services
Input Signature Properties for the Request/Reply Service
When you configure the Request/Reply service, the following overrideConnection
properties automatically appear in the input signature of the Request/Reply service on
the Input/Output tab:
Note: An asterisk * indicates that if you set the dynamicQueuePrefix at run time, then you
also need to set the queueName.
Note: A plus + indicates that there is a description for this property below this table.
When you configure a Request/Reply service, useLocalQueueManager is in the input
signature under override connection parameter. You can set the value for
useLocalQueueManager in the Pipeline editor. If you add a value other than Yes or No in this
field, then WebSphere MQ Adapter sets the value to No.
Yes The Request/Reply service will use the existing connection (configured for this
service) to send messages to the specified queue on the remote queue manager.
No The Request/Reply service will create a new connection to the remote queue
manager and sends the message to the specified queue on the remote queue manager.
For this feature to work, the local queue manager needs to know the route to the remote
location (that is, the transmission queue). When an application puts messages that are
destined for a remote queue manager, the local queue manager adds a transmission
header to the message before putting the message on the transmission queue with the
same name as the remote queue manager. The transmission header contains the name of
the destination queue and queue manager, that is, the addressing information. The
receiving channel removes the transmission header and uses the information in it to
locate the destination queue. To configure your local queue and remote queue managers:
Property Data Type
queueManagerName String
hostName String
port String
channel String
CCSID String
queueName* String
dynamicQueuePrefix* String
useLocalQueueManager+ String
encoding String
5 Adapter Services
138 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
1 Define a Transmission queue on the local queue manager. The transmission queue
name must be same as the remote queue manager name.
2 Define a Sender channel at the local queue manager and specify the transmission
queue to be used. Use the transmission queue defined in the previous step.
3 Define a Receiver channel at the remote queue manager. The receiver channel name
must be same as the sender channel name.
Tip! For more information on configuring your local queue and remote queue
managers, see WebSphere MQ Intercommunication.pdf (SC34-6587). Refer to "Chapter1:
Concepts of Intercommunication" and "Chapter 2: Making Your Applications
Communicate" for instructions on enabling communication between two Queue
Managers.
The following properties are passed from the Request/Reply Service tab in Developer or
Designer to the input signature of the Request/Reply service:
Property Description
waitInterval The time period that the service waits for a message to appear on
the queue. Enter this value in milliseconds.
You set the value of this Integer in the Pipeline Editor, which
overwrites the value set on the Request/Reply Servicetab.
Default: 60000
deadLetterQueueNam
e
A String that contains the name of the queue that will contain
any messages that could not reach their destination.
You set the value of this property in the Pipeline Editor, which
overwrites any value set on the Request/Reply Service tab.
deadLetterQueueMan
agerName
A String that contains the name of the queue manager for the
dead letter queue.
You set the value of this property in the Pipeline Editor, which
overwrites any value set on the Request/Reply tab.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 139
5 Adapter Services
WebSphere MQ Adapter passes the following optional input properties from the MQMD
Header tab in Developer or Designerto the input signature of the Request/Reply service.
The data types for the msgHeader properties are documented as they appear in the
Developer or Designer.
For a complete description of the msgHeader properties and their uses, refer to IBM's
WebSphere MQ user documentation.
deadLetterMessageHe
aders
A String that contains the headers to include in the message sent
to the dead letter queue.
You set the value of this property in the Pipeline Editor, which
overwrites any value set on the Put Service tab.
None Use when you do not want to include any headers
along with the original payload in the message sent to the
dead letter queue.
DLH Use when you want to include only the DLH header
along with the original payload in the message sent to the
dead letter queue.
MQMD Use when you want to include only the MQMD
header along with the original payload in the message sent
to the dead letter queue.
DLH_&_MQMD Use when you want to include both DLH and
MQMD headers along with the original payload in the
message sent to the dead letter queue.
Default: DLH_&_MQMD
msgBody The contents of the payload.
Note: The msgBody is only available via the input signature for
the Request/Reply service, located on the Input/Output tab.
msgBodyByteArray The contents of the payload in a byte array.
Note: The msgBodyByteArray is only available via the input
signature for the Put service, located on the Input/Output tab.
msgHeader Property Data Type
AccountingToken* String
AccountingTokenByteArray* Object
ApplIdentityData String
ApplOriginData String
Property Description
5 Adapter Services
140 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
BackoutCount String
CodedCharSetId String
CorrelId* String
CorrelationIdByteArray* Object
Encoding String
Expiry String
Feedback String
Format String
GroupId* String
GroupIdByteArray* Object
MsgFlags String
MsgId* String
MsgIdByteArray* Object
MsgType String
MsgSeqNumber String
Offset String
OriginalLength String
Persistence String
Priority String
PutApplName String
PutApplType String
PutDate String
PutTime String
ReplytoQueueMgr String
Note: You must supply the
ReplytoQueueMgr property either as a
constant value or as an overridden
value at run time.
msgHeader Property Data Type
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 141
5 Adapter Services
Note: An asterisk * indicates that you can enter these properties either as a string or as a
byte array. For example, AccountingToken and AccountingTokenByteArray refer to the same
msgHeader property. If you specify values for both properties, then the byte array value
will be used.
Output Signature Properties for the Request/Reply Service
When you configure the Request/Reply service, the following output properties
automatically appear in the output signature of the Request/Reply service on the
Input/Output tab:
When you configure the Request/Reply service, the following overrideConnection
properties automatically appear in the output signature of the Request/Reply service on
the Input/Output tab:
ReplyToQ String
Note: You must supply the ReplytoQ
property either as a constant value or
as an overridden value at run time.
Report String
UserIdentifier String
Property Description
replyMsgBody The contents of the payload for a message that is a reply to the
request message.
replyMsgBodyByteArr
ay
The contents of the payload in a byte array for a message that is
a reply to the request message.
reasonCode A String that contains the reasonCode of the MQ Series
operation.
conditionCode A String that contains the conditionCode of the MQ Series
operation.
errorMsg A String that appears in the output signature only when the
adapter service fails.
Property Data Type
queueManagerName String
hostName String
msgHeader Property Data Type
5 Adapter Services
142 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Note: An asterisk * indicates that if you set the dynamicQueuePrefix at run time, then you
also need to set the queueName.
WebSphere MQ Adapter passes the following optional output properties from the JMS
Properties tab in Developer or Designer to the output signature of the Request/Reply
service. The data types for the JMS Properties are documented as they appear in
Developer or Designer.
Note: All the User-Defined Properties specified will also be passed to the output
signature.
For a complete description of the JMS Property properties and their uses, refer to your
JMS provider's user documentation.
port String
channel String
CCSID String
queueName* String
dynamicQueuePrefix* String
encoding String
JMS Properties Data Type
JMSDestination String
JMSExpiration String
JMSPriority String
JMSDeliveryMode String
JMSCorrelationID String
JMSCorrelationIDByteArray String
JMSReplyTo String
JMSType String
JMSMessageID String
JMSTimestamp String
JMSRedelivered String
JMSXGroupID String
JMSXGroupIdByteArray String
JMSXGroupSeq String
Property Data Type
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 143
5 Adapter Services
Note: An "X" in the JMS property name indicates that the property is provider specific.
The remaining JMS properties are generic, delivered by any JMS provider.
WebSphere MQ Adapter passes the following optional input properties from the MQMD
Header tab in Developer or Designer to the input signature of the Request/Reply service.
The data types for the msgHeader properties are documented as they appear in
Developer or Designer.
For a complete description of the msgHeader properties and their uses, refer to IBM's
WebSphere MQ user documentation.
JMSXUserID String
JMSXAppID String
JMSXDeliveryCount String
MCDMessageDomain String
MCDMessageSet String
MCDMessageFormat String
msgHeader Property Data Type
AccountingToken String
AccountingTokenByteArray Object
ApplIdentityData String
ApplOriginData String
BackoutCount String
CodedCharSetId String
CorrelId String
CorrelationIdByteArray Object
Encoding String
Expiry String
Feedback String
Format String
GroupId String
GroupIdByteArray Object
MsgFlags String
MsgId String
JMS Properties Data Type
5 Adapter Services
144 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Configuring Inquire Queue Manager/Queue Services
The Inquire Queue Manager/Queue service inquires the properties of the queue manager
and the properties of the first queue specified in the connection. For more information
about Inquire Queue Manager/Queue services, see Inquire Queue Manager/Queue
Services on page 37. You configure WebSphere MQ Adapter services using the
Developer or Designer.
To configure an Inquire Queue Manager/Queue service
1 Review the steps in Before Configuring or Managing Adapter Services on page 90.
2 Start Developer or Designer.
3 Perform one of the following:
If you are using Developer, select File > New > Adapter Service and click Next.
If you are using Designer, perform the following:
MsgIdByteArray Object
MsgType String
MsgSeqNumber String
Offset String
OriginalLength String
Persistence String
Priority String
PutApplName String
PutApplType String
PutDate String
PutTime String
ReplytoQueueMgr String
ReplyToQ String
Report String
UserIdentifier String
msgHeader Property Data Type
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 145
5 Adapter Services
i Right-click the package in which the service should be contained and select
New > Adapter Service.
ii Select the parent namespace and type a name for the adapter service.
iii Click Next.
4 Select WebSphere MQ Adapter as the adapter type and click Next.
5 Select the appropriate Adapter Connection Name and click Next.
Important! If you are using the adapter with Integration Server 8.0 SP1 or earlier,
adapter services cannot use connections that are also used for adapter listeners.
6 From the list of available templates, select the Inquire Queue Manager/Queue Service
template and do one of the following:
If you are using Developer, click Next, select a package and folder to contain the
service, type a unique name for the service, and click Finish.
If you are using Designer, click Finish.
The adapter service editor for the Inquire Queue Manager Service appears. You can
select the Adapter Settings tab at any time to confirm adapter service properties such as
Adapter Name, Adapter Connection Name, and Adapter Service Template, as necessary.
7 Select the Inquire Queue Manager Service tab to set the following field:
8 Select the Queue Manager Properties tab to specify the queue manager properties to be
queried.
Use the following icons to manage the rows on the Queue Manager Properties tab:
To select a Queue Manager property, click the icon (or the Fill in all rows to the
icon).
To change the order of the selected properties, use the or icons.
To delete any of the selected properties, use the icon.
Field Description/Action
Throw Exception on
Failure?
Select whether the service throws an exception on failure:
Checked Throws an exception when the adapter service
returns error codes.
Unchecked Returns reasonCode, conditionCode and
errorMsg in the output signature.
Default: Checked
5 Adapter Services
146 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
9 To specify the queue properties to be queried, select the Queue Properties tab and then
follow the same instructions to select, change, or delete the desired properties as
specified in step 8.
The properties that you select from the Queue Manager Properties and Queue Properties
appear on the Input/Output tab in the Output signature for this adapter service.
The queue name appears on the Input/Output tab in the Input signature for this adapter
service.
You can override the queue name by specifying the queue name in the service's input
signature.
For more information about queue properties and queue manager properties, see
WebSphere MQ Application Programming Reference (SC34-6596), chapter 42, and chapter
45 respectively.
The Input/Output, Settings, Audit, Permissions, and Results tabs apply to all services that
you configure using versions of Developer earlier than 6.1. For more information, see
the Developer users guide for your release. See About this Guide for specific
document titles.
When using Designer or Developer 6.1 or later, Designer or Developer contains only
the Adapter Settings and Input/Output tabs. The information from the Audit and
Permissions tabs appears in the Properties panel, and the information from the Results
tab appears in the Results panel in Developer or the Service Results panel in Designer.
For more information, see the Developer users guide or Designer Service
Development online help for your release. See About this Guide for specific
document titles.
10 From the File menu, select Save.
Using the Inquire Queue Manager/Queue Service
The input and output signatures for the Inquire Queue Manager service are located on the
Input/Output tab in Developer or Designer.
Output Signature Properties for the Inquire Queue Manager/Queue
Service
When you configure the Inquire Queue Manager service, the following output properties
automatically appear in the output signature of the Inquire Queue Manager service on
the Input/Output tab:
Property Description
reasonCode A String that contains the reasonCode of the MQ Series
operation.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 147
5 Adapter Services
Configuring PCF Command Services
A PCF Command service issues Programmable Command Format (PCF) commands to
the WebSphere MQ command server for execution. PCF commands allow you to use a
single application to perform network administration from a single queue manager
within the network.
For more information about PCF Command services, see PCF Command Services on
page 40. You configure WebSphere MQ Adapter services using Developer or Designer.
Important! To use this feature, you should be familiar with the WebSphere MQ
Programmable Command Formats, described in the WebSphere MQ Programmable
Command Formats and Administration Interface (SC34-6598).
Important! On platforms other than z/OS, the queue to which the PCF commands are sent
is always called the SYSTEM.ADMIN.COMMAND.QUEUE. On z/OS, commands are
sent to SYSTEM.COMMAND.INPUT, although SYSTEM.ADMIN.COMMAND.QUEUE
can be an alias for it.
To configure a PCF Command service
1 Review the steps in Before Configuring or Managing Adapter Services on page 90.
2 Start Developer or Designer.
3 Perform one of the following:
If you are using Developer, select File > New > Adapter Service and click Next.
If you are using Designer, perform the following:
i Right-click the package in which the service should be contained and select
New > Adapter Service.
ii Select the parent namespace and type a name for the adapter service.
iii Click Next.
4 Select WebSphere MQ Adapter as the adapter type and click Next.
conditionCode A String that contains the conditionCode of the MQ Series
operation.
errorMsg A String that appears in the output signature only when the
adapter service fails.
Property Description
5 Adapter Services
148 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
5 Select the appropriate Adapter Connection Name and click Next.
Important! If you are using the adapter with Integration Server 8.0 SP1 or earlier,
adapter services cannot use connections that are also used for adapter listeners.
6 From the list of available templates, select the PCF Command Service template and do
one of the following:
If you are using Developer, click Next, select a package and folder to contain the
service, type a unique name for the service, and click Finish.
If you are using Designer, click Finish.
The adapter service editor for the PCF Command service appears. You can select
the Adapter Settings tab at any time to confirm adapter service properties such as
Adapter Name, Adapter Connection Name, and Adapter Service Template, as necessary.
7 Select the PCF Command Service tab to configure the following fields:
8 Select the Optional Request Parameters tab to specify the optional Input parameters.
Use the following icons to manage the rows on the Optional Request Parameters tab:
To select an optional request parameter for the selected PCF command, select the
icon (or the Fill in all rows to the icon).
To change the order of the selected parameters, use the or icons.
To delete any of the selected parameter, use the icon.
The specified Optional Request Parameters appear on the Input/Output tab in the Input
signature for this adapter service.
Note: Some PCF commands have mandatory Request parameters, which will appear
under RequiredParameters in the Input signature of the service.
Field Description/Action
PCF Command Select the PCF command you want to execute.
Wait Interval (msec) The time period that the service waits for a reply message to
appear on the queue. Enter this value in milliseconds.
Default: 60000
Throw Exception on
Failure?
Select whether the service throws an exception on failure:
Checked Throws an exception when the adapter service
returns error codes.
Unchecked Returns reasonCode, conditionCode, and
errorMsg in the output signature.
Default: Checked
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 149
5 Adapter Services
9 Select the Response Parameters tab to select the response parameters for the selected
pcf command. To select the response parameters follow the same instructions as
specified in step 8. The specified Response Parameters appear on the Input/Output tab in
the Output signature for this adapter service.
For more information about Request Parameters and Response Parameters, see
WebSphere MQ Programmable Command Formats and Administration Interface (SC34-
6598).
The Input/Output, Settings, Audit, Permissions, and Results tabs apply to all services that
you configure using versions of Developer earlier than 6.1. For more information, see
the Developer users guide for your release. See About this Guide for specific
document titles.
When using Designer or Developer 6.1 or later, Designer or Developer contains only
the Adapter Settings and Input/Output tabs. The information from the Audit and
Permissions tabs appears in the Properties panel, and the information from the Results
tab appears in the Results panel in Developer or the Service Results panel in Designer.
For more information, see the Developer users guide or Designer Service
Development online help for your release. See About this Guide for specific
document titles.
10 From the File menu, select Save.
Using the PCF Command Service
The input and output signatures for the PCF Command service are located on the
Input/Output tab in Developer or Designer.
Output Signature Properties for the PCF Command Service
When you configure the PCF Command service, the following output properties
automatically appear in the output signature of the PCF Command service on the
Input/Output tab:
Property Description
reasonCode A String that contains the reasonCode of the MQ Series
operation.
conditionCode A String that contains the conditionCode of the MQ Series
operation.
errorMsg A String that appears in the output signature only when the
adapter service fails.
5 Adapter Services
150 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Throwing Exceptions on Failure
The Put, Get, Peek, and Request/Reply services have a Throw Exception on Failure option on
the service's tab in the adapter service editor of Developer or Designer. You can either
enable or disable this option for each service.
Enabling the Throw Exception on Failure Option
When you enable the Throw Exception on Failure option, WebSphere MQ Adapter has these
results under the following circumstances:
Note: For the Get, Put, and Request/Reply services, make sure that the Dead Letter Queue
field and the Backout Threshold field are set to valid values.
For more information on setting the Throw Exception on Failure field option and the Backout
Threshold field option, refer to the appropriate section on configuring services in this
chapter.
Disabling the Throw Exception on Failure Option
When you disable the Throw Exception on Failure option, WebSphere MQ Adapter has these
results under the following circumstances:
If... Then the WebSphere MQ Adapter...
The Get service and the Reply portion of
the Request/Reply service have a Backout
Threshold that is > or = to the MQ Backout
Count value
...throws an exception. If applicable, the
WebSphere MQ Adapter also includes the
Reason Code and the Condition Code in
the exception.
The Put service and the Request portion
of the Request/Reply service send out
messages that cannot reach the queue
The Peek service cannot retrieve a copy of
the message
The Inquire Queue Manager/Queue
service can not inquire the
QueueManager or Queue
The PCF Command service can not
execute the PCF command
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 151
5 Adapter Services
Note: For the Get, Put, and Request/Reply services, make sure that the Dead Letter Queue
field and the Backout Threshold field are set to valid values.
For more information on setting the Throw Exception on Failure field option and the Backout
Threshold field option, refer to the appropriate section on configuring services in this
chapter.
Working with Messages in a Group
WebSphere MQ Adapter allows you to work with messages in a group. For example, you
can perform the following tasks:
Retrieve inbound messages in a group
Categorize outbound messages as part of a group
Retrieving Inbound Messages in a Group
Use the Get or Peek service to retrieve inbound messages from a queue that are already
part of a group.
If... Then WebSphere MQ Adapter...
The Get service and the Reply portion of the
Request/Reply service have a Backout
Threshold value that is < or = to the MQ
Backout Count value of the message
Sends the message to the dead letter
queue.
The Put service and the Request portion of
the Request/Reply service send out
messages that cannot reach the queue
Attempts to send the message to the
queue the number of times that equal
the value of the Backout Threshold. The
adapter sends the message to the dead
letter queue.
The Peek service cannot retrieve a copy of
the message
Returns the Reason Code, Condition
Code, and errorMsg in the Peek
service's output signature.
The Inquire Queue Manager/Queue service
can not inquire queue manager or queue
properties
Returns the Reason Code, Condition
Code, and errorMsg in the Inquire Queue
Manager/Queue service's output
signature.
The PCF Command service can not execute
the PCF command
Returns the Reason Code, Condition
Code, and errorMsg in the PCF Command
service's output signature.
5 Adapter Services
152 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
To retrieve inbound messages in a group
1 Configure a Get or Peek service using Developer or Designer.
For detailed instructions on how to configure the Get or Peek services, see either
Configuring Get Services on page 105 or Configuring Peek Services on page 117.
2 To retrieve messages that are a part of a group, specify a value for the GroupId or the
GroupIdByteArray property field on the MQMD Header tab in the Get or Peek adapter
service editor.
The Get or Peek service filters on and retrieves only those messages that match the
specified GroupId value, which are part of a group.
Note: You can enter this value either as a string in the GroupId property field (24
alphanumeric single-byte characters) property field or as a byte array in the
GroupIdByteArray(24 bytes) property field. If you specify values for both of these
property fields, then WebSphere MQ Adapter uses the byte array value.
Categorizing Outbound Messages as Part of a Group
Use the Put service to indicate which outbound message to categorize as part of a group.
To categorize outbound messages as part of a group
1 Configure a Put service using Developer or Designer.
For detailed instructions on how to configure a Put service, see Configuring Put
Services on page 91.
2 On the MQMD Header tab in the Put adapter service editor, set the MsgFlags property
field to one of the following values:
3 On the MQMD Header tab in the Put adapter service editor, set the GroupId property
field to specify the messages that you want put on the queue. The Put service filters
on and puts only those messages on the queue that match the specified GroupId value.
Note: You can enter this value either as a string in the GroupId property field (24
alphanumeric single-byte characters) property field or as a byte array in the
GroupIdByteArray(24 bytes) property field. If you specify values for both of these
property fields, then WebSphere MQ Adapter uses the byte array value.
Value Description/Action
Message in Group WebSphere MQ Adapter tags the message as one that is part
of a group.
Last Message in
Group
WebSphere MQ Adapter tags the message as the last message
in the group.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 153
5 Adapter Services
Working with Messages in a Segment
WebSphere MQ Adapter allows you to work with messages in a segment. For example,
you can perform the following tasks:
Retrieve inbound messages in a segment
Segment outbound messages in one of the following ways:
WebSphere MQ segments outbound messages
The user programmatically segments outbound messages
Retrieving Inbound Messages in a Segment
Use the Get or Peek service to retrieve inbound messages from a queue that are already
segmented.
To retrieve segmented inbound messages
1 Configure a Get or Peek service using Developer or Designer.
For detailed instructions on how to configure the Get or Peek service, see either
Configuring Get Services on page 105 or Configuring Peek Services on page 117.
2 Set the Offset property field to a value. The segment of the message returned by the
Get or Peek service depends on the Offsetvalue. For example, if you enter a value of 0
in the Offset property field, then WebSphere MQ Adapter retrieves the first segment
of the message.
Note: WebSphere MQ Adapter filters on and searches for the value that you entered in
the Offset property field. If the adapter does not find a match between the Offset value
and the segmented value on the queue, then the Get or Peek service does not return a
segmented message. For example, if a segmented message on the queue is 32K, then
the first message is set to an appropriate Offset value of 0. However, if you enter a
value of 19 in the Offset property field for a 32K message, then no exact match exists,
and the Get or Peek service does not return a segmented message.
3 To retrieve inbound messages that are already segmented, invoke a series of Get or
Peek services within a flow service using Developer or Designer.
Segmenting Outbound Messages
Use the Put service to segment outbound messages in one of the following ways:
Instruct WebSphere MQ to segment the messages
Segment messages programmatically using your own code
5 Adapter Services
154 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Instructing WebSphere MQ to Segment Outbound Messages
Perform the following procedure to instruct WebSphere MQ to segment outbound
messages.
To instruct WebSphere MQ to segment outbound messages
1 Configure a Put service using Developer or Designer.
For detailed instructions on how to configure a Put service, see Configuring Put
Services on page 91.
2 On the MQMD Header tab in the Put adapter service editor, set the MsgFlags property to
Segmentation allowed.
When the Put services places the message on the queue, then WebSphere MQ
segments the message into smaller sections.
3 To instruct WebSphere MQ to segment outbound messages, invoke a series of Put
services within a flow service using Developer or Designer.
Segmenting Messages Programmatically With Your Own Code
Perform the following procedure to segment messages programmatically.
To segment messages for outbound adapter services that WebSphere MQ Adapter segments
1 Configure a Put service using Developer or Designer.
For detailed instructions on how to configure a Put service, see Configuring Put
Services on page 91.
2 On the MQMD Header tab in the Put adapter service editor, set the MsgFlags property
field to one of the following values:
Value Description/Action
Segment The user segments the beginning and the middle sections of
the message.
Last Segment The user segments only the last portion of the message.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 155
5 Adapter Services
3 Set the Offset property field to a value that represents the offset of the segment in the
original message.
For example, when you have a 1200K message on the queue, then the three
segmented messages are set to the following Offset values and MsgFlag values:
First message: Offset property field value = 0 and MsgFlag property field value =
Segment
Second message: Offset property field value =400andMsgFlagproperty field
=Segment
Third message: Offset property field value = 800 andMsgFlag property field = Last
Segment
Using the Pipeline Editor to View and Set the msgBody
Depending on the service, you can use the Get, Put, Peek, or Request/Reply services to
map variables to the either the Input signature or the Output signature. You can do this
using the Pipeline Editor in Developer or Designer.
To use the Pipeline Editor to view and set the msgBody
1 Configure a new flow service or open an existing one using Developer or Designer.
2 Insert an invoke step that calls the adapter service.
3 In each of the following services, use the Pipeline Editor to map to a variable:
Testing Adapter Services
You use Developer or Designer to test adapter services.
For more information about testing and debugging services, see the Developer users
guide or Designer Service Development online help for your release. See About this
Guide for specific document titles.
Services Use the Pipeline Editor to map...
Put,
Request/Reply
A variable that is in the Pipeline to the msgBody variable in
the Input Signature of the Put service or the Request/Reply
service.
Get, Peek,
Request/Reply
The msgBody variable in the Output Signature of the Get,
Peek, or Request/Reply service to a variable that is in the
Pipeline Editor.
5 Adapter Services
156 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
To test adapter services
1 Review the steps in Before Configuring or Managing Adapter Services on page 90.
2 If you are using Developer, set the view to the Test perspective.
3 In Developer or Designer, expand the package and folder that contain the service you
want to test.
4 Double-click the service you want to test.
Developer or Designer displays the configured service in the service template's
Adapter Service Editor.
5 Perform one of the following
If you are using Developer, select Test > Run.
If you are using Designer, select Run > Run As > Run Service.
6 For every service input field, you will be prompted to enter an input value. Enter a
value for each input field and then click OK.
7 Click the Results tab in Developer or Service Result tab in Designer to view the output
from this service.
Viewing Adapter Services
You use the Developer or Designer to view adapter services.
To view a service
1 Review the steps in Before Configuring or Managing Adapter Services on page 90.
2 In Developer or Designer, expand the package and folder that contain the service you
want to view.
3 Double-click the service you want to view.
Developer or Designer displays the configured service in the service template's
Adapter Service Editor.
Editing Adapter Services
You use Developer or Designer to edit adapter services.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 157
5 Adapter Services
To edit an adapter service
1 In Designer, browse to and open the adapter service that you want to edit.
2 Double-click the service that you want to edit.
Designer displays the adapter service in the service template's Adapter Service
Editor.
3 Do one of the following:
If you have the VCS Integration feature enabled, right-click the service and select
Check Out.
If you do not have the VCS Integration feature enabled, right-click the service and
select Lock for Edit.
If you are using the local service development feature, from the Team menu in
Designer, select the appropriate option to check out the service. The options
available in the Team menu depend on the VCS client that you use.
4 Modify the values for the adapter service's parameters as needed. For detailed
descriptions of the service's parameters, see the section on configuring a service for
the specific type of service you want to edit.
5 After you complete your modifications, save the service and do one of the following:
If you have the VCS Integration feature enabled, right-click the service and select
Check In. Enter a check-in comment and click OK.
If you do not have the VCS Integration feature enabled, right-click the service and
select Unlock.
If you are using the local service development feature, from the Team menu in
Designer, select the appropriate option to check in the service. The options
available in the Team menu depend on the VCS client that you use.
6 Save the service.
Deleting Adapter Services
You use Developer or Designer to delete adapter services.
To delete a service
1 Review the steps in Before Configuring or Managing Adapter Services on page 90.
2 In Developer or Designer, expand the package and folder that contain the service that
you want to edit.
3 Right-click the service you want to delete and then select Delete.
5 Adapter Services
158 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Enabling Automatic Data Validation
Developer or Designer enables WebSphere MQ Adapter to validate user-defined data for
adapter services at design time. You can validate the values for a single adapter service or
you can configure Developer or Designer to always validate the values for adapter
services. Both options could potentially slow your design-time operations.
For more information about the Adapter Service/Notification Editor and other Developer or
Designer menu options and toolbar icons, see the Developer users guide or Designer
Service Development online help for your release. See About this Guide for specific
document titles.
Enabling Data Validation for a Single Adapter Service
When you enable data validation for a single adapter service, Developer or Designer
compares the service values against the resource data that has already been fetched from
the selected adapter.
To enable automatic data validation for a single adapter service
1 Review the steps in Before Configuring or Managing Adapter Services on page 90.
2 In Developer or Designer, expand the package and folder that contain the service for
which you want to enable automatic validation.
3 Double-click the service for which you want to validate the data.
Developer or Designer displays the configured adapter service in the service
template's Adapter Service Editor.
4 Click the icon.
Enabling Validation for All Adapter Services
If you select the option to always validate values for adapter services, it will do so for all
webMethods WmART-based adapters installed on Integration Server.
To always validate the values for all adapter services
1 Review the steps in Before Configuring or Managing Adapter Services on page 90.
2 Start Developer or Designer.
3 Perform one of the following:
If you are using Developer, select the Tools > Options >Integration Server> Adapter
Service/Notification Editor item.
If you are using Designer, select the Window > Preferences >Software AG> Service
Development > Adapter Service/Notification Editor item.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 159
5 Adapter Services
4 Enable the Automatic data validation option.
5 Click OK.
Reloading Adapter Values
You can enable WebSphere MQ Adapter to reload and validate user-defined data for
adapter services at design time in Developer or Designer. You can reload values for a
single adapter service or you can configure Developer or Designer so it automatically
reloads the values for adapter services. Both options could potentially slow your design-
time operations.
For more information about the Adapter Service/Notification Editor and other Developer or
Designer menu options and toolbar icons, see the Developer users guide or Designer
Service Development online help for your release. See About this Guide for specific
document titles.
Reloading Adapter Values for a Single Adapter Service
When you reload adapter values for a single adapter service, Developer or Designer
compares the service values against the resource data that has already been fetched from
the selected adapter.
To reload the adapter values for a single adapter service
1 Review the steps in Before Configuring or Managing Adapter Services on page 90.
2 In Developer or Designer, expand the package and folder that contain the service for
which you want to enable automatic validation.
3 Double-click the service for which you want to validate the data.
Developer or Designer displays the configured adapter service in the service
template's Adapter Service Editor.
4 Click the icon.
Reloading Adapter Values for All Adapter Services
If you select the option to always reload values for adapter services, it will do so for all
webMethods WmART-based adapters installed on the Integration Server.
To reload the adapter values for all adapter services
1 Review the steps in Before Configuring or Managing Adapter Services on page 90.
2 Start Developer or Designer.
5 Adapter Services
160 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
3 Perform one of the following:
If you are using Developer, select the Tools > Options >Integration Server> Adapter
Service/Notification Editor item.
If you are using Designer, select the Window > Preferences >Software AG> Service
Development > Adapter Service/Notification Editor item.
4 Enable the Automatic polling of adapter metadata option.
5 Click OK.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 161
6 Adapter Notifications
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Listener Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
6 Adapter Notifications
162 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Overview
This chapter describes how to configure and manage listeners and listener notifications.
For a detailed description of WebSphere MQ Adapter listeners, see Listeners on
page 44. For a detailed description of the available WebSphere MQ Adapter listener
notifications, see Listener Notifications on page 44.
Listeners
Before you Configure New Listeners
Perform the following tasks before configuring new listeners.
Before you configure a new listener
1 Install webMethods Integration Server and WebSphere MQ Adapter on the same
machine. For details, see Installing, Upgrading, and Uninstalling WebSphere MQ
Adapter on page 53.
2 Make sure that you have webMethods administrator privileges so that you can access
WebSphere MQ Adapter administrative screens. For information about setting user
privileges, see the Integration Server administration guide for your release. See
About this Guide for specific document titles.
3 Start Integration Server and Integration Server Administrator, if they are not already
running.
4 Using Integration Server Administrator, make sure that the WmMQAdapter package
is enabled. To verify the status of the WmMQAdapter package, see Enabling
Packages on page 61.
5 Using webMethods Developer or Software AG Designer, create a user-defined
package to contain the listener, if you have not already done so. For more information
about managing packages, see Package Management on page 59.
Note: If you are using Developer 6.1 or later, use the Edit perspective for all
procedures unless stated otherwise. If you are using Designer, use the Service
Development perspective. For more information, see the Developer users guide or
Designer Service Development online help for your release. See About this Guide
for specific document titles.
6 Using Integration Server Administrator, configure a valid connection. For more
information about configuring connections, see Adapter Connections on page 69.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 163
6 Adapter Notifications
Configuring New Listeners
When you configure WebSphere MQ Adapter listeners, you specify information that
Integration Server uses to perform the following tasks:
Filter messages based on certain criteria
Enable listeners to listen for, and get messages on, a specified queue
You configure WebSphere MQ Adapter listeners using Integration Server Administrator
for both single-queue and multi-queue listeners.
Single-Queue Listeners
When configuring a connection, you can select multiple queues. When you configure a
single-queue listener, the adapter will create a listener that will listen only to the first
queue from the list of queues configured in the connection.
Multi-Queue Listeners
When configuring a connection, you can select multiple queues. When you configure a
multi-queue listener, the adapter will create one listener node (child) for each queue
specified in the connection, and one multi-queue listener node (parent). Each child
listener will be listening to a particular queue.
All the child listener nodes are named after the queue they listen to, prefixed by the
parent listener name and is separated by an underscore. For example: If the multi-queue
listener name is MultiQueueListener that is listening to Queue1 and Queue2, then the
child listeners name will be:
Folder1:MultiQueueListener_Queue1
Folder1:MultiQueueListener_Queue2
Note: Folder1 is the folder under which the listener is configured.
Configuring a New Listener
Perform the following procedure to configure a new listener.
To configure a new listener
1 In the Adapters menu in the navigation area of Integration Server Administrator, click
WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, click Listeners.
3 On the Listeners screen, click Configure New Listener.
6 Adapter Notifications
164 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
4 On the Listener Types screen, select the type of listener:
To configure a single-queue listener, click WebSphere MQ Single-Queue Listener
Service.
To configure a multi-queue listener, click WebSphere MQ Multi-Queue Listener Service.
5 On the Configure Listener Type screen, in the WebSphere MQ Adapter section, use
the following fields:
Important! The listener name is prefixed by the folder name and is separated by a
colon. For example: If the folder name is "Folder1" and the listener name is
"Listener1", then the listener name in the "Listeners" screen will be
"Folder1:Listener1".
Parameter Description/Action
Package The package in which to create the listener.
Create the listener in a user-defined package rather than in
the adapter's package. For other important considerations
when creating packages for WebSphere MQ Adapter, see
Package Management on page 59.
You must create the package using Developer or Designer
before you can specify it using this parameter. For general
information about creating packages, see the Developer users
guide or Designer Service Development online help for your
release. See About this Guide for specific document titles.
Folder Name The folder in which to create the listener.
Listener Name The name of the listener that listens for messages on a queue.
Connection Name The connection to associate with the listener.
From the list of connections, select an appropriate connection
that you created on the Configure Connections Type screen.
You must use a transactional connection with listeners.
Important! If you are using the adapter with Integration Server
8.0 SP1 or earlier, adapter services cannot use connections
that are also used for adapter listeners. However, listeners can
share connections with other listeners.
Retry Limit The number of times the adapter tries to reconnect if the
adapter fails to connect, or loses connection with the Queue
Manager. Default: 5
Retry Backoff
Timeout
The number of seconds that elapse between each of the retries
specified in the retry limit. Default: 10
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 165
6 Adapter Notifications
6 In the Listener Properties section, use the following fields:
Note: An asterisk (*) next to the filter fields indicates that WebSphere MQ Adapter
passes the messages that match the filter criteria to the notification. Messages that do
not match the specified filter criteria remain on the queue.
Parameter Description/Action
Wait Interval (msec) The time period that the listener waits for a message to
appear on the queue before responding to a shutdown
request from WebSphere MQ Adapter. Enter this value in
milliseconds. Default: 60000
Filter on Message ID* The listener instructs WebSphere MQ to deliver only those
messages that match the specified Message ID value within
the MQMD Header of each message.
If you use the filter criteria of the Message ID parameter with
an asynchronous notification, then you need to set the
following value, otherwise the trigger will only be executed
once.
If you are using Integration Server 6.1 or later, then use
Developer or Designer to set the Detect duplicates property on
the trigger to false. For more information about setting this
parameter, see the Integration Server publish-subscribe
developers guide for your release. See About this Guide for
specific document titles.
Filter on Correlation
ID*
The listener instructs WebSphere MQ to deliver only those
messages that match the specified Correlation ID value
within the MQMD Header of each message.
Filter on Group ID* The listener instructs WebSphere MQ to deliver only those
messages that match the specified Group ID value within the
MQMD Header of each message.
Filter on Sequence
Number*
The listener instructs WebSphere MQ to deliver only those
messages that match the specified Sequence Number value
within the MQMD Header of each message.
Filter on Offset* The listener instructs WebSphere MQ to deliver only those
messages that match the specified Offset value within the
MQMD Header of each message.
6 Adapter Notifications
166 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Dead Letter Queue
Name
The name of the queue that will contain any messages that
could not reach their destination.
If you do not specify a value for this field, then
WebSphere MQ Adapter does not move the message to a
dead letter queue if the message could not reach its
destination.
If a message passes the filter criteria for the listener, but does
not match any notification filter criteria, then the message is
moved to the dead letter queue once it has passed the backout
threshold.
Dead Letter Queue
Manager Name
The name of the queue manager for the dead letter queue.
Headers to include in
Dead Letter Message
Select which headers to include in the message sent to the
dead letter queue:
None Use when you do not want to include any headers
along with the original payload in the message sent to the
dead letter queue.
DLH Use when you want to include only the DLH header
along with the original payload in the message sent to the
dead letter queue.
MQMD Use when you want to include only the MQMD
header along with the original payload in the message
sent to the dead letter queue.
DLH_&_MQMD Use when you want to include both DLH
and MQMD headers along with the original payload in
the message sent to the dead letter queue.
Default: DLH_&_MQMD
Note: If you are using a listener configured using
WebSphere MQ Adapter, the listener refers to the watt
property watt.WmMQAdapter.deadLetterMessageHeaders. If this watt
property is not set, then WebSphere MQ Adapter sets
Headers to include in Dead Letter Message parameter to a
default value DLH_&_MQMD.
Backout Threshold The number of times to retrieve the message before it is sent
to the dead letter queue. For example, specify 1 to attempt to
retrieve the message once.
Parameter Description/Action
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 167
6 Adapter Notifications
7 Click Save Listener.
Important! If you have configured a connection by selecting multiple queues, the
single-queue listener will listen to the first queue in the selected list, and the multi-
queue listener will create a single-queue listener for each queue selected in the list.
Open Queue in
Shared Mode?
Select how the queue is opened:
True Use in shared mode to allow simultaneous access to
the queue by other applications.
False Use in exclusive mode to prevent simultaneous
access to the queue by other applications.
Convert Application
Data?
Select whether the service converts the message to the local
character set and encoding:
Checked The messages read using this service will be
converted to the local character set and encoding.
Unchecked The messages read using this service will not be
converted to the local character set and encoding.
Default: Checked
Note: If the property is Checked and the message format does
not match the local character set and encoding, a warning
message appears.
Note: If you are using listeners configured using
WebSphere MQ Adapter, the default value is Checked.
Inherit Parent
Listener's
Properties?
This parameter is available only for multi-queue listeners and
it is used only by child listeners.
Select the properties the child listener should refer to:
True Use the properties configured for the parent listener.
False Use the properties configured for this particular
listener by overriding the properties configured for the
parent listener.
Default: False
Note: For a parent listener, this property does not have any
significance. It is always set to False for a parent listener.
Parameter Description/Action
6 Adapter Notifications
168 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Behavior of Listeners
Listeners exhibit different behaviors when they are associated with either a transactional
connection or a non-transactional connection.
Listeners and Transactional Connections
A listener that is associated with a transactional connection exhibits the following
behavior:
The Listener monitors the queue.
The Listener receives a message. (WebSphere MQ Adapter tags this message as
unavailable, but the adapter does not remove the message from the queue.)
If the message matches all of the selection criteria for any notification, then the
notification processes the message.
If the notification processes the message, then the Listener commits the message.
(WebSphere MQ Adapter removes the message from the queue.)
If no notification processes the message, then the Listener rolls back the message.
(WebSphere MQ Adapter tags this message as available.)
Listeners and Non-Transactional Connections
A listener that is associated with a non-transactional connection exhibits the following
behavior:
The Listener monitors the queue.
The Listener receives a message. (WebSphere MQ Adapter removes this message
from the queue.)
If the message matches all of the selection criteria for any notification, then the
notification processes the message.
However, if the message does not match the selection criteria for the notification, then
the notification discards the message.
Testing Listeners
In general, you can test listeners to ensure that you have configured them correctly.
To test a listener
1 Configure a listener using Integration Server Administrator. For instructions on how
to configure a listener, see Configuring New Listeners on page 163.
2 Configure a listener notification using Developer or Designer. For instructions on
how to configure a notification, see Configuring Listener Notifications on page 178.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 169
6 Adapter Notifications
3 Enable the listener notification using Integration Server Administrator. For
instructions on how to enable a listener notification, see Enabling Listener
Notifications on page 195.
4 Enable the listener using Integration Server Administrator. For instructions on how to
enable a listener, see Enabling Listeners on page 174.
5 Make a change in your back-end system to activate the listener. For example, put a
message on a queue.
The listener searches for filters and returns messages that match the filter criteria that
you specified when you configured the listener on the Configure Listener Type
screen. Filtered messages are then sent to the listener notification for further
processing.
For more information on how listeners and listener notifications work at run time,
refer to the following sections: Listener Transactionality on page 47 and Runtime
Processing of Listeners and Synchronous Listener Notifications on page 49.
Viewing Listener Parameters
You can view a listener's parameters from Integration Server Administrator, Developer,
or Designer. You can also view the notification order of a listener.
Viewing Listener Parameters Using Integration Server Administrator
Perform the following procedure to view listener parameters using Integration Server
Administrator.
To view a listener's parameters using Integration Server Administrator
1 In the Adapters menu in the navigation area of Integration Server Administrator, click
WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, click Listeners.
When using the adapter with Integration Server 8.0 and later, you can sort and filter
the list of listeners that appears on the Listeners screen.
To sort information on the Listeners screen, click the Up and Down arrows at the
top of the column you want to sort.
To filter the list of listeners:
6 Adapter Notifications
170 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
i On the Listeners screen, click Filter Listeners.
ii Type the criterion by which you want to filter into the Filter criteria box.
Filtering is based on the node name, not the listener name. To locate all
listeners containing specific alphanumeric characters, use asterisks (*) as
wildcards. For example, if you want to display all listeners containing the
string "abc", type *abc* in the Filter criteria box.
iii Click Submit. The Listeners screen displays the connections that match the
filter criteria.
iv To re-display all listeners, click Show All Listeners.
The Listeners screen appears, listing all the current listeners. You can control
the number of listeners that are displayed on this screen. For more
information, see Controlling Pagination on page 51.
3 On the Listeners page, click the icon for the listener that you want to see.
The View Listener screen displays the parameters for the listener. For descriptions of
the listener parameters, see Configuring New Listeners on page 163.
4 Click Return to WebSphere MQ AdapterListeners to return to the main listeners screen.
Viewing Listener Parameters Using Developer or Designer
Perform the following procedure to view listener parameters using Developer or
Designer.
To view a listener's parameters using Developer or Designer
1 Review the steps in Before you Configure New Listeners on page 162.
2 From Developer or Designer, expand the package and folder in which the listener is
located.
3 Double-click the listener you want to view.
The parameters for the listener appear on the Listener Information tab. For descriptions
of the listener properties, see Configuring New Listeners on page 163.
Viewing the Notification Order of a Listener
Perform the following procedure to view the notification order of a listener.
To view the notification order of a listener
1 In the Adapters menu in the navigation area of Integration Server Administrator, click
WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, click Listeners.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 171
6 Adapter Notifications
3 On the Listeners screen, click the icon for the listener that you want to view.
The View Notification Order screen displays the order of the notifications for the
listener. To change the notification order for the listener, see Editing the Notification
Order of a Listener on page 172.
4 Click Return to WmMQAdapter to return to the Edit Listener screen.
Editing Listeners
You use Integration Server Administrator to edit the listener in the following situations:
If you need to select a newly configured connection, or if you need to change any
listener properties, such as filter values, you can update the listener parameters.
If you need to change the order of the notifications that are associated with the
listener. For more information, see Editing the Notification Order of a Listener on
page 172.
Updating Listener Parameters
Important! You can change the connection alias of a child listener, but the adapter ignores
the change while saving. No error message is displayed but the adapter will not save the
change.
To update listener parameters
1 In the Adapters menu in the navigation area of Integration Server Administrator, click
WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, click Listeners.
3 On the Listeners screen, make sure that the listener is disabled before editing. To
disable the listener, see Disabling Listeners on page 175.
4 On the Listeners screen, click the icon for the listener that you want to edit.
The Edit Listener screen displays the current parameters for the listener. Update the
listener's parameters by typing or selecting the values you want to specify.
For descriptions of the listener parameters, see Configuring New Listeners on
page 163.
5 Click Save Changes to save the listener and return to the Listeners screen.
Important! If you change the Queue Name parameter of the connection associated with
a multi-queue listener, you must also open the multi-queue listener for edit and save
the listener so that the adapter can re-create the listeners.
6 Adapter Notifications
172 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Editing the Notification Order of a Listener
Important! You are allowed to change the notification order of the child listeners only if a
child listener is directly associated with notifications (not inheriting the notifications from
the parent). The link to change the notification order is inactive for the child listeners that
do not have any notifications configured.
To edit the notification order of a listener
1 In the Adapters menu in the navigation area of Integration Server Administrator, click
WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, click Listeners.
3 On the Listeners screen, make sure that the listener is disabled before editing. To
disable the listener, see Disabling Listeners on page 175.
4 On the Listeners screen, click the icon for the listener that you want to edit.
5 On the Edit Listener screen, click Edit Notification Order.
6 On the Edit Notification Order screen, use the Up and Down buttons to determine the
processing order in which WebSphere MQ Adapter invokes the notifications.
Note: For better processing results, arrange your notifications from ascending to
descending order starting with the most detailed notifications to the least detailed
notifications. For more information on notifications and their filter criteria, see
Considerations for Listener Notifications on page 176.
7 Click Save Changes to save the notification order of the listener.
8 Click Return to WmMQAdapter to return to the Edit Listener screen.
Copying Listeners
You can copy an existing listener to create a new listener with the same or similar
properties without having to type or specify all properties for the listener. You copy
adapter listeners using Integration Server Administrator.
Note: You cannot copy a child listener. If you copy a parent listener, the associated child
listeners are created with the new parent listener name as the prefix.
Note: If you provide a duplicate name while creating a listener or if the adapter generated
name of the child listener is a duplicate (another listener node with the same name as the
adapter generated child listener name), the listener is not created.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 173
6 Adapter Notifications
To copy a listener
1 In the Adapters menu in the navigation area of Integration Server Administrator, click
WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, click Listeners.
3 On the Listeners screen, click the icon for the listener that you want to copy.
The Copy Listener screen displays the current parameters for the listener that you
want to copy. Name the new listener and edit any listener parameters as needed by
typing or selecting the values you want to specify.
For descriptions of the listener parameters, see Configuring New Listeners on
page 163.
4 Click Save Changes to save the listener and return to the Listeners screen.
Deleting Listeners
If you no longer want to use a listener, use the following instructions to delete the listener.
You use Integration Server Administrator to delete listeners.
Important! If you delete a WebSphere MQ Adapter listener, any notifications that are
defined to use the listener will no longer work. You cannot change which listener a
notification uses after the notification is configured. However, you can change the
parameters for an existing listener. For instructions, see Editing Listeners on page 171.
Important! You cannot delete a child listener. If you delete a parent listener, all the child
listeners associated with that parent will be deleted.
To delete a listener
1 In the Adapters menu in the navigation area of the Integration Server Administrator,
click WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, click Listeners.
3 On the Listeners screen, make sure that the listener is disabled. To disable the listener,
see Disabling Listeners on page 175.
4 On the Listeners screen, click for the listener you want to delete.
Integration Server deletes the listener.
6 Adapter Notifications
174 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Enabling Listeners
Before you enable a listener, you need to configure one or more notifications to associate
with the listener. If no notifications are configured when you enable the listener, then the
Integration Server Administrator displays the following warning message: "No
notifications for listener."
After you have configured your notifications, you must enable the listener so that the
associated notifications will communicate appropriately with the listener at run time.
You enable the listeners using the Integration Server Administrator. For more
information on configuring listeners and notifications, see the sections on Configuring
New Listeners on page 163 and Configuring Listener Notifications on page 178.
Note: When you reload a package that contains enabled listeners, the listeners will
automatically be enabled when the package reloads. If the package contains listeners that
are disabled, they will remain disabled when the package reloads.
Note: You cannot enable a child listener. If you enable a parent listener, all the child
listeners associated with that parent will be enabled.
To enable a listener
1 In the Adapters menu in the navigation area of the Integration Server Administrator,
click WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, click Listeners.
3 The Listeners screen appears.
If you are running Integration Server version 6.1 SP1 or later, click No in the
Enabled column for the listener you want to enable.
Integration Server Administrator enables the listener and displays a and Yes in
the Enabled column.
If you are running Integration Server version 6.5, select Enabled from the drop-
down list in the State field.
Integration Server Administrator enables the listener.
The Enable all suspended link helps you change the state quickly for multiple
listeners.
Suspending Listeners
You must be running Integration Server to suspend a listener.
Note: In WebSphere MQ Adapter, a suspended listener behaves identically to a disabled
listener.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 175
6 Adapter Notifications
Note: You cannot suspend a child listener. If you suspend a parent listener, all the child
listeners associated with that parent will be suspended.
To suspend a listener
1 In the Adaptersmenu in the navigation area of the Integration Server Administrator,
click WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, click Listeners.
3 On the Listeners screen, select Suspended from the drop-down list in the State field.
Integration Server Administrator suspends the listener.
The Suspend all enabled link helps you change the state quickly for multiple listeners.
When you suspend a listener, the action may not take effect right away. You may have to
wait as long as the time specified in the Wait Interval parameter for the listener. If one or
more messages appear on the queue within that time interval, the adapter may receive
and process the first message.
Disabling Listeners
Listeners must be disabled before you can edit or delete them. You disable listeners using
Integration Server Administrator.
Note: In WebSphere MQ Adapter, a disabled listener behaves identically to a suspended
listener.
Note: You cannot disable a child listener. If you disable a parent listener, all the child
listeners associated with that parent will be disabled.
To disable a listener
1 In the Adaptersmenu in the navigation area of the Integration Server Administrator,
click WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, click Listeners.
3 On the Listeners screen, select Disabled from the drop-down list in the State field.
Integration Server Administrator disables the listener.
When you disable a listener, the action may not take effect right away. You may have to
wait as long as the time specified in the Wait Interval parameter for the listener. If one or
more messages appear on the queue within that time interval, the adapter may receive
and process the first message.
6 Adapter Notifications
176 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Listener Notifications
The following sections provide instructions for configuring and managing
WebSphere MQ Adapter listener notifications. WebSphere MQ Adapter has two types of
listener notifications that you can configure:
Asynchronous Listener Notifications
Synchronous Listener Notifications
For more information on how listener notifications work, see Listener Notifications on
page 44.
Before you Configure Listener Notifications
Perform the following tasks before configuring listener notifications.
Before you configure a listener notification
1 Install webMethods Integration Server and WebSphere MQ Adapter on the same
machine. For details, see Installing, Upgrading, and Uninstalling WebSphere MQ
Adapter on page 53.
2 Make sure that you have webMethods administrator privileges so that you can access
the WebSphere MQ Adapter's administrative screens. For information about setting
user privileges, see the Integration Server administration guide for your release. See
About this Guide for specific document titles.
3 Start Integration Server and Integration Server Administrator, if they are not already
running.
4 Using Integration Server Administrator, make sure that the WmMQAdapter package
is enabled. To verify the status of the WmMQAdapter package, see Enabling
Packages on page 61.
5 Configure a listener using Integration Server Administrator. For more information on
how to configure a new listener, see Configuring New Listeners on page 163.
6 Using Developer or Designer, create a user-defined package to contain the listener, if
you have not already done so. For more information about managing packages, see
Package Management on page 59.
Considerations for Listener Notifications
For more efficient message processing to Integration Server, make sure that you validate
the notification filter criteria when configuring listener notifications so that it does not
conflict with the listener filter criteria. For example, if both a listener and its notification
filter on the same field but specify different values, the notification filter criteria can never
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 177
6 Adapter Notifications
match. In this case, the listener will remove the message off the queue because it passed
the listener filter criteria. However, the notification will not be processed because the
value of the field will not have a match value for the notification filter criteria.
Using Asynchronous and Synchronous Listener Notifications
The following table lists the tasks required to use these types of notifications:
Task Task Use this tool...
1 Configure an adapter connection. For details,
see Configuring WebSphere MQ Adapter
Connections on page 70.
Integration Server
Administrator
2 Select the appropriate notification template
and configure the notification. For
instructions for configuring notifications, see
Configuring Listener Notifications on
page 178.
Developer or Designer
3 If you plan to use an Integration Server flow
or Java service, design it to react to the data
changes contained in the notification's
publishable document. Configure an
Integration Server trigger to use the
notification's publishable document. For
instructions on configuring notifications, see
the Developer users guide or Designer
Service Development online help for your
release. See About this Guide for specific
document titles.
To process the message from the queue, you
should create an Integration Server trigger
that subscribes to the Integration Server
document type that WebSphere MQ Adapter
created with the asynchronous notification.
For more information about using triggers,
see the Integration Server publish-subscribe
developers guide for your release. See
About this Guide for specific document
titles.
Developer or Designer
4 Enable the adapter notifications. For
instructions on how to enable listener
notifications, see Enabling Listener
Notifications on page 195.
Integration Server
Administrator
6 Adapter Notifications
178 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Configuring Listener Notifications
WebSphere MQ Adapter has two types of listener notifications that you can configure:
Asynchronous Listener Notifications
Synchronous Listener Notifications
For a description of the asynchronous and synchronous listener notifications, see
Listener Notifications on page 44. You configure listener notifications using the
Developer or Designer.
Configuring an Asynchronous Listener Notification
Perform the following procedure to configure an asynchronous listener notification.
To configure a WebSphere MQ asynchronous listener notification
1 Review the steps in Before you Configure Listener Notifications on page 176.
2 Start Developer or Designer.
3 Perform one of the following:
If you are using Developer, select File > New > Adapter Notification and click Next.
If you are using Designer, perform the following:
i Right-click the package in which the notification should be contained and
select New > Adapter Notification.
ii Select the parent namespace and type a name for the adapter notification.
iii Click Next.
4 Select WebSphere MQ Adapter as the adapter type and click Next.
5 Select WebSphere MQ Asynchronous Listener Notification as the template and click Next.
6 Select the appropriate Notification Listener Name and click Next.
7 If you are using Developer, select a package and folder to contain the notification,
type a unique name for the notification, and click Next.
8 Click Finish.
9 Developer or Designer creates an asynchronous listener notification and an
asynchronous publishable document type, and the editor for the adapter notification
appears.
a You can select the Adapter Settings tab at any time to confirm listener notification
properties such as the Adapter Name, Adapter Listener Name, and Adapter Notification
Template as necessary.
b In the Publish Document section, you can specify how you want the notification
document to be published:
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 179
6 Adapter Notifications
To publish documents to Broker, select webMethods Broker/Local. This is the
default option.
To publish documents to a JMS provider, select JMS Provider, and provide
values for the following input fields:
Connection alias name--Specify the name of the JMS connection alias configured
on Integration Server.
Destination name--Specify the name of the JMS connection alias configured on
Integration Server.
Destination type--Specify whether the destination is a Queue (default) or a Topic.
10 Select the MQMD Header tab to specify which optional msgHeader property fields and
constant values the asynchronous notification will use. The msgHeader property
fields that you select in the Output Field Names column appear within the signature of
the Asynchronous Publishable Document on the Document Type tab.
Use the following icons to manage the rows on the MQMD Header tab:
To define new Output Field Names, select the Insert Row icon (or the Fill in all
rows to the table icon ).
To change the order of Output Field Names to ensure the parameters are parsed in
the correct order, use the Shift Up or Shift Down icons.
To delete any Output Field Names, use the Remove row icon .
You can add the following msgHeader property fields to the Input Field Name column
and the Output Field Name column. In the MQMD Header, Filter Criteria refers to specific
values that must be present in the header of the actual message in order for this
notification to process it. You must select the Use for Input check box next to each
property in order for the notification to use the filter criteria for that property.
msgHeader Property Data Type Maximum Field Length for Constant Value
AccountingToken* String 32 alphanumeric single-byte characters
AccountingTokenByteArray* Byte Array 32 bytes
ApplIdentityData String 32 alphanumeric single-byte characters
ApplOriginData String 4 alphanumeric single-byte characters
BackoutCount String 4 digits
CodedCharSetId String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of MQCCSI_Q_MGR.
CorrelId* String 24 alphanumeric single-byte characters
CorrelationIdByteArray* Byte Array 24 bytes
6 Adapter Notifications
180 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Encoding String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of 273 Native.
Expiry String 4 digits
Feedback String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of MQFB_NONE.
Format String 8 alphanumeric single-byte characters
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of (NONE).
GroupId* String 24 alphanumeric single-byte characters
GroupIdByteArray* Byte Array 24 bytes
MsgFlags String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of None.
MsgId* String 24 alphanumeric single-byte characters
MsgIdByteArray* Byte Array 24 bytes
MsgType String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of Datagram.
MsgSeqNumber String 4 digits
Offset String 4 digits
OriginalLength String 4 digits
msgHeader Property Data Type Maximum Field Length for Constant Value
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 181
6 Adapter Notifications
Note: An asterisk * indicates that you can enter these properties either as a string or as
a byte array. For example, AccountingToken and AccountingTokenByteArray refer to the
same msgHeader property. If you specify values and select the Use for Input check box
for both properties, then the byte array value will be used.
11 Select the JMS Properties tab to identify the optional JMS property fields that the
asynchronous notification will use.
Use the following icons to manage the rows on the JMS Properties tab:
To define new JMS property fields, select the Insert Row icon (or the Fill in all
rows to the table icon ).
To change the order of JMS property fields to ensure the parameters are parsed in
the correct order, use the Shift Up or Shift Down icons
To delete any JMS property fields, use the Remove row icon .
You can add the following optional JMS property fields:
Persistence String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of Not Persistent.
Priority String 4 digits
Note: If this field is left blank, then the
WebSphere MQ Adapter enters a
default value based on the default
priority of the queue.
PutApplName String 24 alphanumeric single-byte characters
PutApplType String 4 digits
PutDate String 8 digits
PutTime String 8 digits
ReplytoQueueMgr String 48 alphanumeric single-byte characters
ReplyToQ String 48 alphanumeric single-byte characters
Report String 4 digits
UserIdentifier String 12 alphanumeric single-byte characters
msgHeader Property Data Type Maximum Field Length for Constant Value
6 Adapter Notifications
182 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Note: An "X" in the JMS property name indicates that the property is provider specific.
The remaining JMS properties are generic, delivered by any JMS provider.
You can also add your own folders and properties to the JMS Properties.
Use the following icons to manage the rows for User-Defined Properties on the JMS
Properties tab:
To define new folders and properties, select the Insert Row icon .
Enter the new folder and property. For example, enter "jms.usr.usr1". The "jms"
and "usr" are the names of the folders and "usr1" is the name of the property.
All the folders and properties you add will be under JMSProperties as part of the
publishable document of the adapter service.
JMS Property Data Type
JMSDestination String
JMSExpiration String
JMSPriority String
JMSDeliveryMode String
JMSCorrelationID String
JMSCorrelationIDByteArray Byte Array
JMSReplyTo String
JMSType String
JMSMessageID String
JMSTimestamp String
JMSRedelivered String
JMSXGroupID String
JMSXGroupIdByteArray Byte Array
JMSXGroupSeq String
JMSXUserID String
JMSXAppID String
JMSXDeliveryCount String
MCDMessageDomain String
MCDMessageSet String
MCDMessageFormat String
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 183
6 Adapter Notifications
Note: The property name has to be prefixed with a folder name. You cannot use
"JMSProperties" and "mcd" as the first folder name.
To change the order of User-Defined property fields to ensure the parameters are
parsed in the correct order, use the Shift Up or Shift Down icons.
To delete any User-Defined property fields, use the Remove row icon .
In an asynchronous publishable document, you can only edit parameters on the
Publishable Properties tab.
12 From the File menu, select Save.
13 Select the publishable document that is associated with the asynchronous
notification.
14 Select the Publication Properties tab to select a storage type and set a time-to-live value.
In an asynchronous publishable document, you can only edit parameters on the
Publishable Properties tab:
6 Adapter Notifications
184 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
15 From the File menu, select Save.
Configuring a Synchronous Listener Notification
Perform the following procedure to configure a synchronous listener notification.
Property Description/Action
Storage type For a publishable document type, you can set a storage type
property to specify the steps Integration Server and Broker
will take to ensure that a document does not get lost if a
resource fails. Select the appropriate setting:
Volatile Offers a faster, but less reliable type of storage than
guaranteed. Volatile documents move through
Integration Server faster than guaranteed documents
because volatile documents are not acknowledged.
Volatile documents will be lost if the resource on which
the volatile document resides (Integration Server or
Broker) fails or shuts down. Specify volatile storage for
documents that have a short life or are not critical.
Guaranteed Guaranteed storage offers a safer, but slower
type of document storage. Integration Server saves
guaranteed documents in a disk-backed document store
using a process that ensures that guaranteed documents
are never lost. Guaranteed documents move through
Integration Server more slowly than volatile documents.
Use guaranteed storage for documents that you cannot
afford to lose. If the resource (Integration Server or
Broker) that contains the guaranteed document fails or
shuts down, the resource recovers the guaranteed
documents when the resource restarts.
For more discussion on volatile and guaranteed storage
types, see the Integration Server publish-subscribe
developers guide for your release. See About this Guide for
specific document titles.
Time to live The length of time the document type is allowed to stay on
Integration Server, before it is thrown away. Select the
appropriate setting that indicates how Integration Server
processes the document type:
Never discard Specifies that the Broker should never
discard instances of the publishable document type.
Discard after Specifies that the Broker should discard
instances of the publishable document type after the
specified time elapses. Specify the time interval in
seconds, minutes, hours, days, weeks, months, or years.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 185
6 Adapter Notifications
To configure a WebSphere MQ synchronous listener notification
1 Review the steps in Before you Configure Listener Notifications on page 176.
2 Start Developer or Designer.
3 Perform one of the following:
If you are using Developer, select File > New > Adapter Notification and click Next.
If you are using Designer, perform the following:
i Right-click the package in which the notification should be contained and
select New > Adapter Notification.
ii Select the parent namespace and type a name for the adapter notification.
iii Click Next.
4 Select WebSphere MQ Adapter as the adapter type and click Next.
5 Select WebSphere MQ Synchronous Listener Notification as the template and click Next.
6 Select the appropriate Notification Listener Name and click Next.
7 Select the appropriate Service Node and click Next.
8 If you are using Developer, select a package and folder to contain the notification,
type a unique name for the notification, and click Next.
9 Click Finish.
The Adapter Notification template creates the following items:
A Synchronous Listener Notification
Two Synchronous Document Types:
A Synchronous Reply Document Type
A Synchronous Request Document Type
Note: You cannot edit any fields or properties on the Publications Properties tab for the
Synchronous Request and Reply Document Types. Integration Server does not
publish these document types.
6 Adapter Notifications
186 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
10 Select the MQMD Header tab to specify which optional msgHeader property fields the
synchronous notification will use.
Use the following icons to manage the rows on the MQMD Header tab:
To define new Request Field Names or Reply Field Names, select the Insert Row icon
(or the Fill in all rows to the table icon ).
To change the order of the input or output fields to ensure the parameters are
parsed in the correct order, use the Shift Up or Shift Down icons.
To delete any input field names or output field names, use the Remove row icon
.
You can add the following optional msgHeader Elements to the Request Field Name
column (input) and the Reply Field Name column (output).
The selected Request Field Names appear within the signature of the Synchronous
Request Document on the Document Type tab.
The selected Reply Field Names appear within the signature of the Synchronous
Reply Document on the Document Type tab.
Maximum field lengths apply only to the Request Field Names in the Constant Value
column:
msgHeader Property Data Type Maximum Field Length for Constant Value
AccountingToken* String 32 alphanumeric single-byte characters
AccountingTokenByteArray* Byte Array 32 bytes
ApplIdentityData String 32 alphanumeric single-byte characters
ApplOriginData String 4 alphanumeric single-byte characters
BackoutCount String 4 digits
CodedCharSetId String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of MQCCSI_Q_MGR.
CorrelId* String 24 alphanumeric single-byte characters
CorrelationIdByteArray* Byte Array 24 bytes
Encoding String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of 273 Native.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 187
6 Adapter Notifications
Expiry String 4 digits
Feedback String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of MQFB_NONE.
Format String 8 alphanumeric single-byte characters
Note: If this field is left blank, then the
WebSphere MQ Adapter enters a
default value of (NONE).
GroupId* String 24 alphanumeric single-byte characters
GroupIdByteArray* Byte Array 24 bytes
MsgFlags String 4 digits
Note: If this field is left blank, then
WebSphere MQ Adapter enters a
default value of None.
MsgId* String 24 alphanumeric single-byte characters
MsgIdByteArray* Byte Array 24 bytes
MsgType String 4 digits
Note: If this field is left blank, then the
WebSphere MQ Adapter enters a
default value of Datagram.
MsgSeqNumber String 4 digits
Offset String 4 digits
OriginalLength String 4 digits
Persistence String 4 digits
Note: If this field is left blank, then the
WebSphere MQ Adapter enters a
default value of Not Persistent.
msgHeader Property Data Type Maximum Field Length for Constant Value
6 Adapter Notifications
188 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Note: An asterisk * indicates that you can enter these properties either as a string or as
a byte array. For example, AccountingToken and AccountingTokenByteArray refer to the
same msgHeader property. If you specify values for both properties, then the byte
array value will be used.
11 Select the JMS Properties tab to identify the optional JMS property fields that the
synchronous notification will use. The selected JMS property fields display within the
signature of the Synchronous Request document on the Document Type tab.
Use the following icons to manage the rows on the JMS Properties tab:
To define new JMS property fields, select the Insert Row icon (or the Fill in all
rows to the table icon ).
To change the order of JMS properties to ensure the parameters are parsed in the
correct order, use the Shift Up or Shift Down icons.
To delete any JMS properties, use the Remove row icon .
Select the following optional JMS property fields:
Priority String 4 digits
Note: If this field is left blank, then the
WebSphere MQ Adapter enters a
default value based on the default
priority of the queue.
PutApplName String 24 alphanumeric single-byte characters
PutApplType String 4 digits
PutDate String 8 digits
PutTime String 8 digits
ReplytoQueueMgr String 48 alphanumeric single-byte characters
ReplyToQ String 48 alphanumeric single-byte characters
Report String 4 digits
UserIdentifier String 12 alphanumeric single-byte characters
JMS Property Data Type
JMSDestination String
JMSExpiration String
JMSPriority String
msgHeader Property Data Type Maximum Field Length for Constant Value
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 189
6 Adapter Notifications
Note: An "X" in the JMS property name indicates that the property is provider specific.
The remaining JMS properties are generic, delivered by any JMS provider.
You can also add your own folders and properties to the JMS Properties.
Use the following icons to manage the rows for User-Defined Properties on the JMS
Properties tab:
To define new folders and properties, select the Insert Row icon .
Enter the new folder and property. For example, enter "jms.usr.usr1". The "jms"
and "usr" are the names of the folders and "usr1" is the name of the property.
All the folders and properties you add will be under JMSProperties as part of the
RequestDocument of the adapter service.
JMSDeliveryMode String
JMSCorrelationID String
JMSCorrelationIDByteArray Byte Array
JMSReplyTo String
JMSType String
JMSMessageID String
JMSTimestamp String
JMSRedelivered String
JMSXGroupID String
JMSXGroupIdByteArray Byte Array
JMSXGroupSeq String
JMSXUserID String
JMSXAppID String
JMSXDeliveryCount String
MCDMessageDomain String
MCDMessageSet String
MCDMessageFormat String
JMS Property Data Type
6 Adapter Notifications
190 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Note: The property name has to be prefixed with a folder name. You cannot use
"JMSProperties" and "mcd" as the first folder name.
To change the order of User-Defined property fields to ensure the parameters are
parsed in the correct order, use the or icons.
To delete any User-Defined property fields, use the Remove row icon .
12 Select the Adapter Settings tab, to view the adapter properties and to select the
appropriate service name for the synchronous notification.
a The following fields in the Adapter Properties section are read-only:
b Specify one of the following modes in the Execution Mode section:
To invoke a flow service directly, select Service Invoke and specify the Service
Name field as the name of the service that you selected when you initially
configured the adapter listener notification. You can select a different service
by clicking the browse icon to the right of the Service Name field.
Important! Before you select a different service, make sure that you have disabled
the notification. When the notification is enabled, then the new service is utilized.
For more information on enabling and disabling listeners, see Enabling
Listeners on page 174 and Disabling Listeners on page 175.
To publish documents locally or to a Broker and wait for a reply, select Publish
and Wait and specify the following fields:
Local--Select true to publish documents locally (to Integration Server only) or
false to publish to the Broker connected to Integration Server. If no Broker is
configured for Integration Server, documents will be published locally.
Wait Time--Specify the number of milliseconds to wait for a reply. The default is
-1, which means to wait indefinitely.
13 From the File menu, select Save.
Adapter Properties Description
Adapter Name The name of the adapter.
Adapter Listener
Name
The name of the adapter listener that you selected when
you configured the synchronous notification.
Adapter Notification
Template
The name of the adapter notification template that you
selected when you configured the synchronous
notification.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 191
6 Adapter Notifications
Behavior of Listener Notifications
WebSphere MQ Adapter handles messages depending on how you have configured
listeners and listener notifications in your system. For example, messages behave
differently when the following combinations are set up in your WebSphere MQ Adapter:
Transactional or non-transactional listeners
The transactionality of a listener depends on the transactionality of the connection.
For example, when you associate a non-transactional connection with a listener, then
the listener is non-transactional.
Transactional or non-transactional asynchronous notifications
The transactionality of an asynchronous notification depends on the transactionality
of a listener. For example, when you associate a non-transactional listener with an
asynchronous notification, then the asynchronous notification is non-transactional.
Transactional or non-transactional synchronous notifications
The transactionality of a synchronous notification depends on the transactionality of
a listener. For example, when you associate a non-transactional listener with a
synchronous notification, then the synchronous notification is non-transactional.
If the listener and either asynchronous or synchronous
notification have the following behavior, Then the WebSphere MQ Adapter...
The filter criteria of a non-transactional listener
matches a message's property fields,
AND
The filter criteria of a non-transactional
asynchronous notification does not match a
message's property fields,
...throws the message away.
The filter criteria of a non-transactional listener
matches a message's property fields,
AND
The filter criteria of a non-transactional
synchronous notification does not match a
message's property fields,
...throws the message away.
The filter criteria of transactional listener
matches a message's property fields,
AND
The filter criteria of a transactional asynchronous
notification does not match does not match a
message's property fields,
...rolls the message to the dead
letter queue.
6 Adapter Notifications
192 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Testing Listener Notifications
You can test listener notifications to ensure that you have configured them correctly.
To test listener notifications
1 Configure a listener using Integration Server Administrator. For instructions on how
to configure a listener, see Configuring New Listeners on page 163.
2 Configure a listener notification using Developer or Designer. For instructions on
how to configure a notification, see Configuring Listener Notifications on page 178.
3 Enable the listener notification using Integration Server Administrator. For
instructions on how to enable a listener notification, see Enabling Listener
Notifications on page 195.
4 Enable the listener using Integration Server Administrator. For instructions on how to
enable a listener, see Enabling Listeners on page 174.
5 Make a change in your back-end system to activate the listener. For example, put a
message on a queue.
The listener searches for, filters, and returns messages that match the filter criteria
that you specified when you configured the listener on the Configure Listener Type
screen. Filtered messages are then sent to the listener notification for further
processing.
For more information on how listeners and listener notifications work at run time,
refer to the following sections: Listener Transactionality on page 47 and Runtime
Processing of Listeners and Synchronous Listener Notifications on page 49.
Testing Publishable Document Types
You can test a publishable document type that is associated with an asynchronous
notification running it in Developer or Designer. When you test a publishable document
type, you provide input values that Developer or Designer uses to create an instance of
the publishable document type. You also specify a publishing method (such as publish,
publish and wait, deliver, or deliver and wait). Developer or Designer then publishes a
The filter criteria of a transactional listener
matches a message's property fields,
AND
The filter criteria of a transactional synchronous
notification does not match a message's property
fields,
...rolls the message to the dead
letter queue.
If the listener and either asynchronous or synchronous
notification have the following behavior, Then the WebSphere MQ Adapter...
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 193
6 Adapter Notifications
document and displays the results of the publish in the Results dialog box. Testing a
publishable document type provides a way for you to publish a document without
building a service that does the actual publishing. If you select a publication action where
you wait for a reply document, you can verify whether or not reply documents are
received.
Note: Prior to running the PublishDocument, you need to make sure that you uncheck the
Field must exist at run-time field on the msgBody property. To access this field, right-click on
msgBody, select Properties, and then select the Constraints tab. When you test a publishable
document type, Integration Server actually publishes the document locally or to Broker
(whichever is specified).
For instructions on how to test a publishable document type, see the Integration Server
publish-subscribe developers guide for your release. See About this Guide for specific
document titles.
Envelope parameters define the sender's address, the time the document was sent,
password and certificate information, and other useful information for routing and
control. For a complete description of the envelope parameters located in the WmPublic
folder, see the Integration Server built-in services reference guide for your release. See
About this Guide for specific document titles.
Viewing Listener Notifications
You use Developer or Designer to view listener notifications.
To view a listener notification
1 Review the steps in Before you Configure Listener Notifications on page 176.
2 In Developer or Designer, expand the package and folder that contain the listener
notification you want to view.
3 Select the listener notification you want to view.
Developer or Designer displays the configured listener notification in the adapter's
Adapter Notification Editor.
Editing Listener Notifications
You use Developer or Designer to edit listener notifications, both synchronous and
asynchronous.
Note: Because listener notifications inherently depend on listeners, you cannot change a
listener for a listener notification after you configure it.
6 Adapter Notifications
194 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
To edit a listener notification
1 Review the steps in Before you Configure Listener Notifications on page 176.
2 In Developer or Designer, expand the package and folder that contain the listener
notification you want to edit.
3 Select the listener notification you want to edit.
Developer or Designer displays the configured listener notification in the adapter's
Adapter Notification Editor.
4 Do one of the following:
If you have the VCS Integration feature enabled, right-click the notification and
select Check Out.
If you do not have the VCS Integration feature enabled, right-click the notification
and select Lock for Edit.
If you are using the local service development feature, from the Team menu in
Designer, select the appropriate option to check out the notification. The options
available in the Team menu depend on the VCS client that you use.
5 Open the listener notification and modify the notification's parameter values as
needed. For detailed descriptions of the notification parameters, see Configuring
Listener Notifications on page 178.
6 After you complete the modifications, save the notification and do one of the
following:
If you have the VCS Integration feature enabled, right-click the notification and
select Check In. Enter a check-in comment and click OK.
If you do not have the VCS Integration feature enabled, right-click the notification
and select Unlock.
If you are using the local service development feature, from the Team menu in
Designer, select the appropriate option to check in the notification. The options
available in the Team menu depend on the VCS client that you use.
Editing Publishable Document Types
You use Developer or Designer to edit the publishable document type associated with the
asynchronous listener notifications. However, you cannot edit the request and reply
document types that are associated with synchronous listener notifications.
To edit an asynchronous publishable document type
1 Review the steps in Before you Configure Listener Notifications on page 176.
2 In Developer or Designer, expand the package and folder that contain the publishable
document type that you want to edit.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 195
6 Adapter Notifications
3 Select the asynchronous publishable document type that you want to edit.
Developer or Designer displays the configured asynchronous publishable document
type in the adapter's Adapter Listener Editor.
4 Select the Publication Properties tab, and modify the available values for the document
type's parameters as needed. For detailed descriptions of the asynchronous document
type's parameters, see Configuring an Asynchronous Listener Notification on
page 178.
Deleting Listener Notifications
If you no longer want to use a particular WebSphere MQ Adapter listener notification,
you can delete it by following the instructions in this section. You delete listener
notifications, both synchronous and asynchronous, using Developer or Designer.
Important! If you delete a synchronous listener notification, then the associated request
and reply document types are automatically deleted. If you delete an asynchronous
listener notification, then the associated publishable document type is automatically
deleted. You cannot individually delete the document types associated with the
synchronous and asynchronous listener notifications.
To delete a listener notification
1 Review the steps in Before you Configure Listener Notifications on page 176.
2 In Developer or Designer, expand the package and folder that contain the listener
notification you want to delete.
3 Right-click the listener notification and click Delete.
Enabling Listener Notifications
After you configure an listener notification, you need to enable it using Integration Server
Administrator.
To enable a listener notification
1 In the Adapters menu in the navigation area of Integration Server Administrator, click
WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, select Listener Notifications.
3 On the Listener Notifications screen, click No in the Enabled column for the listener
notification you want to enable.
Integration Server Administrator enables the listener notification and displays a
and Yesin the Enabled column.
6 Adapter Notifications
196 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Disabling Listener Notifications
You disable listener notifications using Integration Server Administrator.
To disable a listener notification
1 In the Adapters menu in the navigation area of Integration Server Administrator, click
WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, select Listener Notifications.
3 On the Listener Notifications screen, click Yes in the Enabled column for the listener
notification you want to disable.
The listener notification becomes disabled and you see a No in theEnabled column.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 197
7 Logging and Exception Handling
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Adapter Logging Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Adapter Message Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Adapter Exception Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Adapter Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Adapter Tracing Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Enabling Tracing When Using WebSphere MQ Version 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
7 Logging and Exception Handling
198 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Overview
This chapter describes message logging, exception handling, and tracing for
WebSphere MQ Adapter.
To view the list of error codes and supporting information, see Adapter Error Codes on
page 201.
Adapter Logging Levels
WebSphere MQ Adapter uses the Integration Server logging mechanism to log messages.
You can configure and view the Integration Server logs to monitor and troubleshoot the
WebSphere MQ Adapter. For detailed information about logging in Integration Server,
including instructions for configuring and viewing the different kinds of logs supported
by the server, see the webMethods logging guide for your release. See About this Guide
for specific document titles.
Beginning with Integration Server 7.1, you can configure different logging levels for
WebSphere MQ Adapter.
Accessing Adapter Logging Information
Perform the following procedure to access the adapter's logging information.
To access the adapter's logging information
1 From the webMethods Integration Server Administrator screen, select Settings >
Logging.
The View Server Logger Details screen appears.
2 In the Server Logger Configuration box, go to Facility > Adapters.
3 Expand the Adapters tree to see a list of all installed adapters with their code number
and adapter description, along with the logging level.
Changing Adapter Logging Settings
Perform the following procedure to change the adapter's logging settings.
To change logging settings for the adapter
1 From the Integration Server Administrator screen, select Settings > Logging.
2 From the Logging Settings screen, select Edit Logging Settings. Select the required Level
of logging for the WebSphere MQ Adapter.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 199
7 Logging and Exception Handling
3 After making your changes, click Save Changes.
For complete information about specifying the amount and type of information to
include in the log, see the webMethods logging guide for your release. See About
this Guide for specific document titles.
Adapter Message Logging
Integration Server maintains several types of logs; however, WebSphere MQ Adapter
only logs messages to the audit, error, and server logs. Because WebSphere MQ Adapter
works in conjunction with the WmART package, the adapter's messages and exceptions
typically appear within log messages for the WmART package.
The following table shows the logging levels for WebSphere MQ Adapter:
WebSphere MQ Adapter log messages appear in the following format, ADA.0600.nnnnc,
where:
ADA is the facility code that indicates that the message is from an adapter.
0600 (or 600) is the WebSphere MQ Adapter major code, which indicates that the
error is generated by WebSphere MQ Adapter.
nnnn represents the error's minor code. For detailed descriptions of WebSphere MQ
Adapter minor codes, see Adapter Error Codes on page 201.
c represents the message's severity level (optional).
Integration Server Log Description
Integration Server 7.1 or
higher
Audit You can monitor individual adapter
services using the audit log as you would
audit any service in Integration Server.
The audit properties for an adapter
service are available in the
WebSphere MQ Adapter service template
on the Audit tab.
Error WebSphere MQ Adapter automatically
posts fatal-level and error-level log
messages to the error log. These log
messages appear as adapter run-time
messages.
Server WebSphere MQ Adapter posts messages
to the server log, depending on how the
server log is configured. Fatal-level
through debug-level log messages appear
as adapter run-time log messages. Trace-
level log messages appear as
WebSphere MQ Adapter log messages.
7 Logging and Exception Handling
200 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
To monitor WebSphere MQ Adapter log messages in the Server log, ensure that your
server log's logging settings are configured to monitor the following facilities:
0113 Adapter Runtime (Managed Object)
0114 Adapter Runtime
0115 Adapter Runtime (Listener)
0116 Adapter Runtime (Notification)
0117 Adapter Runtime (Adapter Service)
0118 Adapter Runtime (Connection)
0121 Adapter Runtime (SCC Transaction Manager)
0126 Adapter Runtime (SCC Connection Manager)
Overriding Adapter Messages
You can set different log levels in watt.WmMQAdapter.logLeveloverride for certain
WebSphere MQ Adapter messages and also specify the Message ID value and its log level
as:
msgId=level,msgId=level...
where: msgId can be any WebSphere MQ Adapter message Id.
level can be an integer between 0 to 10.
"comma" is the delimiter.
For more information about working with extended configuration settings, see the
Integration Server administration guide for your release. See About this Guide for
specific document titles.
Adapter Exception Handling
If a WebSphere MQ Adapter object (for example, a connection or service) encounters an
error with the WebSphere MQ system, it will throw an adapter error coupled with the
WebSphere MQ error, exactly as it was thrown by IBM.
For example, if a Request/Reply service fails on the WebSphere MQ system at run time
because the adapter invoked the service with a transactional connection, you will receive
an adapter error. This error indicates that the Request/Reply service failed, and the
adapter error will contain the specific error generated on the WebSphere MQ system
indicating why the service failed. In this case, you would receive a WebSphere MQ error
specifying that the Request/Reply services requires a non-transactional connection.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 201
7 Logging and Exception Handling
Adapter Error Codes
The following table lists WebSphere MQ Adapter minor codes and provides information
on the error message, reason, and possible action for each error.
ADA.0600.1020 Get completed with conditionCode=conditionCode, reasonCode=reasonCode
Cause: This information message is generated to provide additional debug information
when a Get service returns a non-zero reason code.
Response: Refer to the WebSphere MQ manuals to determine the meaning of the reason
code.
ADA.0600.1030 Put completed with conditionCode=conditionCode, reasonCode=reasonCode
Cause: This information message is generated to provide additional debug information
when a Put service returns a non-zero reason code.
Response: Refer to the WebSphere MQ manuals to determine the meaning of the reason
code.
ADA.0600.1040 Peek completed with conditionCode=conditionCode, reasonCode=reasonCode
Cause: This information message is generated to provide additional debug information
when a Peek service returns a non-zero reason code.
Response: Refer to the WebSphere MQ manuals to determine the meaning of the reason
code.
ADA.0600.1050 - Request/Reply completed with conditionCode=conditionCode,
reasonCode=reasonCode
Cause: This information message is generated to provide additional debug information
when a Request/Reply service returns a non-zero reason code.
Response: Refer to the WebSphere MQ manuals to determine the meaning of the reason
code.
ADA.0600.1051 Request/Reply requires a valid, non-null value in theMQMDPropertyNameproperty of
the msgHeader
Cause: The Request/Reply service was invoked with a null value in the specified
msgHeader property. This property must contain a non-null value.
Response: Specify a non-null value for this property.
ADA.0600.1052 Request/Reply service requires a non-transactional connection
Cause: The Request/Reply service was invoked with a transactional connection. The
Request/Reply service requires a non-transactional connection.
Response: Modify the configuration of this service to use a non-transactional connection.
ADA.0600.1055 Exception caught action: exceptionMessage
Cause: A Java Exception has been caught.
7 Logging and Exception Handling
202 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Response: Determine the cause of the exception and correct the problem. If necessary,
provide this information to a Software AG Global Support representative.
ADA.0600.2055 Exception caught: exceptionMessage
Cause: A Java Exception has been caught.
Response: Determine the cause of the exception and correct the problem. If necessary,
provide this information to a Software AG Global Support representative.
ADA.0600.2062 PCFQuery could not connect to the Queue Manager queueManagerName-
reasoncode=reasonCode
Cause: The PCFQuery class could not connect to the specified queue manager. The
PCFQuery class is used when retrieving the list of available queues on a queue manager.
Response: Determine the cause of the exception and correct the problem. If necessary,
provide this information to a Software AG Global Support representative.
ADA.0600.2063 PCFQuery sent to queueManagerNamefailed, compcode=conditionCode,
reasoncode=reasonCode
Cause: The PCFQuery class sent a command to the specified Queue Manager, but it failed.
The PCFQuery class is used when retrieving the list of available queues on a Queue
Manager.
Response: Refer to the WebSphere MQ manuals to determine the meaning of the reason
code.
ADA.0600.3020 MsgBody must be a byte[], a String, or a Serializable Object. Found dataType
Cause: The msgBody property could not be set because it contained an invalid object. The
supported data types are byte array, string, or a serializable object.
Response: Provide a msgBody property that contains a valid data type.
ADA.0600.3032 Queue Manager queueManagerNamehas disconnected, waiting milliseconds
milliseconds before reconnecting
Cause: A fatal Exception has been caught, and the connection to the specified Queue
Manager has been lost. The adapter will attempt to reconnect in milliseconds milliseconds.
Response: Look for other error messages in the server log to determine why the
connection to the queue manager was lost.
ADA.0600.3033 Connection to Queue Manager queueManagerNamecould not be initialized;
conditionCodeand reasonCode
Cause: The adapter could not connect to the specified queue manager.
Response: Refer to the WebSphere MQ manuals to determine the meaning of the reason
code.
ADA.0600.3034 Queue queueNamecould not be opened for Input/Output/Inquire; exceptionMessage
Cause: The specified queue could not be opened successfully.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 203
7 Logging and Exception Handling
Response: Determine the cause of the exception and correct the problem. If necessary,
provide this information to a Software AG Global Support representative.
ADA.0600.3035 Unable to put message to queue queueNameon queueManagerName; condition code
is conditionCode, reason code is reasonCode.
Cause: The adapter failed to put a message to the specified queue on the specified queue
manager.
Response: Refer to the WebSphere MQ manuals to determine the meaning of the reason
code.
ADA.0600.3036 Unable to get message from queue queueNameon queueManagerName; condition
code is conditionCode, reasonCode is reasonCode.
Cause: The adapter failed to get a message from the specified queue on the specified
Queue Manager.
Response: Refer to the WebSphere MQ manuals to determine the meaning of the reason
code.
ADA.0600.3037 Unable to peek message on queue queueNameon queueManagerName;
conditionCode is conditionCode,reasonCode is reasonCode.
Cause: The adapter failed to peek at a message on the specified queue on the specified
Queue Manager.
Response: Refer to the WebSphere MQ manuals to determine the meaning of the reason
code.
ADA.0600.3038 Unable to commit message(s) on queue queueNameon queueManagerName;
conditionCode=conditionCode, reasonCode=reasonCode.
Cause: The adapter failed to commit an active transaction on the specified queue on the
specified queue manager.
Response: Refer to the WebSphere MQ manuals to determine the meaning of the reason
code.
ADA.0600.3039 Unable to rollback message(s) on a queue queueNameon queueManagerName;
conditionCode is conditionCode, reasonCode is reasonCode.
Cause: The adapter failed to rollback an active transaction on the specified queue using
the Queue Manager.
Response: Refer to the WebSphere MQ manuals to determine the meaning of the reason
Code.
ADA.0600.3040 Service serviceNamemoved a message to the DeadLetterQueue
deadLetterQueueName.
Cause: One of the following errors occurred: 1) a message could not be delivered to a
specified queue, or 2) a message was received whose Backout Count property exceeded
the Backout Threshold for this service.
7 Logging and Exception Handling
204 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Response: Look for other error messages in the server log to determine the cause of the
problem.
ADA.0600.3041 Failure attempting to move message to the DeadLetterQueue deadLetterQueueName.
Error: errorMessage
Cause: One of the following errors occurred: 1) a message could not be delivered to the
specified dead letter queue, or 2) A message was received whose Backout Count property
exceeded the Backout Threshold for this service. However, the adapter could not move
the message to the dead letter queue, due to another error.
Response: Look for other error messages in the server log to determine the cause of the
initial problem. Note that in watt.WmMQAdapter.includeDataInError3041, you can set
whether the 3041 message should include a hex dump of the payload data of the message
that could not be written to the dead letter queue in the server log. Valid values are
(true|false). The default is false (do not include the hex dump).
ADA.0600.3044 A warning was received while putting a message to queue queueName:
MQExceptionMessage
Cause: An MQException with condition code = WARNING was caught while putting a
message to the specified queue.
Response: Look for other error messages in the server log to determine the cause of the
initial problem.
ADA.0600.3045 Unable to inquire the queue manager qmgr name; condition code is mq condition
code, reason code is mq reason code
Cause: Unable to inquire the queue manager.
Response: Look for the reason code returned by WebSphere MQ and take corrective
action mentioned in the WebSphere MQ documentation.
ADA.0600.3046 Unable to inquire the queue name on qmgr name; condition code is mq condition
code, reason code is mq reason code
Cause: Unable to inquire the queue.
Response: Look for the reason code returned by WebSphere MQ and take the corrective
action mentioned in the WebSphere MQ documentation.
ADA.0600.3099 The message received by Listener listenerNamewas not processed by any
Notification
Cause: A message was received by the specified listener, but none of the associated
Notifications support the message type.
Response: Look for other error messages in the server log to determine why the
notifications do not support the message.
ADA.0600.4011 Exception caught while loading exit exitName. (exceptionType)exit Name
Cause: Error occurred when WebSphere MQ Adapter attempted to load the specified exit
class.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 205
7 Logging and Exception Handling
Response: Determine the cause of the exception and correct the problem. If necessary,
provide this information to a Software AG Global Support representative.
ADA.0600.5001 PCFMessageAgent could not connect to QueueManager qmgr name;
conditionCode=completion code, reasonCode=reason code
Cause: Unable to connect to the queue manager.
Response: Look for the reason code returned by WebSphere MQ and take the corrective
action mentioned in the WebSphere MQ documentation.
ADA.0600.5002 Unable to execute PCF command name; conditionCode=completion code,
reasonCode=reason code
Cause: Unable to execute the PCF command.
Response: Look for the reason code returned by WebSphere MQ and take the corrective
action mentioned in the WebSphere MQ documentation. Possible causes could be:
Required parameters not provided.
Provided parameter values are not valid.
Command that is being executed is not supported on the backend platform.
ADA.0600.5003 Error while reading the parameter <parameter name> from the response.
conditionCode=<completion code>, reasonCode=<reason code>
Cause: The response parameter requested is not available in the responses returned from
the command execution.
Response: None.
ADA.0600.5004 Error while parsing the PCFCommands metadata file
WmPCFCommandMetadataFile.xml
Cause: Error occurred with a corrupt xml file or when the xml file not confirming to the
DTD.
Response: Copy the original WmPCFCommandMetadataFile.xml file into the config
folder of the WmMQAdapter package.
Adapter Tracing Settings
To help you troubleshoot adapter services and adapter notifications, the WebSphere MQ
Adapter enables you to trace data that is provided by WebSphere MQ. Use the
WebSphere MQ Adapter tracing capabilities when instructed by Software AG Global
Support to locate errors and to troubleshoot problems. This section discusses the
following tasks:
Configuring Tracing Settings
Archiving Tracing Files
Clearing Tracing Files
7 Logging and Exception Handling
206 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Refreshing Tracing Files
Enabling Tracing When Using WebSphere MQ Version 7
Configuring Tracing Settings
If you are using WebSphere MQ version 6, use webMethods Integration Server
Administrator to configure tracing settings. However, if you are using WebSphere MQ
version 7, you cannot use Integration Server Administrator for tracing. You must enable
tracing using the procedure in Enabling Tracing When Using WebSphere MQ Version 7
on page 208. Also, you cannot archive, clear, or refresh tracing files when using
WebSphere MQ version 7.
Configuring Tracing Settings Using webMethods Integration Server
Administrator
To configure tracing settings using Integration Server Administrator
1 In the Adapters menu in the webMethods Integration Server Administrator navigation
area, click WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, click WebSphere MQ-Level Tracing.
3 From the WebSphere MQ-Level Tracing screen, select the following settings:
Archiving Tracing Files
To archive tracing files, use Integration Server Administrator.
Field Description/Action
WebSphere MQ
Trace Status
Select the following trace status for the WebSphere MQ Adapter:
Enabled Displays tracing messages in the WebSphere MQ-
Level Tracing screen
Disabled Does not trace any messages.
Default: Disabled
WebSphere MQ
Trace Level
Select the level of tracing from 0-5 from the list, where 0 is the
lowest level of tracing.
The adapter automatically outputs all messages at the level you
select, as well as higher-level messages. For example, if you
select 2, the adapter outputs all messages from levels 0 and 1 as
well.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 207
7 Logging and Exception Handling
To archive a tracing file
1 In the Adapters menu in the Integration Server Administrator navigation area, click
WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, click WebSphere MQ-Level Tracing.
3 From the WebSphere MQ-Level Tracing screen, in theArchive Trace File field, type the
name of the file that will contain the trace archive information.
4 Click Archive Trace File and then clickOK.
The status of the archive trace file appears at the top of the WebSphere MQ-Level
Tracing screen as TRACE_ARCHIVED - file=<filename\>
Note: The information in the trace file is archived to the fully qualified file name that
you specified. If you do not specify a directory path, the file is saved in the Integration
Server_directory directory, where IntegrationServer is the directory in which you
installed the Integration Server components. Also, if the trace file does not already
exist, then WebSphere MQ Adapter creates the file.
Clearing Tracing Files
If you no longer need the trace file, then clear trace entries using Integration Server
Administrator.
To clear a tracing file
1 In the Adapters menu in the Integration Server Administrator navigation area, click
WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, click WebSphere MQ-Level Tracing.
3 From the WebSphere MQ-Level Tracing screen, click Clear Trace File and click OK.
The trace file is cleared from the WebSphere MQ-Level Tracing screen and the status
of the file appears at the top of the screen as TRACE_CLEARED. When you clear the
trace file from the screen, the contents of the archived trace files are not affected.
Refreshing Tracing Files
If you changed any settings on the tracing console or if WebSphere MQ contains any new
troubleshooting information, then you need to refresh the tracing file to ensure that the
file has the most up-to-date information.
7 Logging and Exception Handling
208 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
To refresh a tracing file
1 In the Adapters menu in the Integration Server Administrator navigation area, click
WebSphere MQ Adapter.
2 In the WebSphere MQ Adapter menu, click WebSphere MQ-Level Tracing.
3 From the WebSphere MQ-Level Tracing screen, click Refresh.
The information on the WebSphere MQ-Level Tracing screen is updated with any
new settings that you specified or with new information from WebSphere MQ.
Enabling Tracing When Using WebSphere MQ Version 7
When using WebSphere MQ version 7, use the following procedure to enable tracing.
To enable a trace when using WebSphere MQ version 7
1 Using a text editor, create a property file.
The recommended values for each property are as follows:
Property Description Recommended Value
Diagnostic.MQ Controls use of WebSphere MQ-
level tracing. Valid values:
enabled Displays trace
messages.
disabled Does not trace
messages.
Default: disabled
enabled
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 209
7 Logging and Exception Handling
Diagnostics.Java Specifies which components are
traced using Java trace. Valid
values:
explorer Diagnostics from
WebSphere MQ Explorer.
soap Diagnostics from the
running process within
WebSphere MQ Transport
for SOAP.
wmqjavaclasses Diagnostics
from the underlying
WebSphere MQ Java classes.
Default: No components are
traced.
soap,
wmqjavaclasses
Diagnostics.Java.Trace.Detail Specifies detail level for Java
trace. Valid values:
high Provides a high level of
detail for the trace.
medium Provides a moderate
level of detail for the trace.
low Provides a low level of
detail for the trace. This
option is unique to Java
trace.
Default: medium
high
Diagnostics.Java.Trace.Destin
ation.File
Specifies whether Java trace is
written to a file. Valid values:
enabled Writes java trace to a
file.
disabled Does not write java
trace to a file.
Default: disabled
enabled
Property Description Recommended Value
7 Logging and Exception Handling
210 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
2 Save the property file anywhere you choose, but make sure the correct path is
provided in the server.bat file.
3 Open the server.bat file located in the Integration Server_directory\bin\server.bat
directory in a text editor.
4 Add the Dcom.ibm.mq.commonservices java system property for the JAVA_RUN
environment variable as follows:
%JAVA_RUN%-Dcom.ibm.mq.commonservices=file_location
where file_location is the location of the property file created in step 1.
For example, %JAVA_RUN%
-Dcom.ibm.mq.commonservices=d:/mq7.txt
After restarting the server, MQ trace will be available under the location specified in
the Diagnostics.Java.Trace.Destination.Pathname property with the format
AMQyyyymmddhhmmsssss.*.TRC.
Diagnostics.Java.Trace.Destin
ation.Console
Specifies whether Java trace is
written to the system console.
Valid values:
enabled Writes java trace to
system console.
disabled Does not write java
trace to system console.
Default: disabled
enabled
Diagnostics.Java.Trace.Destin
ation.Pathname
Specifies the directory to which
Java trace is written.
c:\\tracedir
Diagnostics.Java.FFDC.Desti
nation.Pathname
Specifies the directory to which
Java FFDC output is written.
c:\\errorsdir
Property Description Recommended Value
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 211
A Built-In Transaction Management Services
Transaction Management Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Built-In Transaction Management Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Changing the Integration Server Transaction Timeout Interval . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Transaction Error Situations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
A Built-In Transaction Management Services
212 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
Transaction Management Overview
This appendix provides an overview and examples of using transactions. It describes
how Integration Server supports the built-in services used to manage explicit
transactions for your WebSphere MQ Adapter services in the WmART package. For
descriptions of each of the specific built-in transaction management services that can be
used with the WmART package, see Built-In Transaction Management Services on
page 214.
For information about other build-in services available with the WebSphere MQ Adapter,
see the Integration Server built-in services reference guide for your release. See About
this Guide for specific document titles.
Transactions
Integration Server considers a transaction to be one or more interactions with one or
more resources that are treated as a single logical unit of work. The interactions within a
transaction are either all committed or all rolled back. For example, if a transaction
includes multiple Put services that place messages on a queue, and one or more Put
services fail, then all messages are rolled back.
Transaction Types
WebSphere MQ Adapter supports two-phase commit transactions with WebSphere MQ
locally (LOCAL_TRANSACTION), without other resource participants. WebSphere MQ
Adapter does not support XA Transactions.
Note: WebSphere MQ Adapter can handle logical units of work with another adapter
resource that supports XA_TRANSACTIONS. However, WebSphere MQ Adapter can
only communicate with one resource at a time.
For a description of the transactions types supported by WebSphere MQ Adapter, see
Transaction Management of WebSphere MQ Adapter Connections on page 24.
Implicit and Explicit Transactions
Implicit transactions are automatically handled by the Integration Server transaction
manager. When you define an explicit transaction, you define the start-on-completion
boundaries of the transaction. As such, implicit and explicit transactions need to be
created and managed differently.
The following sections describe implicit and explicit transactions and how to manage
them.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 213
A Built-In Transaction Management Services
Implicit Transactions
With implicit transactions, Integration Server automatically manages local transactions
without requiring you to explicitly do anything. That is, Integration Server starts and
completes an implicit transaction with no additional service calls required by the adapter
user.
A transaction context, which the transaction manager uses to define a unit of work, starts
when an adapter service is encountered in a flow service execution. The connection
required by the adapter service is registered with the newly created context and used by
the adapter service. If another adapter service is encountered, the transaction context is
searched to see if the connection is already registered. If the connection is already
registered, the adapter service uses this connection. If the connection is not registered, a
new connection instance is retrieved and registered with the transaction.
Note that if the top level flow invokes another flow, adapter services in the child flow use
the same transaction context.
When the top level flow completes, the transaction is completed and is either committed
or rolled back, depending on the status (success or failure) of the top level flow.
A single transaction context can contain no more than one LOCAL_TRANSACTION
connection. If your flow contains adapter services that use more then one
LOCAL_TRANSACTION connection, you must use explicit transactions, which are
described in the next section.
For more information about designing and using flows, see the Developer users guide or
Designer Service Development online help for your release. See About this Guide for
specific document titles.
For more information about transaction types, see Transaction Management of
WebSphere MQ Adapter Connections on page 24.
Explicit Transactions
You use explicit transactions when you need to explicitly control the transactional units
of work. To do this, you use additional services, known as built-in services, in your flow.
A transaction context starts when the pub.art.transaction.startTransaction() service is executed.
The transaction context is completed when either the pub.art.transaction.commitTransaction() or
pub.art.transaction.rollbackTransaction() service is executed. As with implicit transactions, a
single transaction context can contain no more than one LOCAL_TRANSACTION
connection.
Note: With explicit transactions, you must be sure to call either a commitTransaction() or
rollbackTransaction() for each startTransaction(); otherwise you will have dangling
transactions that will require you to reboot Integration Server.
A Built-In Transaction Management Services
214 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
A new explicit transaction context can be started within a transaction context, provided
that you ensure that the transactions within the transaction context are completed in the
reverse order they were started. That is, the last transaction to start should be the first
transaction to complete, and so forth.
For example, consider the following is a valid construct:
pub.art.transaction:startTransaction
pub.art.transaction:startTransaction
pub.art.transaction:startTransaction
pub.art.transaction:commitTransaction
pub.art.transaction:commitTransaction
pub.art.transaction:commitTransaction
The following example shows an invalid construct:
pub.art.transaction:startTransaction
pub.art.transaction:startTransaction
pub.art.transaction:commitTransaction
pub.art.transaction:commitTransaction
For more information about designing and using flows, see the Developer users guide or
Designer Service Development online help for your release. See About this Guide for
specific document titles.
For more information about transaction types, see Transaction Management of
WebSphere MQ Adapter Connections on page 24.
Built-In Transaction Management Services
The following sections describe each of the built-in services you can use with the
WmART package.
pub.art.transaction:commitTransaction
This service commits an explicit transaction. It must be used in conjunction with the
pub.art.transaction:startTransaction service. If it does not have a corresponding
pub.art.transaction:startTransaction service, your flow service will receive a runtime error.
For more information about implicit and explicit transactions, see Transaction
Management Overview on page 212.
Input Parameters
commitTransactionInput Document A document that contains the variable
transactionName, described below.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 215
A Built-In Transaction Management Services
Output Parameters
None.
pub.art.transaction:rollbackTransaction
This service rolls back an explicit transaction. It must be used in conjunction with the
pub.art.transaction:startTransaction service. If it does not have a corresponding
pub.art.transaction:startTransaction service, your flow service will receive a runtime error.
For more information about implicit and explicit transactions, see Transaction
Management Overview on page 212.
Input Parameters
Output Parameters
None.
transactionName String Used to associate a name with an explicit transaction.
The transactionName must correspond to the transactionName
in any pub.art.transaction:startTransaction or
pub.art.transaction:rollbackTransaction services associated with the
explicit transaction.
This value must be mapped from the most recent
pub.art.transaction:startTransaction that has not previously been
committed or rolled back.
rollbackTransactionInput Document. A document that contains the variable
transactionName, described below.
transactionName String. Used to associate a name with an explicit
transaction. The transactionName must correspond to the
transactionName in any pub.art.transaction:startTransaction or
pub.art.transaction:commitTransaction services associated with
the explicit transaction.
This value must be mapped from the most recent
pub.art.transaction:startTransaction that has not previously
been committed or rolled back.
A Built-In Transaction Management Services
216 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
pub.art.transaction:setTransactionTimeout
This service enables you to manually set a transaction timeout interval for implicit and
explicit transactions. When you use this service, you are temporarily overriding the
Integration Server transaction timeout interval. To change the server's default transaction
timeout, see Changing the Integration Server Transaction Timeout Interval on
page 217.
You must call this service within a flow before the start of any implicit or explicit
transactions. Implicit transactions start when you call an adapter service in a flow.
Explicit transactions start when you call the pub.art.transaction:startTransaction service.
If the execution of a transaction takes longer than the transaction timeout interval, all
current executions associated with the flow are cancelled and rolled back if necessary.
This service only overrides the transaction timeout interval for the flow service in which
you call it.
Input Parameters
Output Parameters
None.
pub.art.transaction:startTransaction
This service starts an explicit transaction. It must be used in conjunction with either a
pub.art.transaction:commitTransaction service or pub.art.transaction:rollbackTransaction service. If it
does not have a corresponding pub.art.transaction:commitTransaction service or
pub.art.transaction:rollbackTransaction service, your flow service will receive a runtime error.
For more information about implicit and explicit transactions, see Transaction
Management Overview on page 212.
Input Parameters
timeoutSeconds Integer. The number of seconds that the implicit or explicit
transaction stays open before the transaction manager aborts it.
startTransactionInput Document. A document that contains the variable
transactionName, described below.
transactionName String. Specifies the name of the transaction to be started. The
transactionName must correspond to the transactionName in
any pub.art.transaction:rollbackTransaction or
pub.art.transaction:commitTransaction services associated with the
explicit transaction.
webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5 217
A Built-In Transaction Management Services
Output Parameters
Changing the Integration Server Transaction Timeout Interval
The Integration Server default transaction timeout is no timeout (NO_TIMEOUT). To
change the server's transaction timeout interval, use a text editor to modify the server.cnf
file and add the watt.art.tmgr.timeout parameter. Note that this parameter does not exist by
default in the server.cnf file; you must add it to the file as described below.
This transaction timeout parameter does not halt the execution of a flow; it is the
maximum number of seconds that a transaction can remain open and still be considered
valid. For example, if your current transaction has a timeout value of 60 seconds and your
flow takes 120 seconds to complete, the transaction manager will roll back all registered
operations regardless of the execution status.
To change the server's transaction timeout level
1 Shut down Integration Server.
2 Open the server.cnf file.
3 Add the following parameter to the server.cnf file:
watt.art.tmgr.timeout=TransactionTimeout
where TransactionTimeout is the number of seconds before transaction timeout.
4 Restart Integration Server.
5 For more information about adding parameters to the server.cnf file, see the
Integration Server administration guide for your release. See About this Guide for
specific document titles.
Transaction Error Situations
When Integration Server encounters a situation that could compromise transactional
integrity, it throws an error. Such situations include the following:
A transaction includes a resource that only supports local transactions.
startTransactionOutput Document. A document that contains the variable
transactionName, described below.
transactionName String. The name of the transaction the service just started.
The transactionName must correspond to the transactionName
in any pub.art.transaction:rollbackTransaction or
pub.art.transaction:commitTransaction services associated with the
explicit transaction.
A Built-In Transaction Management Services
218 webMethods WebSphere MQ Adapter Installation and Users Guide Version 6.5
If a transaction accesses multiple resources, and more than one of the resources only
supports local transactions, the integrity of the transaction cannot be guaranteed. For
example, if the first resource successfully commits, and the second resource fails to
commit, the first resource interaction cannot be rolled back; it has already been
committed. To help prevent this problem, Integration Server detects this case when
connecting to more than one resource that does not support two-phase commits. It
throws a runtime exception and the service execution fails.
Note: Because this situation may be acceptable in some applications, the adapter user
can include an input in the startTransaction service to cause Integration Server to
allow this situation.
A resource is used in both a parent transaction and a nested transaction.
This situation is ambiguous, and most likely means that a nested transaction was not
properly closed.
A parent transaction is closed before its nested transaction.
After a service request has invoked all its services, but before returning results to the
caller, the service may commit its work. This commit could fail if the resource is
unavailable or rejects the commit. This will cause the entire server request to fail, and to
roll back the transaction.