Data Power Integrating With Mq

DataPower SOA AppliancesVersion 3.8.1

Integrating with WebSphere MQ

��

DataPower SOA AppliancesVersion 3.8.1

Integrating with WebSphere MQ

��

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

First Edition (June 2010)

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

© Copyright IBM Corporation 2006, 2010.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Preface . . . . . . . . . . . . . . . vIntended audience . . . . . . . . . . . . vFile naming guidelines . . . . . . . . . . . vObject naming guidelines . . . . . . . . . . vTypeface conventions . . . . . . . . . . . vi

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 . . . . . . . . . . . . 5

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

Chapter 2. Routing . . . . . . . . . . 9Back-side request routing . . . . . . . . . . 9Back-side destinations . . . . . . . . . . . 9Using an MQ URL to set back-side destinations . . 10

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

Front Side reply routing . . . . . . . . . . 16

Chapter 3. MQ header values . . . . . 19Injecting and suppressing headers . . . . . . . 19MQ header action . . . . . . . . . . . . 20

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

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

WebSphere MQ API support. . . . . . . . . 33

Chapter 4. Units of Work . . . . . . . 35WebSphere MQ client Units of Work capabilities . . 35Units of work implementation . . . . . . . . 36Transactions 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 . . 51Datagram traffic with Units of Work enabled . . 51Datagram traffic with custom error handling . . 52Request and reply traffic . . . . . . . . . 52

Chapter 6. Additional configurationoptions . . . . . . . . . . . . . . 53Asynchronous put operations . . . . . . . . 53Authentication and authorization . . . . . . . 53Batch request processing . . . . . . . . . . 54Message Properties . . . . . . . . . . . . 54

Enabling parsing for message properties. . . . 54Filtering messages by properties . . . . . . 55Manipulating message properties in theprocessing policy . . . . . . . . . . . 55

Monitoring, logging, and status. . . . . . . . 56Ordered messaging . . . . . . . . . . . . 56Publish and subscribe using topic strings . . . . 57

Publish topic strings . . . . . . . . . . 57Subscribe to topic strings . . . . . . . . . 58Subscribe to topic strings using wildcards . . . 59

Using MQ with a Web Service Proxy . . . . . . 59MQ and JMS . . . . . . . . . . . . . . 60Legacy WebSphere MQ service objects . . . . . 61

Appendix. Referenced objects . . . . 63Configuring a WebSphere MQ handler . . . . . 63

High-level configuration . . . . . . . . . 63Defining the basic configuration . . . . . . 63Defining the publish and subscribe configuration 65

© Copyright IBM Corp. 2006, 2010 iii

Defining the properties and headersconfiguration . . . . . . . . . . . . . 65Defining the advanced configuration . . . . . 66

MQ Queue Manager . . . . . . . . . . . 66Identifying the MQ server . . . . . . . . 66Securing communication with remote queuemanagers . . . . . . . . . . . . . . 67Defining the timeout for dynamic connections . . 68Enabling units of work . . . . . . . . . 68Configuring Queue Manager objects . . . . . 69

MQ Queue Manager Group . . . . . . . . . 72Working with the multi-instance feature in theWebSphere MQ server . . . . . . . . . . 72Configuring MQ Queue Manager Group objects 73

Notices and trademarks . . . . . . . 75Trademarks . . . . . . . . . . . . . . 75

Index . . . . . . . . . . . . . . . 77

iv 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.

Intended audienceThis 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

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 when specifying the name for an object:v a through z

v A through Z

v 0 through 9

v _ (underscore)v - (dash)

© Copyright IBM Corp. 2006, 2010 v

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.

vi 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 athttp://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 to define the architecture. See “DataPower service” on page

2.v An MQ handler to define a WebSphere MQ system as the front side. See “MQ

Front Side Handler object” on page 2.v An MQ Queue Manager object to define the communication between a service

and a WebSphere MQ queue manager. See “MQ Queue Manager object” on page2.

© Copyright IBM Corp. 2006, 2010 1

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

Note: In this document, the DataPower object is referred to as the “MQ QueueManager object.” The WebSphere MQ queue manager is referred to as the“WebSphere MQ queue manager” or simply the “queue manager”.

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

Queue Manager Group” on page 3.

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

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

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

See “Injecting and suppressing headers” on page 19 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“Configuring a WebSphere MQ handler” on page 63 for how to configure an MQFront Side Handler object. The following properties are defined as part of the MQFront Side Handler object.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.

v Use Queue Manager in URL field to determine whether the value of thevar://service/URL-in variable returns the name of the MQ Queue Manager orthe name of the MQ Queue Manager Group.

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 66 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.

2 DataPower SOA Appliances: Integrating with WebSphere MQ

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.

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 20 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 72 for information about how toconfigure the primary and backup MQ Queue Manager objects.

In WebSphere MQ server Version 7.0.1 or later, you can configure multi-instancequeue managers for the failover in the WebSphere MQ server. In the DataPowerappliance, you can configure the MQ Queue Manager Group object to work withthe multi-instance feature for the failover. See “Working with the multi-instancefeature in the WebSphere MQ server” on page 72 for more information.

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 the

Chapter 1. Introduction 3

|||||

appliance as well as the configuration of the MQ Queue Manager to which theservice connects and exchanges messages.

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.

Figure 1. Basic architecture for HTTP to MQ messaging

Figure 2. Basic architecture for MQ to HTTP messaging


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 messageworkflow 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, the service will cancel thetransaction and start error handling. See Chapter 5, “Error handling,” on page45 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 action, or by using the set-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 message forlater 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 Process


