WebSphere DataPower SOAAppliances · 4/24/2009 · Preface IBM ®WebSphere DataPower SOA...

WebSphere® DataPower SOA Appliances

Integrating with WebSphere MQ

Version 3.7.3

��

NoteBefore using this information and the product it supports, read the information in “Notices and trademarks” on page 69.

First Edition (May 2009)

This edition applies to version 3, release 7, modification 3 of IBM WebSphere DataPower SOA Appliances and to allsubsequent releases and modifications until otherwise indicated in new editions.

© Copyright International Business Machines Corporation 2009.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Preface . . . . . . . . . . . . . . . vWho should read this document . . . . . . . . vHow this document is organized . . . . . . . vPublications . . . . . . . . . . . . . . vi

Installation and upgrade documentation . . . . viAdministration documentation . . . . . . . viDevelopment documentation. . . . . . . . viReference documentation. . . . . . . . . viiIntegration documentation . . . . . . . . viiProblem determination documentation . . . . viiSupplemental documentation . . . . . . . viii

File naming guidelines . . . . . . . . . . viiiObject naming guidelines . . . . . . . . . viiiTypeface conventions . . . . . . . . . . . ix

Chapter 1. Introduction . . . . . . . . 1Software requirements . . . . . . . . . . . 1Multi-Protocol Gateway service . . . . . . . . 1Configuration for integration with WebSphere MQ . 1

DataPower service . . . . . . . . . . . 2MQ Front Side Handler object . . . . . . . 2MQ Queue Manager object . . . . . . . . 2Processing policies . . . . . . . . . . . 3MQ Queue Manager Group . . . . . . . . 3

Basic MQ architecture . . . . . . . . . . . 3Message workflow . . . . . . . . . . . . 4

HTTP to MQ . . . . . . . . . . . . . 5MQ to HTTP . . . . . . . . . . . . . 6

Chapter 2. Routing . . . . . . . . . . 9Determining back-side request routing. . . . . . 9Setting back-side destinations. . . . . . . . . 9Using the MQ URL to set back-side destinations . . 10

Syntax for a static MQ URL . . . . . . . . 10Using the MQ Helper to build a static MQ URL 12Using a static MQ URL in a style sheet . . . . 13Syntax for a dynamic MQ URL . . . . . . . 14

Front Side reply routing . . . . . . . . . . 15

Chapter 3. MQ header values . . . . . 17Injecting and suppressing headers . . . . . . . 17MQ header action . . . . . . . . . . . . 18

Modifying MQMD request headers . . . . . 19Retrieving responses by message ID or bycorrelation ID. . . . . . . . . . . . . 20Modifying MQMD response headers . . . . . 20Modifying reply queue for response . . . . . 21Modifying the queue manager for response. . . 22

Using MQ headers with custom style sheets . . . 23Message descriptor header (MQMD) . . . . . 23IMS Information Header (MQIIH) . . . . . . 27CICS Bridge Header (MQCIH) . . . . . . . 27Object descriptor header (MQOD) . . . . . . 28

WebSphere MQ API support. . . . . . . . . 32

Chapter 4. Units of Work . . . . . . . 35WebSphere MQ client Units of Work capabilities . . 35Units of work implementation . . . . . . . . 36Configuring transactions on a service. . . . . . 38

Units of Work property . . . . . . . . . 39Transactional parameter . . . . . . . . . 39Sync parameter . . . . . . . . . . . . 40MQGMO and MQPMO syncpoint options . . . 40

Common message delivery patterns . . . . . . 40Independent asynchronous delivery . . . . . 41Synchronous delivery . . . . . . . . . . 42

Units of work with other protocols . . . . . . 44Front Side . . . . . . . . . . . . . . 44Back Side . . . . . . . . . . . . . . 44

Chapter 5. Error handling. . . . . . . 45Automatic Retry property . . . . . . . . . 45Process Backend Errors property . . . . . . . 46

When to use the Process Backend Errors property 46Automatic Backout property. . . . . . . . . 46

When to use the Automatic Backout property . . 46Enabling automatic backout . . . . . . . . 46Using the backout settings from the WebSphereMQ server . . . . . . . . . . . . . . 47

The MQ reason code (MQRC) . . . . . . . . 47Reading the MQRC in a style sheet . . . . . 47Returning the MQ error message in a style sheet 48

Using the error-ignore service variable . . . . . 49When to use the error-ignore service variable . . 49Using the error-ignore service variable in a stylesheet . . . . . . . . . . . . . . . 50

Using an error rule . . . . . . . . . . . . 51Datagram traffic with Units of Work disabled . . 52Datagram traffic with Units of Work enabled . . 52Datagram traffic with custom error handling . . 52Request and reply traffic . . . . . . . . . 52

Chapter 6. Additional configurationoptions . . . . . . . . . . . . . . 53Authentication and authorization . . . . . . . 53Monitoring, logging, and status. . . . . . . . 53Ordered messaging . . . . . . . . . . . . 53Using MQ with a Web Service Proxy . . . . . . 54MQ and JMS . . . . . . . . . . . . . . 54Legacy WebSphere MQ service objects . . . . . 55

Appendix A. Referenced objects. . . . 57Event-sink (event-sink) action . . . . . . . . 57MQ Front Side Handler . . . . . . . . . . 58MQ Queue Manager . . . . . . . . . . . 60

Identifying the MQ server . . . . . . . . 60Securing communication with remote queuemanagers . . . . . . . . . . . . . . 60Defining the timeout for dynamic connections . . 61Enable units of work . . . . . . . . . . 62

© Copyright IBM Corp. 2009 iii

Configuring Queue Manager objects . . . . . 63MQ Queue Manager Group . . . . . . . . . 65

Configuring MQ Queue Manager Group objects 65

Appendix B. Getting help and technicalassistance . . . . . . . . . . . . . 67

Searching knowledge bases . . . . . . . . . 67Getting a fix . . . . . . . . . . . . . . 67Contacting IBM Support . . . . . . . . . . 68

Notices and trademarks . . . . . . . 69Trademarks . . . . . . . . . . . . . . 69

iv IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ

Preface

IBM® WebSphere® DataPower® SOA Appliances are purpose-built, easy-to-deploynetwork appliances that simplify, help secure, and accelerate your XML and WebServices deployments while extending your SOA infrastructure. These appliancesoffer an innovative, pragmatic approach to harness the power of SOA whilesimultaneously enabling you to leverage the value of your existing application,security, and Networking infrastructure investments.

Who should read this documentThis document is intended for administrators and application developers whomanage the configuration of services, objects, and associated referenced objectsrelated to integrating with WebSphere MQ on a DataPower appliance. You shouldhave the following knowledge:v Network architecture and conceptsv WebSphere MQ administrationv WebSphere MQ application development

This document assumes that you have installed and configured the appliance asdescribed in the IBM WebSphere DataPower SOA Appliances: Type 9235: InstallationGuide.

How this document is organizedThis document is organized into the following chapters:v Chapter 1, “Introduction”

Provides an overview of sample architecture, appliance configuration objects,and message flow in two examples of DataPower and WebSphere MQintegration.

v Chapter 2, “Routing,” on page 9Provides detailed information about routing.

v Chapter 3, “MQ header values,” on page 17Provides detailed information about handling MQ headers.

v Chapter 4, “Units of Work,” on page 35Provides detailed information about units of worked implementation on aDataPower service.

v Chapter 5, “Error handling,” on page 45Provides detailed information about handling error conditions.

v Chapter 6, “Additional configuration options,” on page 53Provides an overview of additional configuration options such as authenticationand authorization, monitoring, and logging.

v Appendix A, “Referenced objects,” on page 57Provides information on additional configuration options.

v Appendix B, “Getting help and technical assistance”Provides information about contacting IBM Support.

© Copyright IBM Corp. 2009 v

PublicationsThe IBM WebSphere DataPower library is organized into the following categories:v “Installation and upgrade documentation”v “Administration documentation”v “Development documentation”v “Reference documentation” on page viiv “Integration documentation” on page viiv “Problem determination documentation” on page viiv “Supplemental documentation” on page viii

Installation and upgrade documentationv IBM WebSphere DataPower SOA Appliances: 9003: Installation Guide

Provides instructions for installing and powering up the Type 7993 (9003)appliance, creating a startup configuration script, and placing the appliance inoperation.

v IBM WebSphere DataPower SOA Appliances: Type 9235: Installation Guide

Provides instructions for installing and powering up the Type 9235 appliance,creating a startup configuration script, and placing the appliance in operation.

v IBM WebSphere DataPower SOA Appliances: Type 9235: Hardware ProblemDetermination and Service Guide

Provides information about diagnosing and troubleshooting hardware problems,ordering consumable replacement parts, and replacing parts.

v IBM WebSphere DataPower SOA Appliances: Upgrade and Rollback Guide: Generation2 Firmware

Provides instructions for upgrading Generation 2 firmware and for rolling backfirmware upgrades.

Administration documentationv IBM WebSphere DataPower SOA Appliances: Appliance Overview

Provides an introduction and understanding of the IBM Websphere DataPowerSOA appliances.

v IBM WebSphere DataPower SOA Appliances: Administrators Guide

Provides instructions for using the DataPower GUI for managing user access,network access, appliance configuration and system configuration of theappliance.

v IBM WebSphere DataPower SOA Appliances: Hardware Security Module Guide

A user guide for using a Hardware Security Module (HSM) installed in theappliance.

Development documentationv IBM WebSphere DataPower SOA Appliances: XSL Accelerator Developers Guide

Provides instructions for using the WebGUI to configure XSL Proxy and XSLCo-Processor services.

v IBM WebSphere DataPower SOA Appliances: XML Firewall Developers Guide

Provides instructions for using the WebGUI to configure XML Firewall services.v IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers

Guide

vi IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ

Provides instructions for using the WebGUI to configure Web ApplicationFirewall services.

v IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway DevelopersGuide

Provides instructions for using the WebGUI to configure Multiple-ProtocolGateway services.

v IBM WebSphere DataPower SOA Appliances: Web Service Proxy Developers Guide

Provides instructions for using the WebGUI to configure Web Service Proxyservices.

v IBM WebSphere DataPower SOA Appliances: B2B Gateway Developers Guide

Provides instructions for using the WebGUI to configure B2B Gateway services.v IBM WebSphere DataPower SOA Appliances: Low Latency Messaging Developers

Guide

Provides instructions for using the WebGUI to configure a DataPower appliancefor low latency messaging.

Reference documentationv Product-specific documentation for using commands from the command line.

The documentation is specific to each of the following products. Each documentprovides an alphabetical listing of all commands with syntactical and functionaldescriptions.– IBM WebSphere DataPower XML Accelerator XA35: Command Reference

– IBM WebSphere DataPower XML Security Gateway XS40: Command Reference

– IBM WebSphere DataPower XML Integration Appliance XI50: Command Reference

– IBM WebSphere DataPower B2B Appliance XB60: Command Reference

– IBM WebSphere DataPower Low Latency Messaging Appliance XM70: CommandReference

v IBM WebSphere DataPower SOA Appliances: Extension Elements and FunctionsCatalog

Provides programming information about the usage of DataPower XSLTextension elements and extension functions.

Integration documentationThe following documents are available for managing the integration of relatedproducts that can be associated with the DataPower appliance:v Integrating with ITCAM

Provides concepts for integrating the DataPower appliance with IBM TivoliComposite Application Management for SOA.

v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphereTransformation Extender

Provides concepts for integrating the DataPower appliance with WebSphereTransformer Extender.

v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ

Explains the concepts and common use patterns for connecting DataPowerservices to WebSphere MQ systems.

Problem determination documentationv IBM WebSphere DataPower SOA Appliances: Problem Determination Guide

Provides troubleshooting and debugging tools.

Preface vii

Supplemental documentationv Understanding Web Services Policy

Provides conceptual information about how the DataPower appliance can useWeb Services Policy (WS-Policy).

v Understanding WS-Addressing

Provides conceptual information about how the DataPower appliance can useWS-Addressing.

v Understanding LTPA

Provides conceptual information about how the DataPower appliance can useLightweight Third Party Authentication.

v Understanding SPNEGO

Provides conceptual information about how the DataPower appliance can useSPNEGO.

v Optimizing through Streaming

Provides conceptual information about and procedures for optimizing theDataPower appliance through streaming.

v Securing the Last Mile

Provides conceptual information about and procedures for understanding theDataPower appliance while securing the last mile.

v Configuring the DoD PKI

Provides conceptual information about and procedures for configuring theDataPower appliance with Department of Defense Public Key Infrastructure.

File naming guidelinesThe maximum length for a file name can be approximately 4128 characters. Thename of the base file can be up to 128 characters in length. The base file is the partafter the name of the DataPower directory. Examples of directories are local:,store:, and temporary:.

If the directory (or domain) supports subdirectories, the path to the file can have alength of 4000 characters. When you create a domain, its name is the base filename in several DataPower directories when viewed from the default domain.

The following characters are valid in directory and file names:v a through z

v A through Z

v 0 through 9

v _ (underscore)v - (dash)v . (period)

Note: Names cannot contain two consecutive periods (..).

Object naming guidelinesThe object name must be unique in the object namespace. The following charactersare valid in when specifying the name for an object:v a through z

v A through Z

viii IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ

v 0 through 9

v _ (underscore)v - (dash)v . (period)

Note: Names cannot contain two consecutive periods (..).

Typeface conventionsThe following typeface conventions are used in the documentation:

bold Identifies commands, programming keywords, and GUI controls.

italics Identifies words and phrases used for emphasis and user-suppliedvariables.

monospacedIdentifies user-supplied input or computer output.

Preface ix

x IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ

Chapter 1. Introduction

The IBM WebSphere DataPower SOA Appliances can exchange messages withWebSphere MQ systems by connecting as a WebSphere MQ client. This capabilityallows the DataPower appliance to bridge disparate messaging and transportprotocols, such as HTTP or TIBCO EMS, to WebSphere MQ. Messages originatingwithin or outside of a WebSphere MQ system can flow easily to and from anotherWebSphere MQ system or other messaging system, such as HTTP or TIBCO EMS.To bridge the disparate messaging and transport protocols, the DataPowerappliance uses a service, such as the Multi-Protocol Gateway service.

Software requirementsDataPower appliance integrates with IBM WebSphere MQ versions 6.0 and 7.0.

The WebSphere MQ Information Center for each version is available at thefollowing URL:v http://www.ibm.com/software/integration/wmq/library/.

Multi-Protocol Gateway serviceA Multi-Protocol Gateway service is a DataPower appliance service that acceptsclient-originated messages in a variety of protocols and subsequently passesmessages to a backend server using a variety of protocols. In addition to themessaging system bridging, the Multi-Protocol Gateway service can also apply thefull range of transformation, security, authorization, routing, logging andcustomization services available to the messages flowing through the service toand from the WebSphere MQ system. In every case, the service behaves as anintermediary in the message flow. The service does not store or hold messagesoutside the context of a single transaction, as a WebSphere MQ queue managermight do.

A Multi-Protocol Gateway service, and the other configuration objects employed onthe appliance to implement integration with WebSphere MQ messaging systems,offers flexibility for tuning integration with WebSphere MQ. This discussesconfiguration options in the context of an enterprise architecture including routingto remote queue managers, handling MQ headers, and error processing.

Configuration for integration with WebSphere MQTo define integration with WebSphere MQ, you must configure objects on theDataPower appliance. The following list of objects are those most frequentlyconfigured when developing a service for integration with WebSphere MQ. Manyof these objects are discussed in the “Basic MQ architecture” on page 3.v A “DataPower service” on page 2 to define the architecture.v An “MQ Front Side Handler object” on page 2 to define a WebSphere MQ

system as the front side.v An “MQ Queue Manager object” on page 2 to define the communication

between a service and a WebSphere MQ queue manager. In this document, theDataPower object is referred to as the “MQ Queue Manager object.” TheWebSphere MQ queue manager is referred to as the “WebSphere MQ queuemanager” or simply the “queue manager.”

© Copyright IBM Corp. 2009 1

http://www.ibm.com/software/integration/wmq/library/

v One or more “Processing policies” on page 3.v An “MQ Queue Manager Group” on page 3 to implement a failover

configuration.

DataPower serviceThe following properties are defined at the DataPower service level.v Static or dynamic back end. See “Using the MQ URL to set back-side

destinations” on page 10 for more information.v MQ Front Side Handler object. See Appendix A, “Referenced objects,” on page

57 for more information.v Front-side and back-side Header injection and Header suppression parameters.

See “Injecting and suppressing headers” on page 17 for more information.v Process Backend Errors property. See Chapter 5, “Error handling,” on page 45 for

more information.

MQ Front Side Handler objectThe MQ Front Side Handler object polls the configured request queue, managed bythe referenced WebSphere MQ queue manager, for incoming requests. See “MQFront Side Handler” on page 58 for how to configure an MQ Front Side Handlerobject. The following properties are defined as part of the MQ Front Side Handlerobject.v An MQ Queue Manager object associated with this handler.v A GET Queue field to poll for messages.v Optional: A PUT Queue field for response messages.v Get Message Options field to specify the MQGET options that are applicable to

an MQ message. See the “MQGMO_* (Get Message Options)” topic in the“Constants” section of the WebSphere MQ Information Center for details.

v Retrieve Backout Settings field to determine whether to retrieve the Backoutthreshold and Backout requeue queue name from the WebSphere MQ server.

MQ Queue Manager objectThe MQ Queue Manager object defines the properties required to connect to theWebSphere MQ queue manager. The MQ Queue Manager object on the appliancedoes not store or hold messages outside the context of a single transaction. See“MQ Queue Manager” on page 60 for how to configure the following properties ofan MQ Queue Manager object. The following properties are defined as part of theMQ Queue Manager object.v Host Name to specify the WebSphere MQ server.v Queue Manager Name to specify the queue manager on the WebSphere MQ

server.v Units of Work to enable support for local units of work with roll back support.v Automatic Backout and associated Backout Threshold and Backout Queue Name

to specify how to handle any message that the receiving application does notprocess.

v Total Connection Limit to specify the total number of open connections to allow.v Automatic Retry and the associated Retry Interval to specify whether to attempt

to reconnect to remote server after a connection failure and if so at whatinterval.

2 IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ

Processing policiesProcessing policies might contain one or more processing rules with the followingactions:v An MQ Header action to insert and modify headers for MQ processing. See

“MQ header action” on page 18 for more information.v Actions, such as a Transform action, to define style sheets for custom MQ

message header processing. See “Using MQ headers with custom style sheets”on page 23 for more information.

v An Error rule for custom error handling. See Chapter 5, “Error handling,” onpage 45 for more information.

MQ Queue Manager GroupThe MQ Queue Manager Group object implements a failover configuration. Thefollowing properties are defined as part of the MQ Queue Manager object.v Primary MQ Queue Manager to specify an existing MQ Queue Manager object.v Backup MQ Queue Managers to specify one or more backup MQ Queue

Manager objects in the event the primary MQ Queue Manager object becomesunavailable.

See “MQ Queue Manager Group” on page 65 for information about how toconfigure the primary and backup MQ Queue Manager objects.

Basic MQ architectureWhen integrating with WebSphere MQ system, a DataPower service performsmessaging system bridging from variety of protocols to the MQ protocol or fromthe MQ protocol to a variety of protocols. The service also supports message trafficfrom the MQ protocol to the MQ protocol and provides transformation, security,authorization, routing, logging and customization services.

This section describes two example architectures of a typical installation:v A DataPower service connects an HTTP-based messaging system to a back-end

WebSphere MQ systemv A DataPower service connects a front side WebSphere MQ system to a back-end

Web Services architecture

In both of these architectures, the DataPower service acts as a WebSphere MQclient only. The service does not act as a WebSphere MQ queue manager.

Figure 1 on page 4 illustrates the basic architecture implemented when aDataPower service is used to connect an HTTP-based messaging system (typical ofa Web Services architecture) to a WebSphere MQ-based system inside theenterprise. The figure illustrates the primary configuration objects created on theappliance as well as the configuration of the MQ Queue Manager to which theservice connects and exchanges messages.

Chapter 1. Introduction 3

The Front Side Handler object implements HTTP transport connectivity on theclient, or front, side of the service. On the back end, the Multi-Protocol Gatewayemploys MQ-based URLs to determine the WebSphere MQ queue to whichrequests are forwarded, and also from which replies are pulled.

Conversely, Figure 2 illustrates a DataPower service being used to extend aWebSphere MQ-based messaging system out to a Web Services architecture.

Here, the Front Side Handler object polls a WebSphere MQ queue for requestmessages and places replies from the back-end services on another WebSphere MQqueue. The Front Side Queue Manager object might optionally place messages inan error queue on the WebSphere MQ queue manager. On the back end, astandard HTTP URL is used to determine the destination to which requests areforwarded, and from which answers are received in accordance with the HTTPspecification.

Message workflowThe message workflow for the two examples presented in “Basic MQ architecture”on page 3 is described in detail in the following sections. First is the HTTP to MQprotocol example in which a DataPower service connects an HTTP-basedmessaging system to a back-end WebSphere MQ system. Next, the message

Figure 1. Basic architecture for HTTP to MQ messaging

Figure 2. Basic architecture for MQ to HTTP messaging


workflow for the MQ protocol to HTTP example is provided. In this workflow theDataPower service connects a front side WebSphere MQ system to a back-end WebServices architecture.

HTTP to MQAs illustrated in Figure 1 on page 4 (HTTP to MQ), messages flow to and from theDataPower appliance and work is performed by the appliance in the followingsequence.1. The HTTP client sends an HTTP-based request (typically an HTTP Post

containing a SOAP XML document, but possibly binary data) to the appliance.An HTTP Front Side Handler listens on an assigned port for incoming requests.

2. The Front Side Handler passes the message to the Multi-Protocol Gatewayservice object. The Multi-Protocol Gateway service then applies relevantProcessing Policy actions on the message.

3. The Multi-Protocol Gateway either dynamically determines the appropriatedestination to which to route the message, or routes all messages statically to aparticular destination. In either case, in this architecture, the destination is aparticular queue managed by a particular MQ queue manager. The DataPowerMQ Queue Manager object contains the necessary information to establish aconnection to the MQ queue manager.

4. The message is placed on the destination queue with the MQPUT command. Ifthe network connection to a queue manager fails for any reason other thanWebSphere MQ reason code (MQRC) 2009 (connection broken), the service willcancel the transaction and start error handling. See Chapter 5, “Error handling,”on page 45 for more information.

5. The appliance polls the reply-to queue specified in the Destination URL field tofind a correlated response message. The Multi-Protocol Gateway examines theCorrelation ID value in the MQ header of messages on the reply-to queue;when the ID is the same as the Message ID assigned to the request, theMulti-Protocol Gateway takes the message as the response. Note that thereply-to queue specified in the MQMD header of the message should agreewith the reply-to queue specified in the Destination URL when theMulti-Protocol Gateway employs a static back-end configuration. If it does not,the Gateway will not be able to find the response message.If a correlated response message is found, the Multi-Protocol Gateway mightagain apply any of the configured Processing Policy actions to the response andreturns the reply to the requesting HTTP client. The reply can include errorresponses from the back-end application server. If no response is found withinthe Timeout property set in the Destination URL, the Multi-Protocol Gatewayhandles the error in the same fashion as a back-end error. Note that theTimeout must be set in the Destination URL used to contact the WebSphere MQback-end queue or the Gateway will continuously poll for a response message,causing the front side HTTP connection to time out.The Multi-Protocol Gateway can be configured to retrieve and process anymessage found on the Reply-to queue, rather than only the correlated message.This can be done by using the Setvar processing action, or by using theset-variable() extension function. Using either method, set the variable'var://context/INPUT/_extension/header/X-MQMD-Get' to '<MQMD/>'.

The URL used to open the connection to the back end Request queue can omitdesignating a reply-to queue. In this case, the Multi-Protocol Gateway does notwait for a correlated response message or any error message and terminates thetransaction immediately after putting the message on the back-end queue. Noresponse is sent to the front side HTTP client.


MQ to HTTPAs illustrated in Figure 2 on page 4 (MQ to HTTP), messages flow to and from theDataPower appliance, and work is performed by the appliance, in the followingsequence.1. An MQ Front Side Handler object polls the configured Request queue,

managed by the referenced WebSphere MQ queue manager, for incomingrequests. All messages found on the queue are copied from the queue.To control the GET command, use the MQ GET options that are available forlarge segmented messages through the MQ Front Side Handler. The MQ FrontSide Handler accepts the decimal value for the desired MQ GET option. See the“MQGMO_* (Get Message Options)” topic in the “Constants” section of theWebSphere MQ Information Center for details.To implement redundancy, configure the Multi-Protocol Gateway to use morethan one MQ Front Side Handler polling a range of queues. It is then up to theWebSphere MQ system, independent of the service, to route messages to anactive queue. If the message is a Request, the Front Side Handler saves theMessageID, ReplyToQueue, and ReplyToQueueManager fields in the messagefor later processing of a reply. See item 4 on page 7 for more information.By default, all request messages are immediately removed from the requestqueue. To leave the request message on the request queue until processing bythe Multi-Protocol Gateway is complete with no errors, set the Units of Workproperty of the MQ Queue Manager object in use by the MQ Front SideHandler to 1. See Chapter 4, “Units of Work,” on page 35 for more information.

2. The Front Side Handler passes the message to the Multi-Protocol Gatewayservice object. The Multi-Protocol Gateway applies relevant Processing Policyactions on the message. The Multi-Protocol Gateway either dynamicallydetermines the appropriate destination to which to route the message or routesall messages statically to a particular destination. In this scenario, the back endemploys HTTP. The Multi-Protocol Gateway opens an HTTP connection andtypically posts the request.If the Gateway encounters a network error or is otherwise unable to establish aconnection to the back-end server, by default the Gateway runs any matchingError rule in the Processing policy. The result is returned to the MQ Front SideHandler for delivery. See item 4 on page 7.

3. The Multi-Protocol Gateway gets the response from the back-end applicationserver. In this scenario, the HTTP protocol requires a response (which mightcontain an error message) or the Multi-Protocol Gateway registers an error.When the back-end HTTP server returns a good response, the Multi-ProtocolGateway applies any applicable Processing Policy actions to the response. Anyprocessing errors will typically terminate the transaction unless error handlinghas been built into the policy. When the back-end application returns aresponse with a protocol error, such as HTTP 500, by default the Gatewayprocesses this response using the same response rules used for a goodresponse. The result of any such processing is forwarded to the PUT queue ofthe MQ Front Side Handler.To configure the Gateway to run an error rule, rather than a standard responserule when the back end returns an error (such as HTTP 500), set the ProcessBackend Errors property of the Gateway to off. The Gateway places the resultof the Error rule on the Put queue of the MQ Front Side Handler unless theMQ Queue Manager object has the Units of Work property set to 1, in whichcase the Error rule runs but no response message is delivered. See Chapter 4,“Units of Work,” on page 35 for more information.


4. The response message can be placed on the reply-to queue specified in the MQFront Side Handler. The Front Side Handler sets the MQMD CorrelID to thesaved MsgID of the original request. If the original request message specifies areply-to queue, the Front Side Handler places the response on the queuespecified in the message, rather than on the Put queue specified in the FrontSide Handler. Unlike HTTP, the MQ protocol does not require a response.However, if the response rule has changed the RepyToQ and the ReplyToQMgr inthe MQMD header, those will be honored. See “Message descriptor header(MQMD)” on page 23 for more details.


Chapter 2. Routing

A Multi-Protocol Gateway routes messages to and from WebSphere MQ queuesjust as messages are routed to and from HTTP destinations. The Multi-ProtocolGateway uses either static or dynamically determined routes. The service providesseveral methods to determine where a message should be routed and how therouting can be specifed. The following sections describe these methods.v “Determining back-side request routing” for information on what parts of an

input message are used to determine where the message should be routed.v “Setting back-side destinations” for information on what method to use to set

the destination.v “Using the MQ URL to set back-side destinations” on page 10 for information on

setting a static or a dynamic MQ URL.

Determining back-side request routingA Multi-Protocol Gateway can use either static or dynamic routing to a back-enddestination. When using a static route, the Backend URL property of the Gatewaydetermines the route. When using dynamic routing, the processing policy of theservice must set the destination during processing. The Gateway can examine thefollowing parts of the input message to help determine where the message shouldbe routed.

Message contentThe Multi-Protocol Gateway can dynamically determine the destinationqueue by employing either an XPath routing map or a custom style sheetto examine the content of the message.

Protocol headerThe Multi-Protocol Gateway can also dynamically determine thedestination queue by examining the value of the MQ protocol headers. Fora list of all headers, use the var://service/header-manifest servicevariable, which contains a nodeset of all supported headers found in themessage, including the required MQMD header. The complete header canbe obtained by reading the extension variable var://context/INPUT/_extension/header/MQMD. The header has already been parsed into anodeset for easy reference. See Chapter 3, “MQ header values,” on page 17for more information. Note that you can inspect the headers presented byother request protocols, such as HTTP or JMS, in similar fashion.

Setting back-side destinationsIf the Multi-Protocol Gateway dynamically determines the back-end destination,then the Multi-Protocol Gateway Processing Policy must set a back-end target.Some common ways for doing this include the following methods:v Use the Route action.v Use the var://service/routing-url service variable.v Use the set-target() or xset-target() DataPower Extension Function calls in a

custom style sheet.

You can send or route messages to one or more alternative destinations by usingthe Results (or Results Async) processing actions, just as with HTTP messages. For


example, a single request message might contain a number of attachments. Theseattachments can be separated from the original request and routed individually toa particular destination (that might not be a WebSphere MQ queue). Theprocessing policy of the Multi-Protocol Gateway can collect the responses andconstruct a reply message, can ignore the responses, or can send a responsemessage that does nothing more than acknowledge receipt of the original request.

An MQ URL can be used to express all back-end destinations.

Using the MQ URL to set back-side destinationsThe DataPower service employs an MQ URL to express a target queue on aWebSphere MQ server where messages are put and retrieved. To send to and toretrieve messages from a back-end WebSphere MQ system, use either a static or adynamic URL format.v The static URL uses a fixed server address that is defined in an MQ Queue

Manager object on the appliance. The static URL format requires the priorconfiguration of an MQ Queue Manager object whose properties provide theinformation (for example, host name and channel name) that is required toaccess the WebSphere MQ server. A Multi-Protocol Gateway service defined ashaving a static back end provides the MQ Helper utility in the WebGUI toconstruct the URL using selected options.

v The dynamic URL format establishes a connection to a WebSphere MQ server inthe absence of a locally configured MQ Queue Manager object. When aMulti-Protocol Gateway service is defined as having a dynamic back end, theback-end server address and port are determined by a processing policy actionsuch as a transform action or a route action. The action can determine the routeby using a style sheet, an XPath expression, or a variable. This provides theflexibility within a processing policy to dynamically determine the destination atrun time.

Syntax for a static MQ URLThe syntax for a static MQ URL is as follows:

dpmq://QueueManagerObject/URI?RequestQueue=requestQueueName;ReplyQueue=replyQueueName;queryParameters

The parameters in the URL are as follows:

dpmq Indicates the required protocol identifier for a static WebSphere MQback-end system.

QueueManagerObjectSpecifies the name of an existing MQ Queue Manager object stored on theappliance. The object provides the connection information needed to accessa remote WebSphere MQ queue manager on a WebSphere MQ server.Optionally, use the name of a Queue Manager Group to implementfailover.

URI Specifies the URI portion of the path to the target queue.

RequestQueue=requestQueueNameSpecifies the name of the back-end WebSphere MQ request queue. Thisqueue is where the DataPower service, acting as the WebSphere MQ client,puts request messages. The URL must minimally contain either the requestor reply queue name and can contain both.


ReplyQueue=replyQueueNameSpecifies the name of the back-end WebSphere MQ reply queue that theservice polls for responses. The URL must contain either the request orreply queue name and can contain both.

queryParametersSpecifies optional and required query parameters for static and dynamicURLs.

Browse={first|next|current}Used to browse (retrieve without removing) messages from the queuespecified in the ReplyQueue parameter. Use one of the followingvalues:

first Browses the first message in a queue.

next Steps through many messages in incremental order on thequeue. For example, if you specify next after browsingmessage one, url-open returns message two. Specifying nexton the first url-open attempt reads the first message in thequeue.

currentReads the last message retrieved from the queue.

You can also specify the MQGMO browse options in theGMO=optionsValue parameter. In the case of a conflict between theBrowse parameter and the GMO parameter, the GMO flag takesprecedence.

ContentTypeHeader=headerSpecifies the name of the MQ header that identifies the content typeof the message data.

ContentTypeXPath=expressionSpecifies an XPath expression to run on a parsed MQ header(specified in the ContentTypeHeader parameter) to extract the contenttype of the message data.

GMO=optionsValueSpecifies an integer that identifies a field option for a MQ GMO GEToperation. For example, a value of 32800 (hexadecimal 0x00008020)sets the following MQGMO options:v MQGMO_BROWSE_NEXT (decimal 32, hexadecimal 0x00000020)v MQGMO_LOGICAL_ORDER (decimal 32768, hexadecimal 0x00008000)

See the “MQGMO_* (Get Message Options)” topic in the “Constants”section of the WebSphere MQ Information Center for details.

MatchOptions=optionValueSpecifies an integer that identifies a field MatchOption for a MQ GMOGET operation. Use this value to control the selection criteria for aGET operation, or how to retrieve a message from a queue. Forexample, you might retrieve a message by matching a MessageId orCorrelationId.

Model={true|false}When true, this value instructs the DataPower service to connect tothe RequestQueue indicated and use the dynamic, temporary Modelqueue defined by the ReplyQueue value to get the response. When theresponse is received, the connection to the temporary queue is closed.

Chapter 2. Routing 11

ParseHeaders={true|false}Specifies a Boolean value that parses and strips headers from messagedata.

PMO=optionsValueSets the value for MQPMO.Options. This optional value is a cumulativevalue in decimal format of all acceptable options. For example, avalue of 2052 (hexadecimal 0x0804) sets the following MQPMO options:v MQPMO_NO_SYNCPOINT (decimal 4, hexadecimal 0x00000004)v MQPMO_SET_ALL_CONTEXT (decimal 2048, hexadecimal 0x00000800)

With the PMO parameter, you can set the MQPMO.Options field on theMQPUT call that is used to place the request message of theback-end request queue. See the “MQPMO_* (Get Message Options)”topic in the “Constants” section of the WebSphere MQ InformationCenter for details.

By default, only MQPMO_NO_SYNCPOINT is set.

SetReplyTo={true|false}Specifies a Boolean value that sets the ReplyToQ MQMD header valuefor a request message placed on the back end (PUT operation).

Sync={true|false}Optional: Specifies whether the PUT operation to the request queue iscommitted immediately upon successful delivery of the message.

true Specifies that the PUT operation is committed immediatelyupon successful delivery of the message so that back-endapplications and GET operations can process the messagefrom the request queue.