Backend 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 24 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 specified. The following sections describe these methods.v “Back-side request routing”

Provides information about what parts of an input message are used todetermine where the message should be routed.

v “Back-side destinations”Provides information about what method to use to set the destination.

v “Using an MQ URL to set back-side destinations” on page 10Provides information about setting a static or a dynamic MQ URL.

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 19for more information. Note that you can inspect the headers presented byother request protocols, such as HTTP or JMS, in similar fashion.

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. Forexample, 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 an 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 minimally must contain a request queue,a publish topic string, or a reply queue name. The URL can contain both arequest queue and a reply queue name. However, if a reply queue and apublish topic string are specified, the last one entered is used and the otherparameter is ignored.

ReplyQueue=replyQueueNameSpecifies the name of the back-end WebSphere MQ reply queue that theservice polls for responses. The URL minimally must contain a requestqueue, a publish topic string, or a reply queue name. The URL can containboth a request queue and a reply queue name.

queryParametersSpecifies optional and required query parameters for static and dynamicURLs.

AsyncPut={true|false}Specifies whether to put a message to a queue without waiting for aresponse from the queue manager.

true Specifies that the put operation is asynchronous.

false (Default) Specifies that the put operation is synchronous.

For additional information, see “Asynchronous put operations” onpage 53.

Browse={first|next|current}Browses (retrieve without removing) messages from the queue that isspecified in the ReplyQueue parameter. Use one of the followingvalues:

first Browses the first message on the queue.

next Browses the messages on the queue in incremental order. Forexample, if you specify next after browsing message one, theurl-open browses message two. Specifying next on the firsturl-open attempt browses the first message on the queue.

currentBrowses the message on the queue that the url-open justread. For example, if you specify current and the previousbrowse result is message one, the url-open browses messageone.

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.

Chapter 2. Routing 11

||||

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.

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.

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

ParseProperties={on|off}Specifies whether to parse the properties of the incoming messagefrom a queue or from a subscription. The ParseProperties parameterapplies to the ReplyQueue or the SubscribeTopicString.

on Specifies that parsing is enabled. The WebSphere MQ serverreturns the messages with the properties.

off (Default) Specifies that parsing is disabled. The DataPowerappliance does not request the properties with the messagewhen issuing an MQGET call, and the WebSphere MQ serverreturns the messages without the properties.

For additional information, see “Message Properties” on page 54.

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.

PublishTopicString=string

Specifies a topic string associated with the identified queue manager.If a ReplyQueue and a PublishTopicString are specified, the last oneentered is used and the other parameter is ignored.

For additional information, see “Publish topic strings” on page 57.

Selector=expression


Specifies a variable length string containing a SQL92 query that filtersmessages based on the message properties. The Selector applies tothe ReplyQueue or the SubscribeTopicString.

For additional information, see “Message Properties” on page 54.

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

SubscribeTopicString=string

Specifies a topic string associated with the identified queue manager.If a ReplyQueue and a SubscribeTopicString are specified, the lastone entered is used and the other parameter is ignored.

For additional information, see “Subscribe to topic strings” on page58.

SubscriptionName=string

Specifies a name for the subscription. The presence of this parametermakes the subscription a durable subscription.

For additional information on durable subscriptions, see “Subscribe totopic strings” on page 58.

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=queueManager;UserName=userName;Channel=channelName;ChannelTimeout=channelTimeout;channelLimit=channelLimit;Size=maxMsgSize;MQCSPUserId=MQCSPUserID;MQCSPPassword=MQCSPPassword;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=queueManagerSpecifies the name of a WebSphere MQ queue manager on the targetWebSphere MQ server.

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

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 longercontains 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 any valueof 2 - 5000.

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

MQCSPUserId=MQCSPUserIdSpecifies the user ID value of the MQCSP connection security parameterwhen MQCSP structure is used for authorization service.

MQCSPPassword=MQCSPPasswordSpecifies the password value of the MQCSP connection security parameterwhen MQCSP structure is used for authorization service.

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 Injection


|||

|||

configuration method, or extension function, changing the header name toReplyToQM and the value to the desired queue manager name. Note that the queuemanager name must match the name of a configured MQ Queue Manager objecton the appliance which in turn connects to the desired remote WebSphere MQqueue 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 24.



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 20 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 16 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:1. Drag the Advanced icon to the configuration path (the horizontal line).2. Double-click the Advanced icon.3. Click the MQ Header radio button.4. Click Next.5. Optional: Specify the input context. If auto, processing inserts the correct

context identifier.6. Set Asynchronous to indicate whether to process asynchronously. If enabled,

the action does not need to complete before the rule starts processing its nextaction.

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

headers in the request message:10. Specify an override value for 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. If auto, processing inserts the output context.12. Click Done.

If this is the last action for the rule, click Apply Policy. Otherwise, drag anothericon to the configuration path.

Retrieving responses by message ID or by correlation IDTo retrieve response messages from the backend reply queue:1. Drag the Advanced icon to the configuration path (the horizontal line).2. Double-click the Advanced icon.3. Click the MQ Header radio button.4. Click Next.5. Optional: Specify the input context. If auto, processing inserts the correct



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

v In the Message Id field, specify the message ID. The service pulls messagesfrom the backend reply queue with the specified message ID.

v In the Correlation Id field, specify the correlation ID. The service pullsmessages from the backend reply queue with the specified correlation ID.

10. Select an output context. If auto, processing inserts the output context.

Chapter 3. MQ header values 21

11. Click Done.