false (Default) Specifies that the PUT operation is not committed.

Note: Note that the QueueManagerObject identified must have theUnits of Work property set to 1 (the default is 0).

TimeOut=timeoutSpecifies the timeout value, in milliseconds, for a GET messageoperation.

Transactional={true|false}Optional: Specifies whether the URL open call executes as part of atransaction.

true The URL open call executes as part of a transaction andsynchronizes the PUT operation to the request queue with theGET operation from the reply queue.

false (Default) The URL open call does not execute as part of atransaction.

Using the MQ Helper to build a static MQ URLThe MQ Helper is available in DataPower WebGUI when creating or editing aMulti-Protocol Gateway service through the service view. For information aboutthe values to specify in the MQ Helper fields, see the online help.

Here is an example of a static MQ URL constructed when the MQ Helper utility isgiven the following input:v The MQ Queue Manager object is specified as DPQM


v The RequestQueue is specified as BACK.REQUEST

v The ReplyQueue is specified as BACK.REPLY

v Transactionality is set to on

v User Identifier is set to on

dpmq://DPQM/?RequestQueue=BACK.REQUEST;ReplyQueue=BACK.REPLY;Transactional=true;PMO=2052

Using a static MQ URL in a style sheetA static MQ URL can also be used in a custom style sheet. The following examplecombines the use of a static MQ URL with the Browse query parameter and thedp:mq-queue-depth extension function to locate message b3 in a WebSphere MQqueue with a message depth value of 4. See IBM WebSphere DataPower SOAAppliances: Extension Elements and Functions Catalog for more information on thedp:mq-queue-depth extension function, including the complete syntax for specifyingthe queue manager parameter....<xsl:template match="/">...

<xsl:call-template name="find-something-using-browse"><xsl:with-param name="num" select="dp:mq-queue-depth('queuemgr1','MQ096')"/><xsl:with-param name="url" select="'dpmq://queuemgr1/?ReplyQueue=MQ096;

TimeOut=500;Browse=next'"/></xsl:call-template>

</xsl:template>

<xsl:template name="find-something-using-browse"><xsl:param name="num" /><xsl:param name="url" />

<xsl:if test="$num > 0">

<xsl:variable name="reply"><dp:url-open target="{$url}" response="xml"/>

</xsl:variable>

<xsl:choose><xsl:when test="$reply//*[local-name() = 'b3']">

<dp:url-open target="dpmq://queuemgr1/?ReplyQueue=MQ096;GMO=256"response="xml"/>

<xsl:call-template name="find-something-using-browse"><xsl:with-param name="num" select="$num - 1"/><xsl:with-param name="url" select="$url"/>

</xsl:call-template></xsl:when><xsl:otherwise>

<xsl:call-template name="find-something-using-browse"><xsl:with-param name="num" select="$num - 1"/><xsl:with-param name="url" select="$url"/>

</xsl:call-template></xsl:otherwise>

</xsl:choose>

</xsl:if>

</xsl:template>...

Syntax for a dynamic MQ URLThe syntax for a dynamic MQ URL is as follows:

mq://host:port?QueueManager=MQQueueManager;RequestQueue=requestQueueName;ReplyQueue=replyQueueName;Channel=channelName;ChannelTimeout=channelTimeout;ChannelLimit=channelLimit;UserName=userName;MaximumMessageSize=maxMsgSize;queryParameters

The parameters in the URL are as follows:

mq Identifies the required protocol identifier for a dynamic WebSphere MQURL.

host Specifies the host name or IP address of the target WebSphere MQ server.

port Specifies the associated port on the target WebSphere MQ server.

QueueManager=MQQueueManagerSpecifies the name of a WebSphere MQ queue manager on the targetWebSphere MQ server.

RequestQueue=requestQueueNameSpecifies the name of the back-end WebSphere MQ request queue. Thisqueue is where the DataPower service, acting as the WebSphere MQ client,puts request messages. The URL must minimally contain either the requestor reply queue name.

ReplyQueue=replyQueueNameSpecifies the name of the back-end WebSphere MQ reply queue which theappliance polls for responses. The URL must minimally contain either therequest or reply queue name.

Channel=channelNameSpecifies the name of the channel, defined on the WebSphere MQ server, toconnect to the WebSphere MQ queue manager.

ChannelTimeout=channelTimeoutSpecifies an integer that indicates the number of seconds that theDataPower appliance retains (keeps alive) a dynamic connection in theconnection cache. This value specifies the Cache Timeout parameter for thedynamic MQ Queue Manager object. Specify a value that is greater thanthe negotiated heartbeat interval but less than the keep alive interval.v The negotiated heartbeat interval is between the DataPower appliance

and the back-end WebSphere MQ server.v The keep alive (timeout) interval is on the back-end WebSphere MQ

server. The KAINT attribute on the WebSphere MQ server defines thetimeout value for a channel.Not all channels have a defined, explicit keep alive interval on theWebSphere MQ server. Some queue managers use an automatic timeoutsetting (the KAINT attribute set to AUTO). In these cases, the keep aliveinterval is the negotiated heartbeat interval plus 60 seconds.

When an inactive connection reaches this threshold, the appliance removesthat dynamic connection from the cache. When the cache no longer


contains dynamic connections, the appliance deletes the dynamic queuemanager. Without a dynamic queue manager, there is no connection withthe back-end WebSphere MQ server.

Note: This timeout value is the only way to configure a timeout valuefrom the appliance to the back-end WebSphere MQ server. No otherconfiguration setting on the appliance can time out an MQconnection.

ChannelLimit=channelLimitSpecifies the maximum number of open channels to allow between theappliance and the remote WebSphere MQ queue manager. Use an integerin the range of 2 through 5000.

UserName=userNameSpecifies the plain text string to identify the client to the WebSphere MQserver.

MaximumMessageSize=maxMsgSizeSpecifies the maximum size of messages that the WebSphere MQ queuemanager accepts. Use an integer between 1024 bytes and 1 GB.

queryParametersSee “queryParameters” under “Syntax for a static MQ URL” on page 10 formore information.

You can construct a dynamic MQ URL that points to a WebSphere MQ queuemanager that has not been defined by a static MQ Queue Manager object on theappliance. Such dynamic MQ URLs take the following form:

mq://MQhost:1414/test/?Channel=DP.CHANNEL;QueueManager=MQQM;RequestQueue=BACK.REQUEST;ReplyQueue=BACK.REPLY

Front Side reply routingThe Multi-Protocol Gateway routes reply messages using the following order:1. Using the Reply-to queue specified by header injection or created by rule

actions in the response message2. Using the Reply-to queue specified in a request message3. Using the PUT queue specified in the MQ Front Side Handler

Set the Front Side ReplyTo Queue dynamically during processing by configuring aResponse Header Injection property that sets the ReplyToQ header to the desiredvalue. For example, specify the following Header Injection values to send a replymessage to the QUEUE5 ReplyToQ:

Table 1. Header Injection Settings

Property Value

Direction Front

Name ReplyToQ

Value QUEUE5

You can accomplish the same thing by using the dp:set-response-header()extension function, as illustrated here:

<dp:set-response-header name="'ReplyToQ'" value="QUEUE5"/>


Note the inner single quotes for the name parameter.

In addition to the Reply-to queue, you can dynamically set the WebSphere MQqueue manager during processing. Use the same Gateway Header Injectionconfiguration method, or extension function, changing the header name to“ReplyToQM” and the value to the desired queue manager name. Note that thequeue manager name must match the name of a configured MQ Queue Managerobject on the appliance which in turn connects to the desired remote WebSphereMQ queue manager, not the name of a Manager elsewhere on the network. Forexample, specify the following Header Injection values to send a reply message tothe WASQM ReplyToQM where WASQM is the name of an existing MQ Queue Managerobject:


Property Value

Direction Front

Name ReplyToQM

Value WASQM

You can also determine the routing of messages to front side WebSphere MQqueues by using the MQMD header contained in the message to be delivered bythe MQ Front Side Handler. The MQMD header is covered in detail in “Messagedescriptor header (MQMD)” on page 23.


Chapter 3. MQ header values

The DataPower service recognizes and can modify the content of a subset of MQheaders to alter the routing of messages and to control the behavior of thecommunications with the queue manager.

The following MQ headers are supported by the DataPower service:v MQCDv MQCIHv MQCNOv MQDHv MQDLHv MQGMOv MQIIHv MQMDv MQODv MQPMOv MQRFHv MQRFH2v MQSCOv MQTMv MQWIHv MQXQH

When an incoming message contains an MQ header other than this subset, theservice leaves the header as it is and passes the message to the back end. Theservice logs a message indicating that the MQ message contains a header that isnot supported. For these unsupported headers, there is no guarantee that themessage will be accepted or processed correctly on the WebSphere MQ server.

The service provides several methods, from basic to completely customized, tomanipulate MQ headers. The following sections describe these methods.v Front-side and back-side “Injecting and suppressing headers” parameters at the

service levelv “MQ header action” on page 18 of a processing rulev “Using MQ headers with custom style sheets” on page 23to manipulate of the

header values from a processing rule

Injecting and suppressing headersThe ability to inject or suppress specific headers is available at the service level.While this controls headers at a high level ability, it might be the easiest way tomeet your requirements.

For instance, suppose you want to simply suppress the WebSphere MQ MessageDescriptor (MQMD) message header on messages passing through a Multi-ProtocolGateway. This can be done from the Headers tab of the service:1. Click Headers.


2. Click Add under Header Suppression Parameters.3. Specify the direction as either Front or Back.4. Specify the header to suppress.

When the header is defined in the original request, the service removes thespecified header before forwarding the request.

Similarly, using header injection, you can specify a header and a header value toinject. Even though the headers are not defined in the original request, the serviceprovides the specified headers. For example, change the MQMD.Format toMQHRF2 using the following header injection parameters:


Property Value

Direction Back

Name MQMD

Value <MQMD><Format>MQHRF2</Format></MQMD>

See “Front Side reply routing” on page 15 for more information.

Note: When you inject any MQ header, such as MQCIH, that has aCodedCharSetId (CCSID) field, you must specify the CCSID value in theMQ header. If this is not done, the service will use 819 (ISO 8859-1 ASCII) asthe default value. In some cases, this might cause an MQRC 2110 error(MQRC_FORMAT_ERROR) for example if the data is in UTF-8 format butthe CCSID is 819, not 1208 (UTF-8).

MQ header actionThe MQ Header action can perform the following header and queue modifications:

Modify MQMD Request Message HeadersSelectively override specified headers values in a request message or dropsall header values from the request message and replaces with new orauto-generated values.

Retrieve Responses using Message Id or Correlation IdModify how the service retrieves response messages from a backend replyqueue by specifying a message ID or Correlation ID. By default, the servicelooks in the backend reply queue for response messages that have aCorrelation Id that matches the Message Id of the request message.

Modify MQMD Response Message HeadersSelectively override specified header values in a response message ordrops all header values from the response message and replaces with newor auto-generated values.

Modify Reply Queue for Response MessagesModify the destination reply queue for response messages. By default, theservice sends responses to the reply queue specified in the MQ Front SideHandler.

Modify Queue Manager for Response MessagesModify the destination MQ Queue Manager for response messages. Bydefault, the service sends responses to the MQ Queue Manager specified inthe MQ Front Side Handler.


Modifying MQMD request headersTo modify MQMD header values for request messages placed to the backend, usethe following procedure:1. Drag the Advanced icon to the configuration path (the horizontal line).2. Double-click the Advanced icon to display a window that lists the advanced

action types.3. Click the MQ Header radio button.4. Click Next to display the MQ Header action window.5. Optionally select the Input context. If this is left at the default value of auto,

processing inserts the correct context identifier.6. Use the Asynchronous toggle to determine whether the action is

asynchronous:

on Marks the action as asynchronous. This action does not need tocomplete for the next action in the processing rule to begin.

When asynchronous, you can cause processing to wait for the actionto complete by adding this action to a subsequent event-sink actionin the same processing rule. Refer to “Event-sink (event-sink) action”on page 57 for details.

off (Default) Marks the action as synchronous. This action must completefor the next action in the processing rule to begin.

7. Select request as the MQ Processing Type.8. Select MQMD for Put from the MQ Request Header Processing list.9. Use the Override Existing MQMD toggle to choose a mode for overriding the

MQMD headers in the request message:

on Overrides existing MQMD header values on the request message withthese values. If blank, the service retains the header value from theoriginal request message.

off (Default) Ignores all MQMD header values from the original requestmessage. The new header values are inserted into the requestmessage. If blank, the service populates those fields withauto-generated defaults.

10. Specify an override value for any of the following MQMD header fields:v Message Id

v Correlation Id

v Character Set Id

v Format Name

v ReplyToQ

v ReplyToQMgr

11. Select an Output context or specify a new context name. Select auto to allowthe processing policy to determine the output context automatically.

12. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completedrule to the processing policy. Otherwise, drag another action icon to theconfiguration path.

Chapter 3. MQ header values 19

Retrieving responses by message ID or by correlation IDTo retrieve response messages from the backend reply queue, use the followingprocedure:1. Drag the Advanced icon to the configuration path (the horizontal line).2. Double-click the Advanced icon to display a window that lists the advanced


the service inserts the correct context identifier.6. Use the Asynchronous toggle to determine whether the action is

asynchronous:




7. Select request as the MQ Processing Type.8. Select MQMD for Get from the MQ Request Header Processing list.9. To specify how the service pulls messages from the backend reply queue, use

the following fields:v Specify the message ID in the Message Id field. The service pulls messages

from the backend reply queue with the specified message ID.v Specify the correlation ID in the Correlation Id field. The service pulls

messages from the backend reply queue with the specified correlation ID.10. Select an output context or specify a new context name. Select auto to allow

the processing policy to determine the output context automatically.11. Click Done to complete the action.


Modifying MQMD response headersTo modify MQMD header values for response messages placed to the backendreply queue, use the following procedure:1. Drag the Advanced icon to the configuration path (the horizontal line).2. Double-click the Advanced icon to display a window that lists the advanced


the service inserts the correct context identifier.6. Use the Asynchronous toggle to determine whether the action is

asynchronous:





7. Select response as the MQ Processing Type.8. Select MQMD from the MQ Response Header Processing list.9. Use the Override Existing MQMD toggle to choose a mode for overriding the

MQMD headers in the response message:

on Overrides existing MQMD header values on the response messagewith the values specified here. If blank, the service retains the headervalues from the original request message.

off (Default) Ignores all MQMD header values from the responsemessage. The new header values are inserted into the responsemessage. If blank, the service populates these fields withauto-generated default values.

10. Specify an override value for any of the following MQMD header fields:v Message Id

v Correlation Id

v Character Set Id

v Format Name

v ReplyToQ

v ReplyToQMgr

11. Select an output context or specify a new context name. Select auto to allowthe processing policy to determine the output context automatically.



Modifying reply queue for responseTo change the destination reply queue for response messages, use the followingprocedure:1. Drag the Advanced icon to the configuration path (the horizontal line).2. Double-click the Advanced icon to display a window that lists the advanced

action types.3. Click the MQ Header radio button.4. Click Next to display the MQ Header action window.5. Optionally select the Input context. If the default, the service inserts the

correct context identifier.6. Use the Asynchronous toggle to determine whether the action is

asynchronous:





7. Select response as the MQ Processing Type.8. Select ReplyToQ from the MQ Response Header Processing list.9. Select the processing method for the response message from the ReplyToQ

Processing Type list.

Empty Forces the service to not send a response message to a reply queue.

Specified(Default) Overrides default response message processing. The serviceroutes response messages to the specified reply queue.

10. Optionally specify a value in the ReplyToQ field.11. Select an output context or specify a new context name. Select auto to allow

the service to determine the output context.12. Click Done to complete the action.


Modifying the queue manager for responseTo change the destination MQ Queue Manager for response messages, use thefollowing procedure:1. Drag the Advanced icon to the configuration path (the horizontal line).2. Double-click the Advanced icon to display a window that lists the advanced

action types.3. Click the MQ Header radio button.4. Click Next to display the MQ Header action window.5. Optionally select the Input context. If the default, processing inserts the

correct context identifier.6. Use the Asynchronous toggle to determine whether the action is

asynchronous:




7. Select response as the MQ Processing Type.8. Select ReplyToQM from the MQ Response Header Processing list.9. Select the processing method for the response message from the ReplyToQM

Processing Type list.


Empty Forces the service to direct responses to the MQ Queue Managerspecified in the MQ Front Side Handler (default behavior).

Specified(Default) Overrides default MQ Queue Manager processing. Theservice routes response messages to the specified MQ Queue Manager.

10. Optionally specify a value in the ReplyToQMgr field.11. Select an output context or specify a new context name. Select auto to allow

the processing policy to determine the output context automatically.12. Click Done to complete the action.


Note: To set values, an input field can be specified as static text or as a variable.For instance, to add an MQ Header action to specify the reply queue forresponse processing, the ReplyToQ name might be specified with static textor with a variable such as var://context/INPUT/hdrval.

Using MQ headers with custom style sheetsWhile header injection and suppression and the MQ Header action provide ease ofuse in handling MQ headers, using custom style sheets adds additionalcustomization for dynamic, runtime control of MQ headers. Typically, the stylesheet is used in a transform action in a request, response, or error rule of theprocessing policy. A results action is not needed, since the service will put themessage to the queue and queue manager which are set dynamically in the stylesheet. There are different ways to implement the desired routing as demonstratedwith the sample style sheets that manipulate the following headers:v “Message descriptor header (MQMD)”v “IMS Information Header (MQIIH)” on page 27v “CICS Bridge Header (MQCIH)” on page 27v “Object descriptor header (MQOD)” on page 28