Modifying MQMD response headersTo modify MQMD header values for response messages placed to the backendreply queue:1. Drag the Advanced icon to the configuration path (the horizontal line).2. Double-click the Advanced icon.3. Click the MQ Header radio button.4. Click Next.5. Optional: Specify the input context. If auto, processing inserts the correct



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

headers in the response message.10. Specify an override value for 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. If auto, processing inserts the output context.12. Click Done.


Modifying the reply queue for responsesTo change the destination reply queue for response messages:1. Drag the Advanced icon to the configuration path (the horizontal line).2. Double-click the Advanced icon.3. Click the MQ Header radio button.4. Click Next.5. Optional: Specify the input context. If auto, processing inserts the correct



7. Select response as the MQ Processing Type.8. Select ReplyToQ from the MQ Response Header Processing list.


9. From the ReplyToQ Processing Type list, select the processing method for theresponse message.

10. Optional: In the ReplyToQMgr field, specify a value.11. Select an output context. If auto, processing inserts the output context.12. Click Done.


Modifying the queue manager for responsesTo change the destination MQ Queue Manager for response messages:1. Drag the Advanced icon to the configuration path (the horizontal line).2. Double-click the Advanced icon.3. Click the MQ Header radio button.4. Click Next.5. Optional: Specify the input context. If auto, processing inserts the correct



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

the response message.10. Optional: In the ReplyToQMgr field, specify a value.11. Select an output context. If auto, processing inserts the output context.12. Click Done.


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)” on page 24v “IMS Information Header (MQIIH)” on page 27v “CICS Bridge Header (MQCIH)” on page 28v “Object descriptor header (MQOD)” on page 29


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 outstandingMessageID values 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 specifiedby 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 theUserIdentifier 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 a


Request 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. This value specifies the use of theCICS 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 Queue

Manager 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 on page 30 illustrates the WebSphere MQ architecture used in thisexample. The routing infrastructure is comprised of multiple interactions of localand remote queues that use the MQ headers MQMD and MQOD to implement theMQ routing 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.

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 the servicecreates and injects an MQOD header with that information, and puts the messageto an alias of the clustered queue on the local queue manager (QM_A). Next, theservice reads the reply using a local queue (QA.LOOPBACK.REPLY), and finally repliesto a remote queue (QB.REPLY) on a clustered queue manager (QM_B) by usinganother 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.

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


v Demonstrates custom error handling, such as sending an error reply as opposedto 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 anMQ 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.

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.ConnectionName


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

v 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 “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.

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.

If the backend transactionality is also turned on by appending theTransactional=true and Sync=true parameters to the backend URL, the responsemessages will be under backend unit of work and the response will not becommitted until it is successfully delivered to the frontside reply queue. Thus, theresponse will not be lost in this kind of configuration.

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, the service cancels thetransaction and starts error handling (such as running a configured Error rule). Theservice also starts the automatic retry mechanism as determined by the AutomaticRetry property of the MQ Queue Manager object. When the Automatic Retryproperty is set to on, the DataPower service attempts to reconnect to the remotehost. 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. The number of retry attempts is determined by the Retry Intervalproperty of the MQ Queue Manager object.

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 72 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 anXML 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-ofselect="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-variable name="’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-ofselect="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 29.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 variableaction 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-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:if></xsl:if><error>

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


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 action or using the dp:set-variable extensionelement. The Set variable action might be followed by a Transform action oractions 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

This chapter contains information about additional configuration options.

Asynchronous put operationsUsing an asynchronous put operation, an application can put a message to a queuewithout waiting for a response from the queue manager. You can use this toimprove messaging performance in some situations.

Normally, when an application puts a message or messages on a queue, theapplication waits for the queue manager to confirm that it has processed the MQIrequest. If high qualities of service are not required, you can improve messagingperformance, particularly for applications that put large numbers of smallmessages to a queue in a DataPower transaction, by choosing instead to putmessages asynchronously.

For the applications that require verification of delivery at the time of each putoperation, users should choose to put the message synchronously to a queue.Then, all MQPUT calls wait for a response to be returned from the queue manager.This is the default behavior.

For "fire-and-forget" applications, you can choose to put the messagesasynchronously to a queue for better performance. When an application puts amessage asynchronously, the following statements apply:v MQPUT calls do not wait for a response to return from the queue manager.v The queue manager does not return the success or failure of each call.

The errors will be checked later through a call to MQSTAT when a transaction in aDataPower service with an MQ front side handler is about to complete. If anyerror in any previous asynchronous call is found, a transaction in a DataPowerservice with an MQ Front-side handler will be rolled back in a transactionalcontext.

The DataPower appliance supports asynchronous put operations when thebackend server is WebSphere MQ V7.

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 must


then 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.

Batch request processingIn batch request processing, the MQ Front Side Handler gets request messages of aspecified batch size from the request queue and process the requests in one batch.No separate commit or rollback is performed for each message. When all requestsare processed, all requests in the batch will be committed. If any one of therequests fails, the batch is rolled back together.

The batch size for batch request processing is configured in the MQ Front SideHandler object. The default is 0, meaning batch processing disabled. Whenbatching is off, the MQ Front Side Handler gets the request, completes processing,and commits each request separately.

Only enable batch request processing when using the same MQ Queue Managersin the front-side handler and as on the backend. Otherwise, you might getduplicate messages in the backend queue. For example, if batch processing is onwhen the MQ Queue Manager in the front-side handler and in backend aredifferent and if a Multi-Protocol Gateway transaction fails, the MQBACK andMQCMIT calls are respectively issued to the MQ Queue Managers in the front-sidehandler and in the backend. The request in the front-side handler gets rolled backand the Multi-Protocol Gateway transaction restarts. When the secondMulti-Protocol Gateway transaction is completed, the message will be committedinto the backend queue again.