Message descriptor header (MQMD)The DataPower appliance provides the ability to determine the full set of MQMDheader values. By manipulating these header values, you can alter the routing ofmessages by a DataPower service. You can also control the behavior of thecommunications with the remote queue manager (by determining a Reply-toqueue, for instance). The DataPower service uses four nodes in particular tomanage the routing and flow of messages.

CorrelationIDA unique identifier that matches a MessageID. The DataPower servicecompares the CorrelationID in a message to a list of outstandingMessageIDs to get replies to specific requests from a given queue.

MessageIDA unique identifier assigned to a message by the originator of the message.

ReplyToQThe name of the queue to place reply message. In the context of a clientrequest, this is where the DataPower service places a reply. This might bespecified by the client in the MQMD header of the request, might bespecified by the reply from the back-end application, or might be specified


by the configuration of the DataPower MQ Front Side Handler. In thecontext of a back-end request, this is where the back-end application servershould place a reply.

ReplyToQMgrThe name of the queue manager managing the ReplyToQ. In the context ofa client request, this is where the DataPower service connects to place areply. This might be specified by the client in the MQMD header of therequest, might be specified by the reply from the back-end application, ormight be specified by the configuration of the DataPower MQ Front SideHandler object. In the context of a back-end request, this is where theback-end application server should place a reply.

For complete details regarding the effect and consequences of these values asinterpreted by an IBM WebSphere MQ instance, see the relevant WebSphere MQdocumentation.

The service processes MQMD headers as follows as the message moves from therequest (front) side to the application (back) side, handling a request message.1. The MQ Front Side Handler parses the MQMD of the message into an XML

nodeset and stores it in the variable var://context/INPUT/_extension/header/MQMD.

2. The handler saves the MessageID, ReplyToQ and ReplyToQMgr header values forlater use in processing the response message.

3. The handler can be configured to strip out unwanted headers, such as JMS,CICS® or IMS™ headers.

4. The Gateway can be configured to suppress the existing MQMD header in themessage. When this is done, the Gateway constructs a new header using thedefault values for the back-end connection.

5. The Gateway can be configured to inject a new MQMD header, replacing anyexisting MQMD header.

6. The Gateway can use a custom style sheet during policy processing to create oralter an MQMD header.

The service processes MQMD headers as follows as the message moves from theapplication (back) side to the request (front) side, handling a response message.1. The Gateway can be configured to suppress or inject the header as detailed

above.2. If the message is in response to a request, the service provides the CorrelID

corresponding to the MessageID provided no response rule alters the MQMDheader. The saved ReplyToQ and ReplyToQMgr information corresponding to therequest message are also provided for Front Side Reply routing.

You can discover which supported MQ-related headers are contained in a messageby reading the var://service/header-manifest variable. This returns a nodesetcontaining the names of all supported headers in the message. You can then obtainthe values set for each header by using a dp:request-header() ordp:response-header() function.

You can change or set the MQMD header by using the extension functionsdp:set-request-header() or dp:set-response-header().

You must create an MQMD header containing all desired elements whenever youwant to change or add just one. So, for example, if you wanted to change the


UserIdentifier header value sent to the back-end queue, you would first need tosave the entire MQMD header nodeset, change the desired value and then rewritethe MQMD header using the saved values. Here is an example MQMD requestheader nodeset:<MQMD>

<StrucId>MD </StrucId><Version>1</Version><Report>0</Report><MsgType>8</MsgType><Expiry>-1</Expiry><Feedback>0</Feedback><Encoding>546</Encoding><CodedCharSetId>819</CodedCharSetId><Format>MQSTR</Format><Priority>0</Priority><Persistence>0</Persistence><MsgId>414d51205741535f6970315f7365727667b65c450a920020</MsgId><CorrelId>000000000000000000000000000000000000000000000000</CorrelId><BackoutCount>0</BackoutCount><ReplyToQ>QUEUE5</ReplyToQ><ReplyToQMgr>WAS_ip1_server1</ReplyToQMgr><UserIdentifier>mqm</UserIdentifier><AccountingToken>1601000000000000000000b</AccountingToken><ApplIdentityData> </ApplIdentityData><PutApplType>11</PutApplType><PutApplName>les\IBM\MQ-test\rfhutilc.exe</PutApplName><PutDate>20081121</PutDate><PutTime>21452170</PutTime><ApplOriginData> </ApplOriginData><GroupId>000000000000000000000000000000000000000000000000</GroupId><MsgSeqNumber>1</MsgSeqNumber><Offset>0</Offset><MsgFlags>0</MsgFlags><OriginalLength>-1</OriginalLength>

</MQMD>

You can set the Reply-to queue and Queue Manager in the MQMD header of areply message. When using this method, store a copy of the MQMD header (andother desired MQ-related headers) in a context variable during the requestprocessing phase, using a style sheet executed in a Transform action as part of aRequest rule. You can then retrieve the original request MQMD header and alter itor reinstate it as needed in the response processing.

Here are two examples that illustrate the request and reply style sheets. On therequest rule, the style sheet retrieves the MQMD header contained in a clientrequest to the front side of a Multi-Protocol Gateway. This style sheet stores thekey elements of the header in DataPower variables.<?xml version="1.0" encoding="utf-8"?><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"

xmlns:dp="http://www.datapower.com/extensions"extension-element-prefixes="dp"exclude-result-prefixes="dp">

<xsl:output method="xml"/>

<xsl:template match="/"><xsl:variable name="entries" select="dp:request-header('MQMD')"/><xsl:variable name="header" select="dp:parse($entries)"/><xsl:variable name="RQ" select="$header//ReplyToQ"/><xsl:variable name="RQMgr" select="$header//ReplyToQMgr"/>

<xsl:variable name="MsgId" select="$header//MsgId"/><dp:set-variable name="'var://context/MYMQMD/ReplyToQ'" value="$RQ"/><dp:set-variable name="'var://context/MYMQMD/ReplyToQMgr'" value="$RQMgr"/><dp:set-variable name="'var://context/MYMQMD/MsgId'" value="$MsgId"/><xsl:message>

<xsl:value-of select="concat ('MQMD with Original Request MQMD :',dp:request-header('MQMD'))"/>

</xsl:message></xsl:template>

</xsl:stylesheet>

This example style sheet uses the values taken from the request MQMD header toconstruct a response header that the service uses to route the server reply to thefront side client. Note that the special headers ReplyToQ and ReplyToQM specify theresponse queue and queue manager. These headers override the values in theMQMD header, allowing the service to put to this queue and queue manager butleave the MQMD in the message intact. If this is not the desired effect, theReplyToQ and ReplyToQM should be cleared with the dp:set-response-header()extension element as shown in this example.<?xml version="1.0" encoding="utf-8"?><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"

xmlns:dp="http://www.datapower.com/extensions"extension-element-prefixes="dp"exclude-result-prefixes="dp"><xsl:output method="xml"/><xsl:template match="/">

<dp:set-response-header name="'ReplyToQ'" value="' '"/><dp:set-response-header name="'ReplyToQM'" value="' '"/><xsl:variable name="newMQMDStr">

<MQMD><CorrelId>

<xsl:value-of select="dp:variable('var://context/MYMQMD/MsgId')"/></CorrelId><ReplyToQ>

<xsl:value-of select="dp:variable('var://context/MYMQMD/ReplyToQ')"/></ReplyToQ><ReplyToQMgr>

<xsl:value-of select="dp:variable('var://context/MYMQMD/ReplyToQMgr')"/></ReplyToQMgr><Format>MQSTR</Format>

</MQMD></xsl:variable><xsl:variable name="mqmdStr">

<dp:serialize select="$newMQMDStr"/></xsl:variable><dp:set-response-header name="'MQMD'" value="substring-after($mqmdStr, '?>')"/><xsl:message>

<xsl:value-of select="concat ('MQMD with modified Response ReplyToQ andReplyToQMgr : ', dp:response-header('MQMD'))"/>

</xsl:message></xsl:template>

</xsl:stylesheet>

Setting the complete MQMD header, using variables containing the RequestMQMD header, provides assured control of message routing. You can also createthe complete MQMD header sent to a back-end application server queue usingthese functions.

IMS Information Header (MQIIH)This example style sheet sets the MQMD and MQIIH headers to send messages toan IMS application. The style sheet is used in a transform action of a request rule.The example shows the following practices:v The MQMD ReplyToQ and ReplyToQMgr specify the queue and queue manager

routingv The headers are set using dp:set-request-header

<?xml version="1.0"?><xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"xmlns:dp="http://www.datapower.com/extensions"xmlns:dpconfig="http://www.datapower.com/param/config"xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"extension-element-prefixes="dp"exclude-result-prefixes="dp dpconfig"xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/">


<xsl:template match="/">

<xsl:variable name="mqmd"><MQMD><Format>MQIMS</Format><ReplyToQ>MQBREPLY</ReplyToQ><ReplyToQMgr>WMQB</ReplyToQMgr></MQMD></xsl:variable>

<xsl:variable name="mqmd-serl"><dp:serialize select="$mqmd" /></xsl:variable><xsl:variable name="mqiih"><MQIIH>

<Encoding>0</Encoding><CodedCharSetId>1208</CodedCharSetId><Format>MQSTR</Format><Flags>0</Flags><LTermOverride /><MFSMapName /><ReplyToFormat>MQSTR</ReplyToFormat><Authenticator>IMSSOAP</Authenticator><TranInstanceId>01234567890123456</TranInstanceId><TranState>0</TranState><CommitMode>1</CommitMode><SecurityScope>0</SecurityScope>

</MQIIH></xsl:variable><xsl:variable name="mqiih-serl"><dp:serialize select="$mqiih" /></xsl:variable><dp:set-request-header name="'MQMD'" value="$mqmd-serl"/><dp:set-request-header name="'MQIIH'" value="$mqiih-serl"/></xsl:template></xsl:stylesheet>

CICS Bridge Header (MQCIH)In an HTTP to MQ-CICS bridge environment, the service might include theMQCIH (CICS Header Structure) as part of the message request. The exampleshows the following practices:

v MQMD.Format is set to MQCICS

v MQCIH.UOWControl is set to MQCUOWC_ONLY

v MQCIH.LinkType is set to MQCLT_PROGRAM to specify use of the CICS DPL bridge<?xml version="1.0" encoding="utf-8"?><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"



<xsl:template match="/">

<xsl:variable name="entries" select="dp:request-header('MQMD')"/><xsl:variable name="header" select="dp:parse($entries)"/><xsl:variable name="MsgId" select="$header//MsgId"/><xsl:variable name="CorrelId" select="$header//CorrelId"/><xsl:variable name="userID" select="$header//UserIdentifir"/>

<xsl:variable name="newMQMDStr">

<MQMD><Format>MQCICS</Format><CorrelId>

<xsl:value-ofselect="'414D51214E45575F53455353494F4E5F434F5252454C4944'"/>

</CorrelId><ReplyToQ>

<xsl:value-of select="'FROM.CICS.BRIDGE'"/></ReplyToQ>

</MQMD></xsl:variable><xsl:variable name="mqmdStr">

<dp:serialize select="$newMQMDStr" omit-xml-decl="yes"/></xsl:variable><dp:set-http-request-header name="'MQMD'" value="$mqmdStr"/>

<xsl:variable name="newMQCIHStr">

<MQCIH><Version>2</Version>

<UOWControl>MQCUOWC_ONLY</UOWControl><LinkType>MQCLT_PROGRAM</LinkType><Format>MQSTR</Format>

</MQCIH></xsl:variable><xsl:variable name="mqcihStr">

<dp:serialize select="$newMQCIHStr" omit-xml-decl="yes"/></xsl:variable><dp:set-http-request-header name="'MQCIH'" value="$mqcihStr"/>

</xsl:template></xsl:stylesheet>

Object descriptor header (MQOD)The MQOD header is not required to route traffic from a DataPower service tolocal queues. The DataPower service propagates the MQOD header and the local(MQ server) queue manager has the responsibility to route the message. TheMQOD header is used in the following situations:

v The target queue is on a queue manager that is remote to the MQ QueueManager object.

v The MQOD header can be used for back-end or front side PUT operations.v In error handling, use the MQOD header if the ReplyToQMgr is not configured.

Here is an example MQOD nodeset:<MQOD>

<Version>2</Version><ObjectName>REPLY.TO.QUEUE</ObjectName><ObjectQMgrName>REMOTEQM</ObjectQMgrName>

</MQOD>

The following scenario describes a set of two sample style sheets to demonstratehow to configure a service to support a complex, clustered MQ architecture. TheFigure 3 illustrates the WebSphere MQ architecture used in this example. Therouting infrastructure is comprised of multiple interactions of local and remotequeues that use the MQ headers MQMD and MQOD to implement the MQrouting pattern.

To start, the service picks up messages on a local queue that come from a remotequeue. The routing headers are configured on the message such that it can be sentback to an appropriate remote response queue. The service communicates with asingle local queue manager and therefore only requires a single connection channeldefinition. The MQOD header specifies which queue on which queue manager tosend the message, but it does not specify connection information.

Figure 3. Message flow in a clustered WebSphere MQ server environment


To route to the DataPower service, an application will put a message to a servicequeue (QA.REQUEST) using a remote definition on a clustered queue manager(QM_B). The service is instructed to forward the request to a remote queue(QB.LOOPBACK.REQUEST) on the clustered queue manager (QM_B), so theservice creates and injects an MQOD header with that information, and puts themessage to an alias of the clustered queue on the local queue manager (QM_A).Next, the service reads the reply using a local queue (QA.LOOPBACK.REPLY), andfinally replies to a remote queue (QB.REPLY) on a clustered queue manager(QM_B) by using another MQOD header and writing to the local queue manager(QM_A).

To demonstrate various facets of this configuration, the style sheets used in therequest, reply, and error rules incorporate several features:v Sets and clears replyToQ and replyToQM to support the clustered routing.v Generates necessary MQOD headers for clustered routing.v Supports both datagram (one-way) and request and reply (two-way) scenarios.v Demonstrates custom error handling, such as sending an error reply as opposed

to using the default backout logic. (See Chapter 5, “Error handling,” on page 45for more information.)

The style sheet for the request rule performs the following steps:1. Parses and saves input variables for use throughout the transaction processing.2. Tests the message type, msgtype, for a datagram message or a request and reply

message.3. Generates the back-side URL for the appropriate message type such that the

URL for request and reply messages contain the ReplyQueue.<?xml version="1.0" encoding="UTF-8"?><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"





<xsl:variable name="mqmd" select="dp:parse(dp:request-header('MQMD'))" /><xsl:variable name="requestQ"

select="substring-after(dp:variable('var://service/URL-in'),'RequestQueue=')" />

<xsl:variable name="requestQMgr"select="substring-before

(substring-after(dp:variable('var://service/URL-in'),'dpmq://'),'/')" />

<dp:set-variable name="'var://context/mq/input'" value="."/><dp:set-variable name="'var://context/mq/mqmd'" value="$mqmd"/><dp:set-variable name="'var://context/mq/msgtype'"

value="normalize-space($mqmd//MsgType/text())" /><dp:set-variable name="'var://context/mq/format'"

value="normalize-space($mqmd//Format/text())" /><dp:set-variable name="'var://context/mq/requestq'"

value="$requestQ" /><dp:set-variable name="'var://context/mq/requestqm'"

value="$requestQMgr" /><dp:set-variable name="'var://context/mq/replytoq'"

value="normalize-space($mqmd//ReplyToQ/text())" /><dp:set-variable name="'var://context/mq/replytoqm'"

value="string(normalize-space($mqmd//ReplyToQMgr/text()))" />

<xsl:variable name="target">

<xsl:choose><xsl:when test="dp:variable('var://context/mq/msgtype') = '8'">

<xsl:value-ofselect="concat('dpmq://',/payload/route/queueManager,'/?RequestQueue=',/payload/route/requestQueue)"/>

</xsl:when><xsl:otherwise>

<xsl:value-ofselect="concat('dpmq://',/payload/route/queueManager,'/?RequestQueue=',/payload/route/requestQueue,';ReplyQueue=',/payload/route/replyQueue)"/>

</xsl:otherwise></xsl:choose>

</xsl:variable>

<dp:set-variable name="'var://service/routing-url'" value="$target"/>

</xsl:template>

<xsl:template match="*"><xsl:copy-of select="."/>

</xsl:template>

</xsl:stylesheet>

The style sheet for the response rule performs the following steps:1. Tests for an MQ error response by checking the x-dp-response-code.2. Tests whether the message originated from a remote queue manager.3. If necessary, creates and injects the MQOD with the remote queue manager and

queue information.<?xml version="1.0" encoding="UTF-8"?><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"



<xsl:variable name="mqrc"select="normalize-space(dp:response-header('x-dp-response-code'))" />

<xsl:if test="starts-with($mqrc, '2') and string-length($mqrc)= 4"><dp:reject>MQ Error (RC: <xsl:value-of select="$mqrc"/>)</dp:reject>

</xsl:if>

<xsl:choose>



<xsl:when test="dp:variable('var://context/mq/requestqm')!= dp:variable('var://context/mq/replytoqm')">

<dp:set-response-header name="'ReplyToQM'"

value="dp:variable('var://context/mq/requestqm')" /><dp:set-response-header name="'ReplyToQ'" value="''" />



<xsl:variable name="xmlMQOD">

<MQOD><Version>2</Version><ObjectName><xsl:value-of

select="dp:variable('var://context/mq/replytoq')"/></ObjectName><ObjectQMgrName><xsl:value-of

select="dp:variable('var://context/mq/replytoqm')"/></ObjectQMgrName>

</MQOD></xsl:variable>

<xsl:variable name="strMQOD"><dp:serialize select="$xmlMQOD" omit-xml-decl="yes"/>

</xsl:variable>

<dp:set-response-header name="'MQOD'" value="$strMQOD"/>

</xsl:when></xsl:choose>

</xsl:template>

<xsl:template match="*"><xsl:copy-of select="."/>

</xsl:template>

</xsl:stylesheet>

WebSphere MQ API supportThe DataPower appliance supports the WebSphere MQ client API through the useof extension variables. For the user who is very familiar with the WebSphere MQarchitecture and implementation details, this new capability might provide aneeded flexibility.

In general, these options should only be used by a WebSphere MQ expert who hasa specific desire to set a certain option in an MQ call. These options only work forconnections created using the dynamic mq:// URI format explained in “Using theMQ URL to set back-side destinations” on page 10. The options are set using thesame values as detailed in the WebSphere MQ API documentation available athttp://www.ibm.com/software/integration/wmq/library/.

For example, suppose you need to send a message to a distribution list (adistribution list is a list of local queues on a single queue manager).

This is done by defining an array of MQOR structures. Each structure needs theObjectName field set to one of the destination queues. The MQOD structure thenpoints to this list and sets a field indicating the length of the list. This only workswith version 2 of the MQOD structure. The MQOD structure is finally the input tothe MQPUT call. The requirement can be implemented on a DataPower service bydoing the following :1. Create a Processing Policy with a rule matching the desired criteria.2. Employ a Set Variable action that sets the var://context/INPUT/_extension/

header/MQOD variable to:<MQOD><Version>2</Version><RecsPresent>3</RecsPresent></MQOD>

You can also use the dp:set-request-header() or dp:set-response-header()functions to set the MQOD header, in the same way you can set the MQMDheader.


http://www.ibm.com/software/integration/wmq/library/

3. Employ a Set Variable action that sets the var://context/INPUT/_extension/header/MQOR variable to<MQOR><ObjectName>Q1</ObjectName></MQOR>,<MQOR><ObjectName>Q2</ObjectName></MQOR>,<MQOR><ObjectName>Q3</ObjectName></MQOR>

4. Employ a Results action with a destination determined by an mq:// URL withno specified RequestQueue, such as:

mq://x.x.x.x/test/RequestQueue=

Here is a list of the extended header variables supported:v MQCONNX.QMgrNamev MQCNO.ConnTag (z/OS® only)v MQCNO.ConnectionId (output only)v MQCD.ChannelNamev MQCD.Descv MQCD.DiscInterval (inactivity timer in seconds)v MQCD.MaxMsgLengthv MQCD.ConnectionNamev MQCD.HeartbeatIntervalv MQCD.LongRemoteUserIdv MQCD.SSLCipherSpecv MQCD.SSLPeerName (indirectly sets the string pointer and length)v MQCD.SSLClientAuth (value of REQUIRED or OPTIONAL)v MQCD.KeepAliveIntervalv MQCD.LocalAddressv MQCSP.UserId (indirectly sets the string pointer and length)v MQCSP.Password (indirectly sets the string pointer and length)v MQSCO.FipsRequiredv MQSCO.KeyResetCountv MQSCO.AuthInfoRec (indirectly sets the pointer and count)

You can set multiple AIR just by adding more headers:v MQAIR.AuthInfoConnName (LDAP server host and port)v MQAIR.LDAPUserName (indirectly sets the string pointer and length)v MQAIR.LDAPPassword

You can differentiate between the Object Descriptor for the Get and Put by usingX-MQOD-Get and X-MQOD-Put. Note that MQOD is write only; you cannot readthe values in this structure.

MQPMO.Options are set in the MQ URI using the PMO= attribute. Options for GET(MQGMO.Options) are set in the MQ Front Side Handler configuration.

Headers can be ordered on the wire in the sequence that they are set.


Chapter 4. Units of Work

The WebSphere MQ protocol includes the Units of Work concept. That is, theprotocol includes the ability to put messages on queues within a unit of work suchthat those messages are made visible to other programs only when the programcommits the unit of work. To commit a unit of work, all updates must besuccessful to preserve data integrity. This concept also includes the ability to rollback transactions. When a program performs a backout, WebSphere MQ restoresthe queues by removing the messages that were put on the queues by that unit ofwork.

WebSphere MQ distinguishes between local and global units of work. Local unitsof work are those in which the only actions are puts to, and gets from, WebSphereMQ queues, and the coordination of each unit of work is provided within thequeue manager. Global units of work are those in which other resources, such astables in a relational database, are also updated. Transaction manager softwaremust coordinate the global unit of work.

The DataPower appliance supports only local units of work, not global units ofwork between the appliance and the queue manager. If different queue managersare used for the front side and the back end, two separate units of work aresupported with each unit of work coordinated by the respective MQ QueueManager object. The implementation supports units of work from front side toback end only when all of the following conditions are true:v Both the front side and back end use the same queue manager.v The MQ Queue Manager object used by the front side has the Units of Work

field set to 1.v The MQ URL of the back end contains the Transactional = true parameter.

This chapter includes the following topics:v “WebSphere MQ client Units of Work capabilities”v “Units of work implementation” on page 36v “Configuring transactions on a service” on page 38v “Common message delivery patterns” on page 40v “Units of work with other protocols” on page 44

WebSphere MQ client Units of Work capabilitiesThe standard WebSphere MQ client library supports the concept of local units ofwork. A unit of work begins when a WebSphere MQ client retrieves (callsMQGET) a message from a queue and ends with an MQCMIT or an MQBACK.The Queue Manager managing the queue from which the request message isretrieved automatically holds a copy of the message on the queue and allows noother client to retrieve the same message until the Queue Manager receives eitheran MQCMIT or an MQBACK signal on the same client connection. Uponreceiving an MQCMIT, the Queue Manager deletes the message. Upon receivingan MQBACK, the Queue Manager makes the message again available to any clientfor retrieval.

A unit of work might include more than one message. An application can specify agroup of MQPUT or MQGET messages all belong to the same unit of work, or


transaction. There can be any number of MQPUT or MQGET messages within theunit of work. All of the messages in the group must process successfully or all ofthem are rolled back together.

A unit of work is associated with the connection between the WebSphere MQ clientand the queue manager. Multiple queues can be opened on the connection forMQGET and MQPUT operations. Because these operations take place on the sameconnection, the queues are all managed by the same queue manager.

Here is a summary discussion of unit of work:1. A unit of work begins when a WebSphere MQ client specifies SYNCPOINT=True

on the first MQGET or MQPUT. The unit of work is committed usingMQCMIT, or rolled back using MQBACK, on the same connection.

2. When a WebSphere MQ client retrieves (MQGET) a message from a queuewithin a unit of work, that message remains on the queue but is not availableto other clients.

3. The queue manager permanently deletes the message from the queue when theclient issues an MQCMIT on the same connection. If the client issues anMQBACK, the queue manager restores the message by making it available tobe retrieved by any client.

4. When a client places a message (MQPUT) on a queue within a unit of work,the queue manager makes that message available to other applications onlywhen the client issues an MQCMIT on the same connection. If the clientdetects an error, it can issue an MQBACK. The queue manager restores thequeue by removing the message that was put on the queue by that unit ofwork.

5. If the application failed before issuing MQCMIT or MQBACK, or the networkfailed, the unit of work is rolled back by the queue manager. If the applicationMQDISC before issuing MQCMIT or MQBACK, the queue manager willcommit the unit of work.

6. Clients can determine the number of times the same message has beenretrieved from a queue by examining the BackoutCount field in the MQMD.This field contains the number of times the message has been previouslyrequested and subsequently backed out.

Units of work implementationThis section discusses how the DataPower appliance implements WebSphere MQunits of work. The MQ implementation functions as a special purpose WebSphereMQ client. The sequence of events is as follows:1. When an MQ Front Side Handler object associated with a Multi-Protocol

Gateway service is ready to retrieve a new message, the MQ Front SideHandler object gets a connection to the queue manager of the Get queue fromthe connection cache. If no connections are available, the handler opens a newone using MQCONNX.

2. The MQ Front Side Handler object issues an MQOPEN for the Get Queuespecified in the handler configuration, if it is not already opened and cached,and issues MQGET to get the next request message on the Get Queue toprocess. If the Units of Work property of the MQ Queue Manager object is setto 1 (that is, enabled), the MQGET is issued with SYNCPOINT=true to mark thestart of a unit of work.

3. The Front Side Handler object passes the message returned by MQGET to theprocessing policy of the Multi-Protocol Gateway service. The service parses themessage headers, which become available through various service variables.


The processing policy can consist of a request rule to process the requestmessage before passing the message to any back-end server. The policy mightalso optionally include a response rule to process a reply message from theback-end server, and optionally an error rule to handle any errors that occurduring processing.

4. When the request rule completes, the Multi-Protocol Gateway service sends thepossibly altered message to the back-end server. When the service connects tothe back-end server using the WebSphere MQ protocol, the gateway serviceemploys an MQ URL opener, which can set PMO for the MQPUT of the request,and the GMO of the MQGET for the reply. If the DataPower MQ Queue Managerobject handling the transmission of the request to the back-end server has theUnits of Work property set to 1, and the MQPUT is issued withSYNCPOINT=true, the MQPUT of the request message to the back-end queue isimmediately followed by an MQCMIT upon success. It is important to notethat the back-end MQPUT typically goes to a different queue manager than thefront, and even if it is to the same queue manager as the front it would use adifferent connection. Therefore, the unit of work for the back-end connection isnot the same as the unit of work for the front side connection.

5. The Multi-Protocol Gateway service retrieves a response from the back-endserver using an MQGET issued to the queue specified by the ReplyToQueue ofthe destination URL. Note that although the MQGET for reply message can beissued with SYNCPOINT=true using GMO, there is no corresponding logic to laterissue an MQCMIT or MQBACK and hence should be avoided. Any responserule in the processing policy matching the message executes, possibly alteringthe message or the message headers.

6. When the processing policy completes, the MQ Front Side Handler object issignaled and any response data from the back end is MQPUT to a front queueusing one of the following methods:v The ReplyToQ in the MQMD of the reply message (which might be altered

during response processing)v The ReplyToQ in MQMD of the initial request messagev The statically configured Put Queue in MQ Front Side Handler object which

uses the same connection as the Get Queue of the MQ Front Side Handlerobject

7. The MQ Front Side Handler object issues an MQCMIT on the same connectionto the queue manager handling the queue from which the handler originallyretrieved the message when the handler successfully places the response on thecorrect Reply-to queue. Note that if the statically configured Put Queue is usedin step 6, the MQCMIT will apply to both the initial MQGET on the GetQueue and the MQPUT on the Put Queue. Any error that stops the processingpolicy processing or causes an error rule to run will result in a MQBACKissued instead of a MQCMIT.

8. When a message remains on a request (GET) queue after a failure, the MQFront Side Handler object will again retrieve the same message. It is possiblethat this loop could continue indefinitely (although many queue managersdetect messages left on a queue for a long time and remove them). You canhandle this case automatically on the DataPower appliance if you configure theMQ Queue Manager object used by the MQ Front Side Handler object with thefollowing property values:a. Set the Automatic Backout flag to on

b. Set the Backout Threshold property to the appropriate valuec. Set the Backout Queue Name property to the appropriate value

Chapter 4. Units of Work 37

The MQ Front Side Handler object using the queue manager tracks theMQMD.BackoutCount header value of the MQGET of the request (GET) queue. Ifthe MQMD.BackoutCount reaches the configured backout threshold, the MQ FrontSide Handler object will move (MQPUT) the message on the queue identifiedby the Backout Queue Name property (typically the dead letter queue) andissue MQCMIT to the request queue to break the loop.

The DataPower appliance MQ unit of work implementation is “loosely coupled” toallow users to meet different reliability requirements for different message deliverypatterns through different configurations. Users must be careful to have the correctconfiguration for the message exchange pattern desired.

Configuring transactions on a serviceA transaction is a sequence of operations that end with either a commit or a rollback. A transaction commits if all the operations in the transaction succeed. Atransaction rolls back if any one of the operations in the transaction fails. TheDataPower appliance, acting as the WebSphere MQ client, participates in localtransactions, or units of work. When enforcing transactions, when a message isfetched from a queue with an MQ GET operation, the message is not physicallyremoved from the queue until the MQCMIT operation performs a commit.Similarly, when a message is put onto a queue with the PUT operation, themessage is not available for another GET operation until the commit.

Several configuration options on the DataPower appliance control when atransaction commits or rolls back:v The Units of Work property of the MQ Queue Manager object associated with

the front side handler object. See “Units of Work property” on page 39.v The Transactional parameter of the back-end MQ URL. See “Transactional

parameter” on page 39.v The Sync parameter of the back-end MQ URL. See “Sync parameter” on page 40.v The MQGMO and MQPMO syncpoint options. See “MQGMO and MQPMO

syncpoint options” on page 40.

The DataPower MQ client library provides transactional support on both sides ofthe Multi-Protocol Gateway service, front side and back end. The Units of Worksetting controls front side synchronization. The Transaction and Sync parameters ofthe back-end MQ URL control back-end synchronization.

Figure 4 on page 39 depicts a scenario where MQ operations are performed onboth the front side and back end of a Multi-Protocol Gateway. In this example, twoqueue managers are used, “A” and “B”. The Multi-Protocol Gateway service usesan MQ Front Side Handler object to communicate with queue manager “A” and astatic back-end MQ URL to target queue manager “B”. Queue manager “A”, on thefront side, has two queues: FRONT.GET and FRONT.BACK. Queue manager “B”,on the back end, has two queues: BACK.REQUEST and BACK.REPLY.

In this scenario, because there is a different queue manager on the front side fromthe queue manager on the back end, the scope of the unit of work is limited toeither the front side or the back end.


Units of Work propertyThe Units of Work property manages transactionality on the front side. When thisproperty is set to 1, retrieved messages are synchronized when they aresuccessfully delivered to the back end destination queue and the transaction iscomplete. The queues in Figure 4 show the message flow when units of work is setto 1:1. The MQ Front Side handler object retrieves messages from the FRONT.GET

queue.2. The message is successfully delivered to the back-end destination

BACK.REQUEST queue.3. The transaction commits and the message is removed from the FRONT.GET

queue.

Transactional parameterThe Transactional parameter is set to true on the back-end MQ URL tosynchronize the PUT operation to the request queue with the GET operation fromthe reply queue. When the following conditions are true, the service uses the sameconnection on the front side and the backend.v The Transactional parameter is set to true.v The same queue manager manages both the front side and the back-side

connectionsv The static MQ URL, dpmq://, format is used.

Figure 4 shows the message flow when the Transactional parameter is set to true:1. The message is PUT to the back-end BACK.REQUEST queue.2. A GET operation retrieves the message from the BACK.REPLY queue.3. The GET and PUT operations are committed when the GET operation from the

BACK.REPLY queue is successful and the transaction is complete.

Note: If no reply queue is specified, the transaction does not require the GEToperation. The transaction commits as soon as the PUT operation to the

Figure 4. Basic architecture for MQ to MQ messaging


BACK.REQUEST queue completes.See “Sync parameter” for information on using the Transactional parameter withthe Sync parameter.

When the Transactional parameter is not specified, false is assumed.

Sync parameterWhen the Sync parameter is set to true on the back-end MQ URL, the PUToperation to the request queue is committed immediately upon successful deliveryof the message. The Sync parameter is used in conjunction with the Transactionalparameter to force the transaction to use a single connection and to commit theback-end PUT operation for request and reply message traffic.

The queues in Figure 4 on page 39 show the message flow:1. The message is delivered to the back-end BACK.REQUEST queue.2. The PUT operation is committed and completes the transaction.

Note: Because the PUT operation is committed immediately upon successfuldelivery of the message, back-end applications can see the message on therequest queue and can use the GET operation to process the message forpotential delivery to BACK.REPLY. The Sync parameter must be set to trueif there is both a back-end request and a reply queue. If it is not set, theback-end application will not see the message placed on BACK.REQUEST.

When the Sync parameter is not specified, false is assumed.

MQGMO and MQPMO syncpoint optionsWhen units of work is set to 1, you can use the MQGMO and the MQPMOsyncpoint options to include GET and PUT operations in a unit of work. Forinstance, if you use a PUT operation with the MQPMO option set to 2 orMQPMO_SYNCPOINT, the PUT operation is committed inside a unit of work. If thereare multiple PUT operations and any one fails, you can use the final action of aprocessing policy to perform a dp:reject to roll back the transaction. Otherwise,all the messages within the unit of work are committed.

Common message delivery patternsThe DataPower appliance supports a number of application-specific deliverypatterns using all of the configuration tools available. Many sites require the abilityto send a message from one WebSphere MQ queue to another (fire) and make noattempt to track the results or response (forget). The WebSphere MQ messagingsystem can easily support this pattern because WebSphere MQ is asynchronous. Aresponse to a request is not required, unlike HTTP. Often, sites also require thatthis asynchronous (fire-and-forget) pattern provide assured delivery of messages,with no loss of messages and no duplication of messages during operation.

Many sites require transaction-style (synchronous) delivery, in which each requestmust result in a response. The WebSphere MQ system provides some mechanismsto support this delivery pattern, which the service uses (notably the correlation ofrequests to responses using the Message ID of the request set to the Correlation IDof the response).

This section describes each of these two common delivery patterns. These patternsapply to scenarios in which the service retrieves messages from a WebSphere MQ