Message PropertiesWebSphere MQ V6 messages have two parts, namely the message descriptor orheaders and the message data or payload. The message descriptor is a fixed set ofheaders. The WebSphere MQ server processes the headers only, not the messagedata. You can only add the customized information in the message payload, not inthe headers.

WebSphere MQ V7 introduces another component into the messages. In addition tothe fixed descriptor and the message data, there is a Properties component. Aproperty is a named piece of data in name-value pair format. A property is nottreated as part of the message payload. The namespace for the property name ishierarchical and splits the name into components by dots, for example car.weight.

The DataPower appliance supports the processing of message properties when thebackend server is WebSphere MQ V7. The feature provides the following support:v “Enabling parsing for message properties”v “Filtering messages by properties” on page 55v “Manipulating message properties in the processing policy” on page 55

Enabling parsing for message propertiesYou can enable or disable parsing the properties of the incoming messages from aqueue or subscription. If parsing is enabled, the server returns the messages with


their properties. If parsing is disabled, the DataPower appliance does not requestthe properties with the message when issuing an MQGET call, and the WebSphereMQ Server returns the messages without properties.

Enable message properties parsing for the MQ Front Side Handler object with theWebGUI, the command line, or with the ParseProperties query parameter of theurl-open extension element.

Filtering messages by propertiesYou can filter the incoming messages by the properties by specifying a selectionstring. The selection string filters the messages delivered to the DataPowerappliance from a queue or a subscription.

A selector is a variable-length string containing a SQL92 query. The selection isbased on the message properties, not the payload. For example, a message selector“sport = 'football'” will limit messages to those that have a message propertynamed “sport” with a value “football”.

The property values have specific data types. The following data types are thesupported types: boolean, byte string, string, float32, float64, integer8, integer16,integer32, and integer64.

Specify the SQL92 query filter for the MQ Front Side Handler object with theWebGUI, the command line, or with the Selector query parameter of the url-openextension element.

Manipulating message properties in the processing policyMessage properties display in the probe and can be manipulated in custom stylesheets.

When the probe is turned on, use the MQMP tab to display the messageproperties.

You can add, update, and delete message properties using a custom stylesheet in aBinary Transform (xformbin) action. The following stylesheet appends fourproperties to the incoming requests. The properties are of type string, integer (32bit), boolean, and binary string respectively.<?xml version="1.0" encoding="UTF-8"?><xsl:stylesheet version="1.0">

<xsl:output method="xml" encoding="UTF-8"/>

<xsl:template match="/"><xsl:variable name="newMQMP">

<MQMP><Property name="car.color" type="string">red</Property><Property name="car.year" type="int32">1997</Property><Property name="car.domestic" type="boolean">TRUE</Property><Property name="car.code" type="hexstr">4142434445</Property>

</MQMP></xsl:variable>

<xsl:variable name="result-mqmp"><dp:serialize select="$newMQMP" omit-xml-decl="yes"/>

</xsl:variable>

Chapter 6. Additional configuration options 55

<dp:set-request-header name="’MQMP’" value="$result-mqmp"/><xsl:copy-of select="."/>


Note the following points when you specify the name, type, and value for aproperty:v Each <Property> element in the <MQMP> header represents a message property.

Use the name and type attributes to specify the property name and typerespectively. Enclose the property value with the <Property> and </Property>tags.

v The DataPower appliance supports the following data types for the typeattribute: boolean, byte string, string, float32, float64, integer8, integer16,integer32, and integer64 types. Specify the type attribute with the followingliterals: boolean, hexstr, string, float32, float64, int8, int16, int32, and int64.

v The default type of the property value is string. If the type attribute is notspecified, the appliance treats the given property as string type.

v The boolean literals are TRUE and FALSE.v For the properties of byte string (type = “hexstr”), the value should be in

hexadecimal. For example, the value of car.code will be saved as ABCDE whenthe property is specified with the following byte string:<car.code type="hexstr">4142434445</car.code>

The hex string “41 42 43 44 45” is “65 66 67 68 69” in decimal. The bytes 65, 66,67, 68, and 69 are “A”, “B”, “C”, “D”, and “E” respectively.

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, see Message Processing Modes in the reference objectssection of the IBM WebSphere DataPower Integration Appliance XI50: Multi-ProtocolGateway Developers Guide.

Publish and subscribe using topic stringsPublish and subscribe messaging allows users to decouple the provider ofinformation from the consumers of that information. The sending application andreceiving application do not need to know anything about each other for theinformation to be sent and received.

A typical publish and subscribe system has more than one publisher and morethan one subscriber. The provider of information is called a publisher. Publisherssupply information about a subject, without needing to know anything about theapplications that are interested in that information. Publishers generate thisinformation in the form of messages, called publications that they want to publishand define the topic of these messages.

The consumer of the information is called a subscriber. Subscribers createsubscriptions that describe the topic that the subscriber is interested in. Thus, thesubscription determines which publications are forwarded to the subscriber.Subscribers can make multiple subscriptions and can receive information frommany different publishers.

A topic is a character string that describes the subject of the information that ispublished. Topics are key to the successful delivery of messages in a publish andsubscribe system. Instead of including a specific destination address in eachmessage, a publisher assigns a topic to each message. The queue manager matchesthe topic with a list of subscribers who have subscribed to that topic, and deliversthe message to each of those subscribers.

In WebSphere MQ V7, publish and subscribe functionality is integrated into thequeue manager. The MQ client publishes information directly to the WebSphereMQ server, and the WebSphere MQ server distributes the information tosubscribers of that specific topic.