queue using an MQ Front Side Handler, and delivers messages to a destinationWebSphere MQ queue on the back end. Figure 5 illustrates this architecture.

Independent asynchronous deliveryIt is possible to implement asynchronous (fire-and-forget) delivery of requests andresponses (independently in each direction). In this scenario, two separateMulti-Protocol Gateways are used, one for each direction.

For each Gateway, use the following configuration parameters:v Units of Work property of the MQ Queue Manager object on the appliance set

to 1 (enabled)v Process Backend Errors property of the Gateway set to off (allowing the

appliance to automatically roll back the front side GET when connection errorsare detected)

v No Reply-to queue specified in the destination URL. This causes the Gateway toautomatically send an MQCMIT to the front side request queue as soon as theMQPUT on the other side succeeds, completing the unit of work, withoutlooking for a response. Note that the header of the message must also contain noReplyToQ specification (that is, blank).

Note that the back-end MQPUT is not on the same connection as the front sideMQGET, especially if message routing is involved. However, with no responserule processing, the probability of an appliance failure between the back-endMQPUT and the front side MQCMIT is extremely small. In the unlikely event thatthis happens, the original front side request message will be restored by the QueueManager automatically (due to a lost connection) and processed by the serviceagain upon recovery of the appliance, resulting in duplicate delivery.

For guaranteed asynchronous delivery with no duplicates, both Multi-ProtocolGateways can be configured to use loopback processing, thus omitting the backend altogether. Instead, the Gateway uses the Front Side Handler to place

Figure 5. Common message delivery patterns


(MQPUT) the message on the Front Side Handler's PUT queue after all ProcessingPolicy actions for the request have completed. This is done by setting thewrite-only service variable var://service/mpgw/skip-backside to 1 (on) in theMultistep Policy. The configured Put Queue in the MQ Front Side Handler must beused as it is opened on the same connection as the MQ Front Side Handler GetQueue. The MQCMIT issued by the Gateway then commits both the MQGET andMQPUT messages atomically.

This delivery pattern requires that the same MQ Queue Manager manages both thequeue containing request messages (typically the front side) and the queuemonitored by the back-end server (typically the back end). This delivery patternalso requires that the same MQ Queue Manager manages both the queuecontaining back-end response messages and the reply queue monitored by therequesting application. The two Queue Managers (one for each direction) might bedifferent.

All the policy contexts and variables for each direction are separate and notavailable to each other. It is not, for example, possible to correlate a request to theback-end server with the response using Message IDs and Correlation IDs.

Synchronous deliveryWebSphere MQ provides features to support synchronous (request-responsetransaction type) delivery patterns. Requests can be correlated with responses, anddynamic routing can be used to facilitate workflow. The DataPower applianceprovides such support and other additional features such as failover acrossmultiple queues and Queue Managers. Note that the use of these additionalfeatures does conflict with the ability to use units of work to guard againstmessage duplication.

For a synchronous delivery pattern, a single Multi-Protocol Gateway processesboth the request and reply messages of the transaction. Here are the importantconfiguration parameters:v The Units of Work property of the MQ Queue Manager object on the appliance

used by the Front Side Handler should be set to 1, enabling units of work.v The Process Backend Errors property of the Gateway should be set to off so

that back-end errors will cause the front side to issue an MQBACK to theQueue Manager.

v The Gateway's Processing Policy should include an error rule to handle failuresencountered during the transaction.

Using the reference diagram below, the following are the possible failure situations:#1 <--------- GET Request

PUT Request ---------> #2GET Reply ---------> #3

#4 <--------- PUT Reply

Appliance failure between points 1 and 2The Queue Manager detects failure (connections disappear) and recovers therequest message on queue #1.

WebSphere MQ infrastructure failure at point 2The DataPower service will try to issue MQBACK at #1 and start over. IfMQBACK failed, the service would close the connection and start over. The closedconnection will cause the Queue Manager to restore the request message.


Appliance failure between point 2 and point 3The Queue Manager will restore request message at #1, but that request has beensuccessfully delivered to queue #2 and the reply from the back-end server might beon queue #3. Because the DataPower appliance failed, the front side request QueueManager restores the request message to the queue, even though the service has infact successfully delivered it to the back-end server. However, when appliancerecovers, it would not get the reply on queue #3 due to the use of a synchronousdelivery pattern (matching response to request through IDs). The service mightalso be using dynamic Reply-to queues, which would no longer be known to theappliance. If the back-end server application is idempotent, the server applicationwill produce the same result when the service again delivers the request message.The back-end server application places another reply message on its reply queuewith the correct CorrelationID, and the transaction completes successfully. If theback-end application is not idempotent, the back-end server application will needto incorporate protections against receiving a request message twice.

WebSphere MQ infrastructure failure at point 3Two kinds of errors can occur here. If the DataPower service encounters aconnection error and cannot establish a connection to the back-end Reply queue,the service will run the configured error rule. After the error rule completes, MQFront Side Handler error handling will issue MQBACK at #1, causing the originalrequest message to be restored to the queue. If the service can establish ormaintain a connection to the back end Reply queue but the server application failsto produce a reply, the service will again run any matching Error rule and issueMQBACK at #1, provided the URL used to designate the back-end connectionspecifies a Timeout value. If no timeout is set, the service will wait indefinitely.

You can alternatively cause the service to place an error message at #4 and issue anMQCMIT at #1. To do this, set the Process Backend Errors property to on and setthe Timeout parameter of the destination MQ URL. In addition, you must set theResponse Type property of the Gateway to Non-XML. Upon timeout, because theservice never gets a correlated response message from the application server, theservice runs a response rule to send a specific message to queue #4. This againcauses an MQCMIT to be sent to the Queue Manager of the request queue.

Appliance failure between point 3 and point 4The reply message taken from #3 is lost. The Queue Manager handling the frontside connection will detect the appliance failure and restore the request message at#1.

WebSphere MQ infrastructure failure at point 4The DataPower service will issue an MQBACK signal at #1, thus restoring theoriginal request message to the queue, which will result in a duplicate messagedelivered to the back-end server.

Note that the use of two separate Multi-Protocol Gateways for a synchronousdelivery pattern is not recommended. The two separate Gateways cannot sharetransactional data, such as Message ID and Correlation ID.


Units of work with other protocolsThe DataPower service interconnects the WebSphere MQ protocol system withother protocols, including HTTP, JMS, TIBCO EMS and FTP. This section discussesthe behavior of the service when units of work is 1 and non-MQ protocols are usedfor either the front side connection or the back-end connection.

Front SideThe DataPower service only commits the GET of a message from the MQ FrontSide Handler GET queue when the entire transaction completes successfully. Thisdoes not change when the protocol used to connect to the back-end applicationserver is not MQ.

As with a WebSphere MQ back end, errors can be handled by controlling theProcess Backend Errors and Response Type properties of the Gateway, plus anyTimeout parameters used in the back-end URL.

Back SideThe MQ units of work affects only the placement (PUT) of a message on therequest queue of the back-end server, and is not in any way affected by theoperations of a different protocol on the front side of the Gateway. The operationof the front side might be affected by the methods used to handle errorsencountered when using units of work on the back-end WebSphere MQconnection. Errors can be handled by controlling the Process Backend Errors andResponse Type properties of the Gateway, plus any Timeout parameters used inthe back-end URL.


Chapter 5. Error handling

A Multi-Protocol Gateway service uses all of the standard error handlingcapabilities available for HTTP traffic. This includes processing policy Error rules,the On-Error action, automatic fault generation when a request or responsemessage does not pass validation checks, and custom error message generation.The service can also use custom style sheets to implement error handling.

When designing an error handling strategy, consider whether the service willhandle datagram (one-way) and request and reply (two-way) message traffic. TheDataPower service considers a message a response when the MQMD headerCorrelationId property of the response message matches the MQMD headerMessageId property of the request message. The service does not use theWebSphere MQ defined message type, MQMD.MsgType, such as datagram, request, orreply, unless specifically instructed to do so within a style sheet. A service thatreceives both datagram and request and reply message traffic, must have a stylesheet with customized error handling.

The following topics highlight specific approaches to use for error handling in anintegrated DataPower and WebSphere MQ environment.v “Automatic Retry property”v “Process Backend Errors property” on page 46v “Automatic Backout property” on page 46v “The MQ reason code (MQRC)” on page 47v “Using the error-ignore service variable” on page 49v “Using an error rule” on page 51

Automatic Retry propertyIf the network connection to a queue manager fails for any reason other thanWebSphere MQ reason code (MQRC) 2009 (connection broken), the service cancelsthe transaction and starts error handling (such as running a configured Error rule).The service also starts the automatic retry mechanism as determined by theAutomatic Retry property of the MQ Queue Manager object. When the AutomaticRetry property is set to on, the DataPower service attempts to reconnect to theremote host. This setting does not affect attempts to put or get messages over anestablished connection.

In response to a MQRC 2009 error, by default the service retries placing a messageon a queue once. For MQ errors other than MQRC 2009, the number of retryattempts is determined by the Retry Interval property of the MQ Queue Managerobject.

If repeated connection attempts to an unresponsive remote queue manager fail, theservice can instead connect to an alternative, or failover, queue manager. Thisalternative queue manager is defined by an MQ Queue Manager Group object. See“MQ Queue Manager Group” on page 65 for more information.


Process Backend Errors propertyIn general, back-end protocol level error handling is controlled by the ProcessBackend Errors property of the Multi-Protocol Gateway service. If this property isset to on, the service uses the response rule of the processing policy to process anymessage received with the error. In this way, transactions successfully completeeven though an error occurred. If you do not create a response rule to handle thiscondition, the service generates an automatic error message.

Because errors in WebSphere MQ often contain no message, when an error occurs,the service runs any configured error rule. If the Process Backend Errors propertyis set to off, the service returns an HTTP 500 response to the caller unless an errorrule is configured.

To have the Gateway automatically generate an error message in all error cases, setProcess Backend Errors to off. You can then optionally configure an error rule inthe processing policy to handle the error condition.

When to use the Process Backend Errors propertyWhen enabled, the Process Backend Errors property uses the response rule in aprocessing policy to handle any error messages. Because a datagram does notrequire a reply from the back-end application, a processing policy for this trafficmost likely does not contain a response rule. The Process Backend Errors propertyis appropriate for services that handle request and reply messages. It is notintended to be used with services that exclusively handle datagrams unless customerror processing is desired and is configured in the response rule.

Automatic Backout propertyWith the Automatic Backout property enabled, the Multi-Protocol Gateway servicerequests the queue manager to remove a message that results in an error and placethe offending message on an alternative queue available through the same queuemanager. When enabled, the Automatic Backout property prevents an infinite loopif the queue manager handling the queue does not remove messages from itsqueues.

When to use the Automatic Backout propertyUse the Automatic Backout property in conjunction with units of work so that theDataPower service reroutes any errors that are not specifically handled by othermethods.

For example, suppose you are using an error rule that matches specific MQ reasoncodes. When an MQRC is returned from the WebSphere MQ server, such as whena queue is full or inhibited, the configured error rule processes the error. However,if an error occurs that does not return an MQRC, the error rule does not capture it.This might happen if there is a back-end communication problem error such aswith a WebSphere MQ channel. In these situations, because the error does notmatch the error rule, the service moves the message to the backout queue specifiedby the Automatic Backout properties.

Enabling automatic backoutWhen a message remains on a request (GET) queue after a failure, the MQ FrontSide Handler object retrieves the same message again, possibly causing a loop.This loop can continue indefinitely unless the queue manager detects the message


left on the queue and removes it. You can prevent this issue by configuring thefollowing property values on the MQ Queue Manager object used by the MQFront Side Handler object:1. In the Units of Work field, set the value to 1 to expose the backout fields.2. In the Automatic Backout field, set the value to on.3. In the Backout Threshold field, specify the number of times for the message to

be reprocessed.4. In the Backout Queue Name field, designate an alternative queue.

Using the backout settings from the WebSphere MQ serverUse the optional Retrieve Backout Settings field to determine whether to retrievethe backout threshold and backout requeue queue name from the WebSphere MQserver rather than using the Automatic Backout and associated Backout Thresholdand Backout Queue Name settings on the MQ Queue Manager object.

The Retrieve Backout Settings field on the MQ Front Side Handler object allowsthe service to retrieve the backout settings from the WebSphere MQ server. Theretrieved settings override the values configured in the MQ Queue Manager object.When the MQ Queue Manager object defines backout values and the RetrieveBackout Settings is enabled, the MQ Front Side Handler object retrieves thebackout threshold and backout requeue queue name from the WebSphere MQserver and compares these values to the backout values for the MQ QueueManager object. If the WebSphere MQ server does not contain backout settings, thehandler uses any existing backout values, either empty or populated, from the MQQueue Manager object.

The MQ Front Side Handler object retrieves the settings from the WebSphere MQserver at the time the MQ Front Side Handler object changes to the up state. If youmodify the settings on the WebSphere MQ server queue, the MQ Front SideHandler object must be restarted to synchronize the settings.

The MQ reason code (MQRC)You can read and use a number of MQ-specific event (reason) codes that areprovided on the appliance for error processing. The MQRC displays in the logwhen there are errors with communications, queue managers, queues, and so forth.Here is an example of an MQRC and message in a log message:Tue Jan 19 2009 16:24:53 [mq] [error] mpgw(service):tid(1511863)[x.x.x.x]:The get call timed out before receiving any messages (Reason Code 2033)

To view the reason codes in the WebGUI, use the following steps:1. Select Administration from the navigation bar.2. Under the Debug heading, click View List of Event Codes.3. Scroll down to the mq category.

Reading the MQRC in a style sheetWithin a style sheet, you can capture MQ reason codes by using thedp:response-header extension function to read the x-dp-response-code protocolresponse code. If this value matches both of the following criteria, the responsecode is a WebSphere MQ error:v Starts with the number 2

v Has a length equal to 4

Chapter 5. Error handling 47

The following example checks the MQRC with dp:response-header('x-dp-response-code') and depending on the reason code, issues dp:reject to trigger anerror rule.<xsl:variable name="mqrc"

select="normalize-space(dp:response-header('x-dp-response-code'))" />

<xsl:if test="starts-with($mqrc, '2') and string-length($mqrc)= 4"><dp:reject>MQ Error (RC: <xsl:value-of select="$mqrc"/>)</dp:reject>

</xsl:if>

Returning the MQ error message in a style sheetWhile a style sheet can extract the MQRC and provide the reason code back toclient, the associated text error message, such as “The get call timed out beforereceiving any messages” for MQRC 2033, is not available. To retrieve the text ofthe error, include a table with MQ reason codes and corresponding messages in an.xml file in a style sheet.

The following style sheet uses an .xml file called mqrc-codes.xml that contains theMQRC and the associated error text. The style sheet captures the MQRC whenused in an On error (on-error) action in the processing rule. The .xml file format isprovided after the style sheet.<?xml version="1.0" encoding="utf-8"?><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

xmlns:dp="http://www.datapower.com/extensions"xmlns:env="http://schemas.xmlsoap.org/soap/envelope"extension-element-prefixes="dp"exclude-result-prefixes="dp" version="1.0">

<xsl:output method="xml"/><xsl:template match="/">

<xsl:variable name="mqData"select="document('local:///mqrc-codes.xml')"/>

<xsl:variable name="mqrc"select="dp:response-header('x-dp-response-code')"/>

<xsl:variable name="errorCode"select="dp:variable('var://service/error-code')"/>

<xsl:variable name="mqrc2"select="normalize-space($mqrc)"/>

<xsl:variable name="mqrc3"select="string-length($mqrc2)"/>

<xsl:choose><xsl:when test="(starts-with($mqrc, '2') and ($mqrc3 = 4))">

<xsl:variable name="mq-msg"select="$mqData/mqrc-codes/mqrc[@code=$mqrc]/@error-msg"/>

<xsl:message dp:priority="error"><xsl:value-of

select="concat(' ** MQ Reason Code (mqrc) ** : ',$mq-msg)"/>

</xsl:message><dp:set-variable

name="'var://service/error-protocol-response'"value="'200'"/>

<dp:set-http-response-headername="'x-dp-response-code'" value="'200 OK'"/>

<xsl:variable name="response-url"><dp:url-open target="dpmq://DP2/?ReplyQueue=MQ4"

response="xml"/></xsl:variable><xsl:copy-of select="$response-url"/>

</xsl:when><xsl:otherwise>

<dp:set-variablename="'var://service/error-protocol-response'"

value="'200'"/><dp:set-http-response-header

name="'x-dp-response-code'" value="'200 OK'"/><env:Envelope>

<env:Body><env:error><xsl:value-of

select="concat(' ** MQ Reason Code (mqrc) ** : ',$mqrc)"/>

</env:error></env:Body>

</env:Envelope></xsl:otherwise>

</xsl:choose></xsl:template>

</xsl:stylesheet>

The mqrc-codes.xml file used in the example contains the error text for MQ reasoncodes provided in View List of Event Codes. The file has the following elements:v A root element <mqrc-codes>v A child element <mqrc> with three attributes: code, event-code, and error-msg

Here is an example file showing the child elements for the MQ reason codes 2003and 2009:<?xml version="1.0" encoding="UTF-8"?><mqrc-codes><mqrc code="2003" event-code="0x0133000c"

error-msg="The unit-of-work was backed out (Reason Code 2003)"/><mqrc code="2009" event-code="0x0133000d

error-msg="Connection was broken (Reason Code 2009)"/>...</mqrc-codes>

Using the error-ignore service variableThe service variable, var://service/error-ignore, gets or sets a flag to controlhow the MQ Front Side Handler object processes error conditions. If the value isset and is greater than zero, the service does not run any error handling methodand produces a regular response. You can then use a style sheet to implementcustomized manual error handling.

When to use the error-ignore service variableSet the error-ignore service variable to 1 for datagram and request and replytraffic whenever the MQ Queue Manager object associated with the MQ Front SideHandler object is using units of work. Setting this variable will prevent anaccumulation of uncommitted messages on the GET queue.

For instance, consider a service with units of work enabled, Process Backend Errorsenabled, and a backout queue defined. When an MQGET operation gets a messagefrom the request queue, if any error causes an error rule to run, the MQPUToperation is not complete. Successful datagram messages complete the PUToperation to the back-side queue, but erroneous datagram messages require amanual PUT operation to a front-side backout queue.

This situation might occur, for example, in a development environment where astyle sheet fails to compile and the PUT operation does not complete. Therefore,the transaction does not commit and the message remains uncommitted on theGET queue. If this happens repeatedly, uncommitted messages can accumulate onthe request queue and the DataPower appliance connections can hang.

With the error-ignore service variable set to 1, the MQPUT operation to thebackout queue indicates successful completion of the transaction and the MQCMIToperation occurs, removing the message from the GET queue.

Using the error-ignore service variable in a style sheetThe sample style sheet that follows implements the error rule for the scenariodescribed in the section on the “Object descriptor header (MQOD)” on page 28.Note that the error-ignore service variable is set to 1 at the top of the style sheetto disable the default backout logic. The variable also can be set with a Set variable(setvar) action as the first action in the error rule.

The style sheet performs the following steps:1. Disables the default backout logic.2. Tests whether the message originated from a remote queue manager.3. Tests whether error handling should be performed based on the message type.4. Sets the ReplyToQM back to the original requestqm queue manager and clears out

the ReplyToQ queue.5. Creates and injects the MQOD header with the remote queue manager and

queue information.6. Generates an error message.<?xml version="1.0" encoding="UTF-8"?><xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"





<dp:set-variable name="'var://service/error-ignore'" value="'1'"/>



<xsl:if test="dp:variable('var://context/mq/requestqm')!= dp:variable('var://context/mq/replytoqm')">



<xsl:if test="dp:variable('var://context/mq/msgtype') != '8'">



<dp:set-response-header name="'ReplyToQM'"value="dp:variable('var://context/mq/requestqm')" />

<dp:set-response-header name="'ReplyToQ'" value="''" />



<xsl:variable name="xmlMQOD"><MQOD>

<Version>2</Version>

<ObjectName><xsl:value-of

select="dp:variable('var://context/mq/replytoq')"/></ObjectName><ObjectQMgrName>

<xsl:value-ofselect="dp:variable('var://context/mq/replytoqm')"/>

</ObjectQMgrName></MQOD>

</xsl:variable>

<xsl:variable name="strMQOD"><dp:serialize select="$xmlMQOD" omit-xml-decl="yes"/>

</xsl:variable>

<dp:set-response-header name="'MQOD'" value="$strMQOD"/>

</xsl:if>

</xsl:if>



<error><xsl:copy-of select="dp:variable('var://context/mq/input')"/>

</error>

</xsl:template>

</xsl:stylesheet>

Using an error ruleIn a processing policy, an error rule is invoked when an error occurs duringprocessing. The error rule acts as an error handler and allows you to create customerror messages. Error rules work in conjunction with the other error handlingmethods described in this chapter.

For instance, you can invoke an error rule depending on the MQRC in theresponse rule as described in “The MQ reason code (MQRC)” on page 47. If thereturn code is an MQ error, invoke an error rule by using dp:reject. The error rulecan generate an appropriate SOAP fault, non-XML error, or other error response, aswell as send the original request message or a SOAP fault to another queue. Ifnecessary, build an MQOD header to route to a target queue on a queue managerremote to the MQ Queue Manager object using the dp:set-response-headerextension element. For instance, this might be needed to send the original requestmessage to a remote dead letter queue.

Typically, if an error rule is invoked in an MQ to MQ environment that has Unitsof Work enabled, set the error-ignore service variable to 1 as the first action of theerror rule using a Set variable (set-var) action or using the dp:set-variableextension element. The Set variable action might be followed by a Transform actionor actions that determine routing based on message type or a Conditional actiondepending on how you want to handle the error.

MQ to MQ traffic calls for different error handling depending on the type ofmessage and whether Units of Work is enabled. The following sections list errorhandling methods used for MQ to MQ traffic in four different combinations ofmessage type and Units of Work and show how an error rule is one part of errorprocessing.

Datagram traffic with Units of Work disabledSince datagram is one way traffic with no response expected, the processing policywill have a request rule but no response rule. Use the following error processingmethods:v Set the Process Backend Errors property to off.v Optional: Specify an error rule if desired.

Datagram traffic with Units of Work enabledSince datagram is one way traffic with no response expected, the processing policywill have a request rule but no response rule. Use the following error processingmethods:v Set the Process Backend Errors property to off.v Enable Automatic Backout and specify the associated Backout Threshold and

Backout Queue Name settings on the MQ Queue Manager object.v Optional: Specify an error rule with the var://service/error-ignore service

variable set to 1.

Datagram traffic with custom error handlingSince datagram is one way traffic with no response expected, however, withcustomer error handling the processing policy will have both a request rule and aresponse rule to capture potential errors in the response header. Use the followingerror processing methods:v Set the Process Backend Errors property to on.v Capture the response code using dp:response-header('x-dp-response-code')

v Use dp:reject to invoke the Error rule if the value of the mqrc is 2xxx.v If Units of Work is enabled, specify an error rule with the var://service/error-

ignore service variable set to 1.

Request and reply trafficWith two way traffic in the request and reply traffic pattern, use a Request rule, aResponse rule, and an Error rule. Use the following error processing methods:v Set the Process Backend Errors property to on.v If Units of Work is enabled, enable Automatic Backout and specify the associated

Backout Threshold and Backout Queue Name settings on the MQ QueueManager object.

v Capture the response code using dp:response-header('x-dp-response-code')

v Use dp:reject to invoke the Error rule if the value of the mqrc is 2xxx.v If Units of Work is enabled, specify an error rule with the var://service/error-

ignore service variable set to 1.


Chapter 6. Additional configuration options

Authentication and authorizationA Multi-Protocol Gateway can use all of the standard AAA methods availablethrough an AAA Policy object. For example, you can examine a WS-Securityheader to obtain an identity that can be used to authenticate or authorize, or bothauthenticate and authorize, against an external authority. In addition to thestandard methods, you can also use values taken from the MQ header toimplement Transport Independent AAA. This is done using a Processing Metadataobject.

A Processing Metadata object contains a list of the header name-value pairs. TheAAA Extract Identity phase can use a Processing Metadata object. When the AAAaction executes, the system extracts this list of pairs and forwards the results as anodeset to the AAA Authentication phase. The AAA Authentication phase mustthen use a custom style sheet to create an authentication query to some authorityand pass on the results to the next phase of AAA.

Consider a scenario in which all messages must contain a UserIdentity valueauthenticated by a local LDAP authority. In this case, the Processing Metadataobject could contain just the UserIdentity node of the MQ header, which wouldthen be returned to the custom Authentication phase style sheet.

Monitoring, logging, and statusAll of the standard capabilities of the Multi-Protocol Gateway can be applied tomonitoring and logging of MQ transactions. These include Log Targets that sendselected log messages to remote facilities off the appliance, rotating log files, theLog action that delivers a copy of an entire message to a remote facility and thestandard Count and Duration monitors.

Because MQ runs on a Multi-Protocol Gateway, the Service Level Monitorcapability is also available. Through this capability, you can notify, shape andthrottle traffic in accordance with policy rules that can filter by credentials (who isasking) and by resources (to do what). The Resource Class of an SLM policy offersthe ability to select WebSphere MQ-specific attributes, such as Reply Queue Nameand Request Queue Name. You implement SLM by including an SLM action in theProcessing policy of the Multi-Protocol Gateway.

Note that in the case of MQ, you can also log messages by sending a copy of themessage to a particular remote queue by using a Results action. This queue canthen simply be archived.

You can use all of the standard means that are offered by a Gateway to collectstatus information, such as SNMP.

Ordered messagingThe DataPower appliance supports the processing of messages in the order inwhich they appear in the message queue. The feature provides the followingsupport:


v Allows for the correct processing of messages that are order-dependent by serverapplications

v Allows for the backing out of transactions that do not complete successfullywhen at least one message in the sequence is missing

For additional information, refer to Message Processing Modes in the referenceobjects section of the IBM WebSphere DataPower SOA Appliances: Multi-ProtocolGateway Developers Guide.

Using MQ with a Web Service ProxyThe Web Service Proxy service can also integrate with the WebSphere MQmessaging system. Here are some of the methods available to create thisconfiguration.v The Proxy can employ an MQ Front Side Handler to get SOAP request messages

from a WebSphere MQ queue, and optionally place any response on acorresponding reply queue.

v The Proxy can employ a statically-defined back end that uses WebSphere MQqueues to put requests and get responses. Because most WSDL files indicate anHTTP endpoint, you might need to manually change the Proxy type property tostatic backend from the typical default of static-from-wsdl. You will then needto specify the back-end URL using the MQ URL syntax.

v The Proxy can employ a Results (or Results Async) action in the ProcessingPolicy that sends messages to a WebSphere MQ queue.

MQ and JMSIt is possible to transport JMS messages over an WebSphere MQ system. In thiscase, some architectures allow for the selection of WebSphere MQ messages basedon values contained in the JMS message headers.

The DataPower service views JMS messages over MQ as illustrated in Figure 6.

The DataPower service recognizes and parses JMS headers in WebSphere MQmessages. Although you can use the service to read and select messages based onJMS header values regardless of release, the methods will differ. It is possible toselect WebSphere MQ messages based on JMS header values by using a Binary

Figure 6. JMS messages over MQ


Transform operation on the WebSphere MQ message body to extract the JMSheader values into an XML nodeset. This extracted nodeset can then be examinedfor the desired attributes.

You can examine the nodeset contained in the var://service/header-manifestvariable, which contains the parsed JMS headers. This includes headers in thefollowing formats:v MQMD

v MQRFH2

v MQRFH

v MQIIH

v MQDLH

v MQCIH

The MQMD.Format field value is MQRFH2. A JMS header follows after the standardMQMD header structure. The JMS header consists of the MQRFH2 structure followedby a number of short XML documents. The system now adds these XMLdocuments to the header manifest as “X-MQRFH2-Data-xxxx” headers. The appliancesupports WebSphere MQ messages with one MQRFH2 header. If a WebSphere MQmessage contains multiple MQRFH2 headers, only the last one is parsed.

Table 4. Header Manifest

Header Value

MQMD <MQMD>...</MQMD>

MQRFH2 <MQRFH2>...</MQRFH2>

X-MQRFH2-Data-0 <mcd><Msd>jms_text</Msd></mcd>

X-MQRFH2-Data-1 <jms><Dst>queue:///Q2</Dst><Tms>1164748514102</Tms></jms>

Legacy WebSphere MQ service objectsThe DataPower appliance includes the following WebSphere MQ-related servicesthat predate the Multi-Protocol Gateway:v WebSphere MQ Gatewayv WebSphere MQ Hostv WebSphere MQ Proxy

These objects should no longer be used for WebSphere MQ integration. TheMulti-Protocol Gateway and the Web Service Proxy provide all of the functionalitythat these legacy services offer.

Additionally, the appliance provides a number of legacy MQ service variables.Because these variables are not available to the Multi-Protocol Gateway or WebService Proxy, do not use these variables. For a list of these variables, see thesection on legacy MQ service variables in the IBM WebSphere DataPower SOAAppliances: Extension Elements and Functions Catalog.

Chapter 6. Additional configuration options 55

Appendix A. Referenced objects

Event-sink (event-sink) actionThe event-sink action does not employ an output context. To use the results froman asynchronous action in an event-sink action, you must configure any of thesubsequent actions to use the output context of the asynchronous action. Forexample, the processing rule can run a fetch action and a results action inparallel. Both of these actions are included in an event-sink action. Processingwaits until both actions complete successfully.

To add an event-sink action, use the following procedure:1. Drag the Advanced icon to the configuration path (the horizontal line).2. Double-click the Advanced icon to display a window that lists the advanced

action types.3. Click the Event-sink radio button.4. Click Next to display the Configure Event-sink window.5. Use the default value for the Input field. This context is not used in any way.6. Select the desired asynchronous action from the list of actions available in the

Action property. Only asynchronous actions are in this list. Asynchronousactions that were created during the configuration of a conditional or for-eachaction are not in this list and cannot be affected by an event-sink action. ClickAdd to add the action to the list of actions.

7. Repeat step 6 as many times as needed to include the desired asynchronousactions. The actions can be in any order.

8. Set the desired Timeout value. The default of 0 means that processing waitsindefinitely for the included actions to complete.


For a transform to use the data from a results action that follows the event-sinkaction, the transform must use the output context of the results action as its inputcontext. You can create a style sheet to access and combine all of the contexts thatare created by multiple asynchronous actions.

When the event-sink action includes actions that can reject the message, a rejectionby any of the included actions causes the message to be rejected as if the actionswere processed in sequence. When more than one such action rejects the message,any error rule that is in the policy has access to the detailed error messages thatwere generated for the last asynchronous action to complete only.



MQ Front Side HandlerAn MQ Front Side Handler object handles MQ protocol communications withDataPower services.

This handler is available on the following appliances only:v DataPower appliancev B2B Appliance XB60v Low Latency Appliance XM70

To configure an MQ Front Side Handler, use the following procedure:1. Select Objects → Protocol Handlers → MQ Front Side Handler to display the

MQ Front Side Handler catalog.2. Click Add to display the MQ Front Side Handler Configuration screen. Use

this screen to specify operational parameters.3. Specify the name of the object in the Name field.4. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.5. Specify a descriptive object-specific summary in the Comment field.6. Select a queue manager from the Queue Manager list.7. Specify the name of the GET queue in the Get Queue field.8. Specify the name of the PUT queue in the Put Queue field.9. Specify the Coded Character Set Identifier that the remote MQ queue manager

converts output data in the CCSI field. The default CCSI is for ISO-8859-1(latin-1). Refer to the IBM Code Pages on the Web for a list of CCSIidentifiers.This property is meaningful only when the MQ Queue Manager object has theConvert Input property set to on.

10. Specifies the cumulative value of the MQGET options that are applicable toan MQ message in decimal or hexadecimal format in the Get MessageOptions field. The value is passed directly to the MQ API. The default is 4097(decimal value for the MQGMO_WAIT and the MQGMO_SYNCPOINT_IF_PERSISTENToptions).Refer to the “MQGMO_* (Get Message Options)” topic in the “Constants”section of the WebSphere MQ Information Center for details.When a message is too large for a queue, an attempt to put the message onthe queue fails. Segmentation is a technique that allows the queue manager orapplication to split the message into smaller pieces, and place each segmenton a queue as a separate physical message. The application that retrieves themessage can either handle the multiple segments one-by-one, or request thequeue manager to reassemble the segments into a single message that isreturned by the MQGET call. The reassembly request is achieved byspecifying the MQGMO_COMPLETE_MSG option (65536) on the MQGET call, and byproviding a buffer large enough to accommodate the entire message.

Note: Ensure that the associated queue manager supports theMQGMO_COMPLETE_MSG option. On z/OS, MQ queue managers do notsupport segmentation. On other operating systems, MQ queuemanagers might not be configured to support segmentation.


11. Use the Exclude Message Headers check boxes to select which types of MQheaders after the MQMD to remove from the message. By default only the MQMDheader is parsed. The following headers after MQMD, when selected, can beremoved:v CICS Bridge Header (MQCIH)v Dead Letter Header (MQDLH)v IMS Information Header (MQIIH)v Rules and Formatting Header (MQRFH)v Rules and Formatting Header (MQRFH2)v Working Information Header (MQWIH)

12. Specify the number of concurrent MQ connections to allocate in the Thenumber of concurrent MQ connections field. The minimum is 1. The defaultis 1.

13. Specify the number of seconds before an MQGET operation returns if nomessages are available in the Polling Interval field. The next attempt will beperformed immediately. Setting a low value will help to detect quicklynetwork connectivity issues and queue manager power shutdown. At thesame time, a low value will increase network traffic. The minimum is 1. Thedefault is 30.

14. Select the MQ header structure from which to extract the Content-Type headerfrom the Header to Extract Content-Type list.

None (Default) No header

MQRFHMQRFH header

MQRFH2MQRFH2 header

15. If Header to Extract Content-Type is not None, specify the XPath expressionto extract the value of the Content-Type header in the XPath expression toextract Content-Type from MQ header field. Click XPath Tool for helpbuilding the XPath expression.

16. Use the Retrieve Backout Settings to determine whether to retrieve thebackout threshold and backout queue name from the MQ server.

on Retrieves backout settings from the MQ server and compares to thebackout values set in the MQ Queue Manager object. On retry, theDataPower appliance uses the higher priority backout settings fromthe MQ server. If MQ server does not contain backout settings, theappliance uses existing backout properties, either empty or populated,that are stored in the MQ Queue Manager object. If there are nobackout properties, backout is disabled.

off (Default) Do not retrieve backout settings from the MQ server. If theseproperties already exist in the MQ Queue Manager object, theappliance use those values.

17. Click Apply to save the object to the running configuration.18. Optionally, click Save Config to save the object to the startup configuration.

Appendix A. Referenced objects 59