The DataPower appliance supports publishing and subscribing to topic stringswhen the backend server is WebSphere MQ V7. The feature provides the followingsupport:v “Publish topic strings”v “Subscribe to topic strings” on page 58v “Subscribe to topic strings using wildcards” on page 59

Publish topic stringsIn WebSphere MQ publish and subscribe, a publisher is an application that makesinformation about a specified topic available to a queue manager in the form of astandard WebSphere MQ message called a publication. A publisher can publishinformation about more than one topic.

The following components specify the topic string to publish:


v MQ Front Side handlerv Backend URLv url-open() extension element

Subscribe to topic stringsIn WebSphere MQ publish and subscribe, a subscriber is an application thatrequests information about a specific topic from a queue manager in a publish andsubscribe network. A subscriber can receive messages, about the same or differenttopics, from more than one publisher.

Subscriptions are nondurable or durable. The following points apply to nondurableand durable subscriptions:v All subscriptions made by DataPower are managed subscriptions. The

WebSphere MQ server automatically creates the subscription queue for themanaged subscriptions. Managed queues are tidied up automatically inaccordance with the durability of the subscription.

v The MQSO option MQSO_NEW_PUBLICATIONS_ONLY is used for allsubscriptions in DataPower. The subscribers do not receive any retained messagethat is published before the subscription is made.

v For nondurable subscriptions, multiple concurrent connections will lead to thereceiving of duplicate publications. For durable subscriptions, only a single user(connection) can have the named subscription at any one time. An attempt toresume a subscription currently in use by another connection will cause the callto fail with MQRC_SUBSCRIPTION_IN_USE. Thus, for both of the durable andnondurable subscriptions in DataPower, there is always only one connectionworking to poll the available publications.

You can make a subscription through any of the following components byspecifying the subscription topic for a nondurable subscription or by specifying thesubscription topic and the subscription name for a durable subscription:v MQ Front Side handlerv Backend URLv url-open() extension element

Note: You can make a subscription to a topic or get a message from a queue, butyou can not do both. If you specify a subscription topic and a GET queue,the subscription topic is ignored.

Nondurable subscriptionsNondurable subscriptions exist only as long as the subscribing application'sconnection to the queue manager remains open. The subscription is removed whenthe subscribing application disconnects from the queue manager. In the context ofDataPower, when the Multi-Protocol Gateway is down or disabled, thesubscription is no longer valid and no more messages will be put to the subscriberqueue. When the Multi-Protocol Gateway is up again, another subscription to thesame topic will be created.

Durable subscriptionsDurable subscriptions continue to exist when the connection to the queue manageris closed. When the subscribing application disconnects, the subscription remainsin place. In the context of DataPower, a queue manager will continue to sendpublications to the durable subscription even when the Multi-Protocol Gateway isdown. These saved publications will be received later when the Multi-Protocol


Gateway is up again. With durable subscriptions, a subscription name is required.Subscription names must be unique within a queue manager so that it can be usedto identify a subscription.

The default option MQCO_KEEP_SUB is used for closing a durable subscription inDataPower. When closing a durable subscription, the handle to the subscription isclosed but the subscription made is kept on the WebSphere MQ server.Publications will continue to be sent to the subscription queue. To permanentlydelete a durable subscription, use the WebSphere MQ Explorer or the MQSCcommands.

Subscribe to topic strings using wildcardsBy specifying a subscription topic string, for example /ibm/datapower, you cancreate a durable or nondurable subscription that registers interest in anexplicitly-specified single topic string and that polls messages that are published tothe topic string to which it is subscribed. By using wildcards in the subscriptiontopic string, the created subscribers can subscribe to multiple topics at one time.

In WebSphere MQ, two wildcard schemes are supported: topic-based wildcardscheme and character-based wildcard scheme. In the topic-based wildcard scheme,wildcards operate on topic elements within the topic string. DataPower supportsthe topic-based wildcard scheme.

Use wildcard topic strings in the backend URL or in a dp:url-open extensionelement by specifying the SubscribeTopicString parameter or in the MQ FrontSide handler Subscribe Topic String field. Use “#” or “+” for wildcard matching,such as /ibm/# or /ibm/+/+.

For example, the following MQ URLs specify a subscription topic string usingwildcards:v Subscribes to all topics.

dpmq://mq-qm/?SubscribeTopicString=#

v Subscribes to every topic in /ibm/datapower/, /ibm/wmq, or /ibm/message-broker.dpmq://mq-qm/?SubscribeTopicString=/ibm/+

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. To use an MQ Front Side Handler with the Proxy,you need to specify the local URI in the Proxy endpoint configuration in theformat of /<MQ FSH name>?RequestQueue=<GetQ>&ReplyQueue=<PutQ>. If you don'twant to place any response on a corresponding reply queue, specify the URI inthe format of /<MQ FSH name>?RequestQueue=<GetQ>.

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 backend 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 BinaryTransform 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>

Figure 6. JMS messages over MQ


Table 4. Header manifest (continued)

Header Value

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.



Appendix. Referenced objects

This chapter contains information about creating objects that are referenced, orassociated with, the configuration of other objects.

Configuring a WebSphere MQ 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

For additional information on DataPower integration with WebSphere MQ, seeIBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ.

This section provides information about configuring an MQ Front Side Handler.

High-level configurationTo configure an MQ Front Side Handler:1. Select Objects → Protocol Handlers → MQ Front Side Handler to display the

MQ Front Side Handler catalog.2. Click Add.3. Define the basic configuration of the handler. See “Defining the basic

configuration” for details.4. Define the publish and subscribe configuration. These fields are only supported

with WebSphere MQ V7 queue managers. See “Defining the publish andsubscribe configuration” on page 65 for details.

5. Define the properties and headers configuration. See “Defining the propertiesand headers configuration” on page 65 for details.

6. Define the advanced configuration. See “Defining the advanced configuration”on page 66 for details.

7. Click Apply to save the changes to the running configuration.8. Optional: Click Save Config to save the changes to the startup configuration.

Defining the basic configurationTo define the basic configuration for an MQ Front Side Handler:1. In the Name field, enter the name for the object.2. Set Administrative State to identify the administrative state of the

configuration.v To make inactive, click disabled.v To make active, click enabled.

3. Optional: In the Comments field, enter a descriptive summary.4. From the Queue Manager list, select a queue manager.5. In the Get Queue field, specify the name of the GET queue.


6. In the Put Queue field, specify the name of the PUT queue.7. In the The number of concurrent MQ connections field, specify the number

of concurrent MQ connections to allocate. The minimum is 1. The default is 1.8. In the Get Message Options field, specify the cumulative value of the

MQGET options that are applicable to an MQ message in decimal orhexadecimal format. The value is passed directly to the MQ API. The defaultis 4097 (decimal value for the MQGMO_WAIT and theMQGMO_SYNCPOINT_IF_PERSISTENT options).See the “MQGMO_* (Get Message Options)” topic in the “Constants” sectionof 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.

9. In the Polling Interval field, specify the number of seconds before anMQGET operation returns if no messages are available. The next attempt willbe performed 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.

10. Use the Retrieve Backout Settings field 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.

11. Use the Use Queue Manager in URL field to determine whether thevar://service/URL-in variable returns the name of MQ Queue Manager orthe name of the MQ Queue Manager Group when this configuration defines aqueue manager group as the queue manager.

on The variable returns the name of the queue manager

off (Default) The variable returns the name of the queue manager group.12. In the CCSI field, specify the Coded Character Set Identifier (CCSID) that the

remote MQ queue manager converts output data. The default CCSID is forISO-8859-1 (latin-1). For a list of CCSID, see the following web site:http://www.ibm.com/software/globalization/ccsid/ccsid_registered.jsp


||

http://www.ibm.com/software/globalization/ccsid/ccsid_registered.jsp

This property is meaningful only when the MQ Queue Manager object has theConvert Input property set to on.

Defining the publish and subscribe configurationTo define the publish and subscribe configuration for an MQ Front Side Handler:1. In the Subscribe Topic String field, specify a topic string. If the Get Queue is

specified, this field is ignored.2. In the Subscription Name field, specify the name for the durable subscription.3. In the Publish Topic String field, specify a topic string associated with the

identified queue manager. The handler publishes messages to this topic string.If the Put Queue field is specified, this field is ignored.

Note: These fields are only supported with WebSphere MQ V7 queue managers.

Defining the properties and headers configurationTo define the properties and headers configuration for an MQ Front Side Handler:1. Use the Parse Properties field to specify whether to parse the properties of the

incoming message from a queue or from a subscription.

on Specifies that parsing is enabled. The WebSphere MQ server returns themessages with the properties.

off (Default) Specifies that parsing is disabled. The DataPower appliancedoes not request the properties with the message when issuing anMQGET call, and the WebSphere MQ server returns the messageswithout the properties.

For additional information, see the section on Message Properties in IBMWebSphere DataPower SOA Appliances: Integrating with WebSphere MQ.

2. In the Selector field, specify the selector as a variable-length string containing aSQL92 query. For additional information, see the section on Message Propertiesin IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ.

Note: This field is only supported with WebSphere MQ V7 queue managers.3. Use the Exclude Message Headers check boxes to select which types of MQ

headers 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)

4. From the Header to Extract Content-Type list, select the MQ header structurefrom which to extract the Content-Type header.

None (Default) No header

MQRFHMQRFH header

MQRFH2MQRFH2 header

Appendix. Referenced objects 65

5. If Header to Extract Content-Type is not None, specify the XPath expression toextract the value of the Content-Type header in the XPath expression to extractContent-Type from MQ header field. Click XPath Tool for help building theXPath expression.

Defining the advanced configurationTo define the advanced configuration for an MQ Front Side Handler:1. Use the Async Put field to specify whether to put a message to a queue

without waiting for a response from the queue manager.

on Specifies that the put operation is asynchronous.

off (Default) Specifies that the put operation is synchronous.

Note: This field is only supported with WebSphere MQ V7 queue managers.2. In the Batch Size field, specify the number of messages to be processed as a

batch. The default is 0 which disables batch processing.

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:1. With the SSL Key Repository controls, define the location of the key database

file.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 samefile 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. From the SSL Cipher Specification list, select the cipher suite.

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


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

SSL Cipher Specification setting Crypto Profile settings

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.

Enabling 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 Automatic Backout to on. This value enables the automatic backout ofpoison 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 makes the DataPower appliance aware of thelocation of remote queue managers:1. Click Objects → Network → MQ Queue Manager.2. Click Add.3. In the Name field, enter the name for the object.4. Set Administrative State to identify the administrative state of the

configuration.v To make inactive, click disabled.v To make active, click enabled.

5. Optional: In the Comments field, enter a descriptive summary.6. In the Host Name field, specify the host name or IP address and port of the

MQ server. If not specified, the default port is 1414.7. Optional: In the Queue Manager Name field, specify the name of the queue

manager. Use when the name of a nondefault queue manager is assigned tothis queue manager.

8. Optional: In the Channel Name field, specify the name of the channel. Use asan alternative to the default SYSTEM.DEF.SVRCONN.