MQ Queue ManagerIn WebSphere MQ, distributed send queues and receive queues are managed by aqueue manager. A queue manager provides messaging services in the followingways:v Periodically monitoring and polling queuesv Ensuring that sent messages are directed to the correct receive queue or are

routed to another queue manager

Identifying the MQ serverThe host for an MQ queue manager is the MQ server where the queue manager isrunning. The value for the Host Name field includes the listening port on theserver. If you do not specify the port, the default is 1414.

The value of the host depends on IP family.

For IPv4The value for the Host Name field can be in one of the following formats:v address:port — For example, 10.10.1.2:1414v address(port) — For example, 10.10.1.2(1414)v address — For example, 10.10.1.2v host-name:port — For example, server1:1414v host-name(port) — For example, server1(1414)v host-name — For example, server1

For IPv6The value for the Host Name field can be in one of the following formats:v [address]:port — For example, [2202::148:248]:1414v address(port) — For example, 2202::148:248(1414)v address — For example, 2202::148:248v host-name:port — For example, server1:1414v host-name(port) — For example, server1(1414)v host-name — For example, server1

Securing communication with remote queue managersBefore configuring an MQ Queue Manager object, determine whether to supportsecure communication with the remote queue manager. For secure communication,you can either use an SSL artifacts that were created with IBM Global Security Kit(GSKit) or use an SSL Proxy Profile. If you define both methods, the DataPowerappliance uses the selected SSL Proxy Profile.

Note: To integrate with a MQ for z/OS, you must use an instance of the SSLProxy Profile object.

Securing with GSKitTo define secure communication with artifacts from GSKit, use the following steps:1. Select the location of the key database file with the SSL Key Repository

controls.The key database file contains the required keys and certificates. Each keydatabase file has an associated stash file. The stash file holds encryptedpasswords that allow programmatic access to the key database. The stash filemust reside in the same directory as the key database file, must have the same


file stem, and must end with the sth file extension. For example, if the keydatabase file is MQkeys.pem or MQkeys.kdb, the stash file must be MQkeys.sth.If these files are not on the appliance, upload or fetch them.

2. Select the cipher suite from the SSL Cipher Specification list.

Securing with an SSL Proxy Profile objectTo define secure communication with an SSL Proxy Profile, select an SSL ProxyProfile from the SSL Proxy Profile list. Table 5 maps the relationship between theSSL Cipher Specification property and setting required on the Crypto Profile ofthe SSL Proxy Profile that is assigned to the MQ Queue Manager. Use thisinformation when configuring the SSL Proxy Profile to communicate with the MQQueue Manager.

Table 5. Mapping of the SSL Cipher setting the Crypto Profile settings

SSL Cipher Specification setting Crypto Profile settings

NULL_MD5 Cipher: NULL-MD5Options: OpenSSL-default+Disable-TLSv1

NULL_SHA Cipher: NULL-SHAOptions: OpenSSL-default+Disable-TLSv1

RC4_MD5_EXPORT Cipher: EXP-RC4-MD5Options: OpenSSL-default+Disable-TLSv1

RC4_MD5_US Cipher: RC4-MD5Options: OpenSSL-default+Disable-TLSv1

RC4_SHA_US Cipher: RC4-SHAOptions: OpenSSL-default+Disable-TLSv1

RC2_MD5_EXPORT Cipher: EXP-RC2-CBC-MD5Options: OpenSSL-default+Disable-TLSv1

DES_SHA_EXPORT Cipher: DES-CBC-SHAOptions: OpenSSL-default+Disable-TLSv1

RC4_56_SHA_EXPORT1024 Cipher: EX1024-RC4-SHAOptions: OpenSSL-default+Disable-TLSv1

DES_SHA_EXPORT1024 Cipher: EXP1024-DES-CBC-SHAOptions: OpenSSL-default+Disable-TLSv1

TRIPLE_DES_SHA_US Cipher: DES-CBC3-SHAOptions: OpenSSL-default+Disable-TLSv1

TLS_RSA_WITH_AES_128_CBC_SHA Cipher: AES128-SHAOptions: OpenSSL-default

TLS_RSA_WITH_AES_256_CBC_SHA Cipher: AES256-SHAOptions: OpenSSL-default

AES_SHA_US Cipher: AES128-SHAOptions: OpenSSL-default

Defining the timeout for dynamic connectionsThe Cache Timeout property defines the number of seconds that the applianceretains (keeps alive) a dynamic connection in the connection cache. This timeoutvalue must be greater than the negotiated heartbeat interval but less than the keepalive interval.v The negotiated heartbeat interval is between the appliance and the backend MQ

server. This interval uses the value of the Channel Heartbeat property to definethe starting value for the negotiation.

v The keep alive (timeout) interval is on the remote MQ server. The KAINTattribute on the MQ server defines the timeout value for a channel.


Not all channels have an explicit keep alive interval on the MQ server. Somequeue managers use an automatic timeout setting (the KAINT attribute set toAUTO). In these cases, the keep alive interval is the negotiated heartbeat intervalplus 60 seconds.

When an inactive connection reaches this threshold, the appliance removes thatdynamic connection from the cache. When the cache no longer contains dynamicconnections, the appliance deletes the dynamic queue manager. Without a dynamicqueue manager, there is no connection with the remote MQ server.

Note: The timeout value for the Cache Timeout property is the only way toconfigure a timeout value from the appliance to the MQ server. No otherconfiguration setting on the appliance can time out an MQ connection.

Enable units of workThe appliance supports only local units of work, not global units of work betweenthe appliance and the remote MQ queue manager. When using synch points, thesame queue manager must maintain the request queue and the reply queue.

A transaction (unit of work) can consist of one or more MQ messages. Some MQsystems require synchronization on each unit of work. In other words, the systemcommits the entire transaction or rolls back the entire transaction. This type ofsynchronization ensures that the remote system and the application with which itinteracts remain in synch.

To use unit of work:1. Set the Units of Work field to 1. This value indicates that the queue manager

uses synch points. A synch point commits or rolls back each MQ message, notthe entire transaction. When specified, the appliance does not remove themessage that it gets from a queue until it completes its transaction using thatmessage (such as placing the message on a server queue for processing). If thetransaction fails and the message is left available on the queue, the appliancecan attempt to get the message and process it again.If not enable, undeliverable messages are discarded. Higher level protocols areresponsible for detecting and for retransmitting any undeliverable messagewithin the transaction.

2. Set the Automatic Backout toggle to on. This value enables the automaticbackout of poison messages. A poison message is any message that the receivingapplication does not know how to process. Usually an application rolls backthe GET of this message, which leaves the message on the input queue.However, the backout count (MQMD.Backoutcount) is increased. As the MQQueue Manager object continues to “re-get” the message, the backout countcontinues to increase. When the backout count exceeds the backout threshold,the MQ Queue Manager object moves the message to the backout queue.If not enabled, the poison message must be programmatically rerouted by acustom style sheet in the request rule.

3. Specify the number of reprocessing attempt per message in the BackoutThreshold field. Use an integer greater than 1 to specify the maximum numberof reprocessing attempts per message. The default is 1. The count starts at 0,which accounts for the initial processing attempt. The default value specifiestwo attempts: the initial attempt and a single reprocessing attempt.

4. Specify the name of the backout queue in the Backout Queue Name field. Thebackout queue contains messages that cannot be processed or delivered.


Typically, the name of the queue is SYSTEM.DEAD.LETTER.QUEUE. Messages thathave exceeded the backout threshold are rerouted to this queue.

Configuring Queue Manager objectsTo configure queue managers, that is to make the DataPower appliance aware ofthe location of remote queue managers, use the following procedure:1. Select Objects → Network → MQ Queue Manager to display the MQ Queue

Manager catalog.2. Click Add to display the MQ Queue Manager configuration screen.3. Specify the name of the object in the Name field.4. Retain the default setting for the Admin State toggle. To place the object in an

inactive administrative state, click disabled.5. Specify a descriptive object-specific summary in the Comment field.6. Specify the host name or IP address and port of the MQ server in the Host

Name field. If not specified, the default port is 1414.7. Optionally specify the name of the queue manager in the Queue Manager

Name field. Use this property when the name of a nondefault queue manageris assigned to this queue manager.

8. Optionally specify the name of the channel in the Channel Name field. Usethis property as an alternative to the default SYSTEM.DEF.SVRCONN.

9. Specify the approximate time in seconds between heartbeat flows on a channelwhen waiting for a message on a queue in the Channel Heartbeat field. Usean integer in the range of 0 through 999999. The default is 300.If 0, no heartbeat flow is exchanged when waiting for a message on thechannel. This setting does not set the heartbeat on the channel. This settingnegotiates the heartbeat value with the channel. The greater of the two valuesis used.

10. Optionally specify a plaintext string that identifies this client to the MQ serverin the User Name field.

11. Optionally specify the size in bytes of the largest message to process in theMaximum Message Size field. Use a value that is equal to or greater than theMaxMsgLength attribute of the channel and of the queue on the MQ server.Use an integer in the range of 1024 through 1073741824. The default is1048576.

12. Specify the number of seconds that the appliance retains a dynamicconnection in the connection cache in the Cache Timeout field. Use a valuethat is greater than the negotiated heartbeat interval but less than the keepalive interval.

13. Determine whether to support transactions (units of work) with roll backsupport.a. In the Units of Work field, indicate whether to support transactions.b. Use the Automatic Backout toggle to enable the automatic backout of

poison messages.c. In the Backout Threshold field, specify the number of reprocessing

attempt per message.d. In the Backout Queue Name field, specify the name of the backout queue.

14. Optionally define open connection behavior.a. Specify the total number of open connections to allow in the Total

Connection Limit field. Use an integer in the range of 1 through 5000. Thedefault is 250.


b. Specify the number of connections to open immediately when the queuemanager starts in the Initial Connections field. Use an integer in the rangeof 0 through 5000. The default is 1.

15. Determine whether to support secure communication with the remote queuemanager.v To secure with artifacts from GSKit:

a. Select the location of the key database file with the SSL Key Repositorycontrols.

b. Select the cipher suite from the SSL Cipher Specification list.v To secure with an SSL Proxy Profile object, select the instance from the SSL

Proxy Profile list.16. Use the Convert Input toggle to indicate whether the queue manager can

convert input messages to a different CCSI (Coded Character Set Identifier)than the one in the original message. This conversion is done by the remotequeue manager, not the DataPower appliance.The output CCSI is specified on the MQ Front Side Handler.

on (Default) Enables CCSI conversion.

off Disable CCSI conversion. If MQ error 2210 is encountered, use thissetting.

17. Define the retry behavior.a. Use the Automatic Retry toggle to define whether to attempt to reconnect

to the remote queue manager.

on Enables automatic retry. When enabled, the DataPower applianceautomatically attempts to reconnect to the remote queue managerat every defined interval.

off (Default) Disables automatic retry.b. When automatic retry is enabled, specify the number of seconds between

automatic retry attempts in the Retry Interval field. The minimum is 1.The default is 1.

Note: This setting does not affect attempts to PUT or GET messages overestablished, active connections.

c. When automatic retry is enabled, specify the number of seconds betweenthe creation of log messages at the error level when failed connections areretried in the Reporting Interval field. This setting filters the generation ofidentical error messages to MQ logging target. When set to 0, only debuglevel messages are sent. The default is 1.

18. Use the Alternate User toggle to determine whether to useMQOD.AlternateUserId during MQOPEN operations and during MQPUToperations.

on (Default) The MQ operation uses the value for MQOD.AlternateUserId

off The MQ operation uses the value for MQMD.UserIdentifier

19. Specify the local address for outbound connections in the Local Address field.Supported formats are 1.1.1.1 or 1.1.1.1(1) or (1) to tell TCP to bind toport 1 and for a range of ports use (1,10) or 1.1.1.1(1,10). If the port is set,the range must be greater than the total number of allowed connections.

20. Select an XML Manager from the XML Manager list.21. Optionally define the CCSID to present to the remote queue manager on

connection.


a. Click the Advanced tab.b. Specify the CCSID to present to the queue manager when the DataPower

appliance connects to it in the Character Code Set ID field. This settinghas the same effect as setting the MQCCSID environment variable for an MQclient. The default is 819. Refer to the WebSphere MQ Information Centerfor more information.

22. Click Apply to save the object to the running configuration.23. Optionally, click Save Config to save the object to the startup configuration.

MQ Queue Manager GroupAn instance of the MQ Queue Manager Group object implements a failoverconfiguration. These objects provide connection redundancy in the event of acritical queue manager or bus error that results in a loss of connectivity betweenclients and remote queue managers.

An MQ Queue Manager Group object defines one primary queue manager andone or more backup queue managers. The appliance periodically monitors thestatus of the primary queue manager. In the event of failure, the appliance selects abackup queue manager to assume the role of the primary queue manager. Whenthe original primary queue manager returns to service, the appliance reassigns thisqueue manager to its former role.

For information about creating MQ Queue Manager objects, refer to “MQ QueueManager” on page 60.

Configuring MQ Queue Manager Group objectsTo configure an MQ Queue Manager Group object:1. Select Objects → Network Settings → MQ Queue Manager Group to display

the catalog.2. Click Add to display the configuration screen.3. Define the configuration. For information about the values to specify in the

available fields, refer to the online help.4. Click Apply to save the object to the running configuration.5. Optionally, click Save Config to save the object to the startup configuration.


Appendix B. Getting help and technical assistance

This section describes the following options for obtaining support for IBMproducts:v “Searching knowledge bases”v “Getting a fix”v “Contacting IBM Support” on page 68

Searching knowledge basesIf you encounter a problem, you want it resolved quickly. You can search theavailable knowledge bases to determine whether the resolution to your problemwas already encountered and is already documented.

DocumentationThe IBM WebSphere DataPower documentation library provides extensivedocumentation in Portable Document Format (PDF). You can use thesearch function of Adobe® Acrobat to query information. If you downloadand store the documents in a single location, you can use the search facilityto find all references across the documentation set.

IBM SupportIf you cannot find an answer in the documentation, use the Search Supportfeature from the product-specific support page.

From the Search Support (this product) area of the product-specificsupport page, you can search the following IBM resources:v IBM technote databasev IBM downloadsv IBM Redbooks®

v IBM developerWorks®

Getting a fixA product fix might be available to resolve your problem. To determine what fixesare available for your IBM product, check the product support site by performingthe following steps:1. Go to the IBM Support site at the following Web address:

http://www.ibm.com/support2. Select Support & Downloads → Download to open the Support & downloads

page.3. From the Category list, select WebSphere.4. From the Sub-Category list, select WebSphere DataPower SOA Appliances.5. Click the GO icon to display the list of most recent updates.6. Click the link for the firmware and documentation download that is specific to

your WebSphere DataPower product.7. Follow the instructions in the technote to download the fix.


http://www.ibm.com/support

Contacting IBM SupportIBM Support provides assistance with product defects. Before contacting IBMSupport, the following criteria must be met:v Your company has an active maintenance contract.v You are authorized to submit problems.

To contact IBM Support with a problem, use the following procedure:1. Define the problem, gather background information, and determine the severity

of the problem. For help, refer to the Software Support Handbook. To access theonline version of this handbook, use the following procedure:a. Access the IBM Software Support Web page at the following Web address:

http://www.ibm.com/software/supportb. Scroll down to the Additional support links section of the page.c. Under Support tools, click the Software Support Handbook link.d. Bookmark this page for future reference.From this page, you can obtain a PDF copy of the handbook.

2. Gather diagnostic information.a. Access the product support at the following Web address:

http://www.ibm.com/software/integration/datapower/supportb. Locate the Assistance area of the product support page.c. Click Information to include to access that technote that lists the

information that is required to report a problem.3. Submit the problem in one of the following ways:

OnlineFrom the IBM Support Web site (http://www.ibm.com/support), selectSupport & Downloads → Open a service request. Following theinstructions.

By phoneFor the phone number to call in your country, refer to “Contacts” in theSoftware Support Handbook. From the Software Support Handbook Website, click Contacts. In the U.S. and Canada, call 1–800–IBM-SERV(1–800–426–7378) and select option 2 for software.

If the problem you should submit is for a software defect or for missing orinaccurate documentation, IBM Support creates an authorized program analysisreport (APAR). The APAR describes the problem in detail. Whenever possible, IBMSupport provides a workaround that you can implement until the APAR isresolved and a fix is delivered.


http://www.ibm.com/software/support

http://www.ibm.com/software/integration/datapower/support

http://www.ibm.com/support

Notices and trademarks

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information about theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law: INTERNATIONALBUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS”WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OFNON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULARPURPOSE. Some states do not allow disclaimer of express or implied warranties incertain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvements orchanges in the product(s) or the program(s) described in this publication at anytime without notice.

TrademarksIBM, the IBM logo, CICS, developerWorks, DB2, DataPower, IMS, RACF,Redbooks, Tivoli, WebSphere, and z/OS are registered trademarks of theInternational Business Machines Corporation in the United States or othercountries.

Adobe, the Adobe logo, PostScript, and the PostScript logo are either registeredtrademarks or trademarks of Adobe Systems Incorporated in the United States,and/or other countries.

Microsoft and Windows are trademarks of Microsoft Corporation in the UnitedStates, other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the United States and other countries.


Other company, product, and service names may be trademarks or service marksof others.


��

Printed in USA

WebSphere DataPower SOAAppliances · 4/24/2009 · Preface IBM ®WebSphere DataPower SOA...

Documents

Transcript of WebSphere DataPower SOAAppliances · 4/24/2009 · Preface IBM ®WebSphere DataPower SOA...