9. In the Channel Heartbeat field, specify the approximate time in secondsbetween heartbeat flows on a channel when waiting for a message on aqueue. If 0, no heartbeat flow is exchanged when waiting for a message onthe channel. This setting does not set the heartbeat on the channel. Thissetting negotiates the heartbeat value with the channel. The greater of the twovalues is used.

10. Optional: In the User Name field, specify a plaintext string that identifies thisclient to the MQ server.


11. Optional: In the Maximum Message Size field, specify the size in bytes of thelargest message to process. Use a value that is equal to or greater than theMaxMsgLength attribute of the channel and of the queue on the MQ server.

12. In the Cache Timeout field, specify the number of seconds that the applianceretains a dynamic connection in the connection cache. Use a value that isgreater than the negotiated heartbeat interval but less than the keep aliveinterval.

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. Set Automatic Backout to indicate whether 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. Optional: Define open connection behavior.a. In the Total Connection Limit field, specify the total number of open

connections to allow.b. In the Initial Connections field, specify the number of connections to open

immediately when the queue manager starts.15. Optional: In the Sharing Conversations field, define the sharing conversation

behavior by specifying the maximum number of conversations to share asingle TCP/IP connection.In WebSphere MQ Version 7 or later, you can use the shared conversationsfeature to control the number of connections between the DataPowerappliance and the MQ server. To enable conversation sharing, specify a valuethat is greater than 1.For more information about sharing conversations, see the following web site:http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.csqzaf.doc/cs13220_.htm.

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

a. With the SSL Key Repository controls, select the location of the keydatabase file.

b. From the SSL Cipher Specification list, select the cipher suite.v To secure with an SSL Proxy Profile: From the SSL Proxy Profile list, select

the instance.17. Set Convert Input to indicate whether the queue manager can convert input

messages to a different CCSID than the one in the original message. Thisconversion is done by the remote queue manager, not the DataPowerappliance. If MQ error 2110 is encountered, disable this setting.The output CCSID is specified on the MQ Front Side Handler.

18. Define the retry behavior.The retry behavior controls the connection behavior of the MQ QueueManager object when it initially tries to connect to the queue manager. Settinga short retry interval, the number of times to attempt to connect at the shortinterval, and a long retry interval allow you to configure the DataPowerappliance to handle repeated connection failures such as when the queuemanager is unavailable for maintenance purposes.


|||

||||

|||

http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.csqzaf.doc/cs13220_.htm

http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.csqzaf.doc/cs13220_.htm

a. Set Automatic Retry to define whether to attempt to reconnect to theremote queue manager at every defined interval.

b. When enabled, define the behavior for retrying failed connections.1) In the Retry Interval field, specify the number of seconds between

automatic retry attempts. This setting does not affect attempts to PUTor GET messages over established, active connections.

2) In the Retry Attempts field, specify the number of attempts to retry thefailed connection. After the reaching this number of attempts, use thelong retry interval. If the long retry interval is disabled, the queuemanager repeatedly attempts to reconnect using the retry intervalsetting.

3) In the Long Retry Interval field, specify the number of secondsbetween retrying the failed connections after the number of retryattempts is reached. This value (long retry interval) must be greaterthan the value of the short interval. To disable, change the retryattempts setting to 0.

4) In the Reporting Interval field, specify the number of seconds betweenthe creation of error messages when failed connections are retried. Thissetting filters the generation of identical error messages to MQ loggingtarget.

19. Set Alternate User to determine whether to use MQOD.AlternateUserId orMQMD.UserIdentifier during MQOPEN and MQPUT operations.

20. In the Local Address field, specify the local address for outbound connections.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.

21. From the XML Manager list, select an XML Manager.22. Optional: Define the CCSID to present to the remote queue manager on

connection.a. Click the Advanced tab.b. In the Character Code Set ID field, specify the CCSID to present to the

queue manager when the DataPower appliance connects to it. This settinghas the same effect as setting the MQCCSID environment variable for an MQclient. See the WebSphere MQ Information Center for more information.For a list of CCSID, see the following web site:http://www.ibm.com/software/globalization/ccsid/ccsid_registered.jsp

23. Optional: Define the MQCSP configuration.The MQCSP support enables the authorization service to authenticate a userID and password. You can specify the MQCSP connection security parametersstructure on an MQCONNX call. Before using the MQCSP support, you needto define a security exit in the MQ Queue Manager on the MQ server. Ensurethat your MQCSP user ID and password in the security exit are consistentwith what you input in the MQ Queue Manager object configuration. Eitheran inconsistent MQCSP user ID or an inconsistent password causes a failureof connection between the DataPower appliance and the MQ server.Take the following actions to define your MQCSP configuration in the MQQueue Manager:a. Click the Advanced tab.b. In the MQCSP User ID field, specify the user ID value of the MQCSP

connection security parameter.


||

|

||||||||

||

|

||

http://www.ibm.com/software/globalization/ccsid/ccsid_registered.jsp

c. In the MQCSP Password field, specify the password value of the MQCSPconnection security parameter.

Notes:

a. If neither the MQCSP user ID or the password is defined, the DataPowerappliance connects to the MQ server without MQCSP settings.

b. If only one is defined, a warning occurs and the MQ Queue Managerobject is not up.

c. If both are defined but one is not consistent with that defined on the MQserver, the connection fails and the MQ Queue Manager object is not up.

24. Click Apply to save the changes to the running configuration.25. Optional: Click Save Config to save the changes 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, see “MQ QueueManager” on page 66.

Working with the multi-instance feature in the WebSphere MQserver

In WebSphere MQ server Version 7.0.1 or later, you can configure multi-instancequeue managers for the failover in the WebSphere MQ server. The active instanceand the standby instance of a queue manager reference the same queue managerdata and logs in shared network storage. When the active instance fails, thestandby instance automatically takes over the data and logs from the activeinstance, and accepts re-connections from clients and channels.

To work with the multi-instance feature in the WebSphere MQ server for thefailover in the DataPower appliance, you need to configure your MQ QueueManager Group object with the multi-instance queue managers in the WebSphereMQ server. Connect the primary queue manager to one of the instances of a queuemanager in the MQ server, and the backup queue manager to the other instance. Ifthe active instance in the MQ server fails, the DataPower appliance selects thequeue manager connected to the standby instance, and this queue managerautomatically takes over all the data and logs from the queue manager connectedto the original active instance.

For more information about multi-instance queue managers, seehttp://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.amqzag.doc/fa70150_.htm.


||

|

||

||

||

|

|

||||||

|||||||||

|||

http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.amqzag.doc/fa70150_.htm

http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/com.ibm.mq.amqzag.doc/fa70150_.htm

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, see the online help.4. Click Apply to save the changes to the running configuration.5. Optional: Click Save Config to save the changes to the startup configuration.



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, DataPower, and WebSphere are registered trademarks of theInternational Business Machines Corporation in the United States or othercountries. If these and other IBM trademarked terms are marked on their firstoccurrence in this information with a trademark symbol (® or ™), these symbolsindicate U.S. registered or common law trademarks owned by IBM at the time thisinformation was published. Such trademarks may also be registered or commonlaw trademarks in other countries. A current list of IBM trademarks is available onthe Web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml.

Adobe is either a registered trademark or trademark of Adobe SystemsIncorporated in the United States, and/or other countries.


http://www.ibm.com/legal/copytrade.shtml

http://www.ibm.com/legal/copytrade.shtml

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 product and service names might be trademarks of IBM or other companies.


Index

Aactions

MQ Headermodifying reply queue 22modifying reply queue

manager 23modifying request message

headers 21modifying response message

headers 22overview 20retrieving responses with

correlation ID 21retrieving responses with message

ID 21

Bbackout queue, MQ 68backup queue managers, MQ 72basic configuration

MQ Front Side Handler 63bold typeface vi

Ddocumentation conventions, typefaces vidurable subscriptions 58

Eerror 2010, MQ 70error 2110, MQ 70

Ffailover configurations

MQ queue managers 72files

MQkey database file 67stash file 67

Front Side Handlerobject pages

MQ 63

GGSKit, MQ integration 67

Hheader-manifest variable 60

Iintellectual property 75

IP addressesMQ queue managers 66

italics typeface vi

KKAINT attribute, MQ server 68key database file

MQ 67

Llicensing

sending inquiries 75

Mmessages

poison, MQ 68monospaced typeface viMQ error 2010 70MQ error 2110 70MQ Front Side Handler 63

advanced configuration 66basic configuration 63configuration 63properties and headers

configuration 65publish and subscribe

configuration 65MQ Get Message Options (GMO)

MQGET options 64MQGMO_* 64

MQ header actionmodifying

reply queue 22reply queue manager 23request message headers 21response message headers 22

overview 20retrieving responses

with correlation ID 21with message ID 21

MQ headersMQMD

UserIdentifier 71MQOD

AlternateUserId 71MQ integration

GSKit 67z/OS 67

MQ Queue Managerautomatic retry 70configuring 69error 2010 70error 2110 70MQCSP password 71MQCSP support 71MQCSP userID 71retry behavior 70

MQ Queue Manager (continued)sharing conversations 70

MQ Queue Manager Groupbackup queues 72configuring 73primary queue 72

MQ queue managersautomatic backout 68backup 72dynamic connections

timing out 68failover configuration 72host name 66IP addresses 66key database file 67primary 72securing communication 67securing with GSKit 67securing with SSL Proxy Profile 67stash file 67synch points 68transactions 68units of work 68z/OS integration 67

MQ request messagesmodifying message headers 21specifying correlation ID 21specifying message ID 21

MQ response messagesmodifying headers 22modifying reply queue 22modifying reply queue manager 23

MQ servershost name 66IP addresses 66KAINT attribute 68keep alive interval 68

MQCO_KEEP_SUB 58MQMD.UserIdentifier 71MQOD.AlternateUserId 71MQRC_SUBSCRIPTION_IN_USE 58MQSO_NEW_PUBLICATIONS_ONLY

option 58

Nnondurable subscriptions 58notices 75

Oobject pages

Front Side HandlerMQ 63

objectsMQ Queue Manager 69MQ Queue Manager Group 73


Ppatents 75poison messages, MQ 68primary queue manager, MQ 72publish

MQ Front Side Handler 65

Qqueue managers

See MQ queue managers

Ssoftware requirements 1SSL Proxy Profile

MQ Queue Manager 67stash file

MQ 67subscribe

MQ Front Side Handler 65subscriptions

durable 58nondurable 58

synch points, MQ 68SYSTEM.DEAD.LETTER.QUEUE 68

Ttopic strings

subscribing 58wildcards 59

trademarks 75transactions

MQautomatic backout 68MQMD.Backoutcount 68

transactions, MQ 68typeface conventions vi

Uunits of work, MQ 68

Vvariables

header-manifest 60

WWebSphere MQ

supported version 1wildcards

topic strings 59

Zz/OS

MQ integration 67


��

Printed in USA

Data Power Integrating With Mq

Documents

based wildcard

sample style

datapower

custom style

ssl proxy

mq helper

websphere

negotiated