Data Power Integrating With MQ

DataPower SOA Appliances
Version 3.8.1
Integrating with WebSphere MQ
DataPower SOA Appliances

Version 3.8.1
Integrating with WebSphere MQ
Note Before 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 all subsequent 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 Contract with IBM Corp.
Contents
Preface . . . . . . . . . . . . . . . v
Intended audience . . . . . . . . . . . . v File naming guidelines . . . . . . . . . . . v Object naming guidelines . . . . . . . . . . v Typeface conventions . . . . . . . . . . . vi Common message delivery patterns . Independent asynchronous delivery Synchronous delivery . . . . . Units of work with other protocols . Front Side . . . . . . . . . Back Side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 41 42 44 44 44
Chapter 1. Introduction . . . . . . . . 1
Software requirements . . . . Multi-Protocol Gateway service . Configuration for integration with DataPower service . . . . MQ Front Side Handler object MQ Queue Manager object . Processing policies . . . . MQ Queue Manager Group . Basic MQ architecture . . . . Message workflow . . . . . HTTP to MQ . . . . . . MQ to HTTP . . . . . . . . . . . . . . WebSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1 1 2 2 2 3 3 3 5 5 6
Chapter 5. Error handling. . . . . . . 45

Automatic Retry property . . . . . . . . . Process Backend Errors property . . . . . . . When to use the Process Backend Errors property Automatic Backout property. . . . . . . . . When to use the Automatic Backout property . . Enabling automatic backout . . . . . . . . Using the backout settings from the WebSphere MQ server . . . . . . . . . . . . . . The MQ reason code (MQRC) . . . . . . . . Reading the MQRC in a style sheet . . . . . Returning the MQ error message in a style sheet Using the error-ignore service variable . . . . . When to use the error-ignore service variable . . Using the error-ignore service variable in a style sheet . . . . . . . . . . . . . . . Using an error rule . . . . . . . . . . . . Datagram traffic with Units of Work disabled . . Datagram traffic with Units of Work enabled . . Datagram traffic with custom error handling . . Request and reply traffic . . . . . . . . . 45 46 46 46 46 46 47 47 47 48 49 49 50 51 51 51 52 52
Chapter 2. Routing . . . . . . . . . . 9
Back-side request routing . . . . . . . . . Back-side destinations . . . . . . . . . . Using an MQ URL to set back-side destinations . Syntax for a static MQ URL . . . . . . . Using the MQ Helper to build a static MQ URL Using a static MQ URL in a style sheet . . . Syntax for a dynamic MQ URL . . . . . . Front Side reply routing . . . . . . . . . . 9 . 9 . 10 . 10 13 . 14 . 15 . 16
Chapter 3. MQ header values . . . . . 19

Injecting and suppressing headers . . . . . MQ header action . . . . . . . . . . Modifying MQMD request headers . . . Retrieving responses by message ID or by correlation ID. . . . . . . . . . . Modifying MQMD response headers . . . Modifying the reply queue for responses . Modifying the queue manager for responses Using MQ headers with custom style sheets . Message descriptor header (MQMD) . . . IMS Information Header (MQIIH) . . . . CICS Bridge Header (MQCIH) . . . . . Object descriptor header (MQOD) . . . . WebSphere MQ API support. . . . . . . . . . . . . . . . . . . . . 19 . 20 . 21 . . . . . . . . . . 21 22 22 23 23 24 27 28 29 33
Chapter 6. Additional configuration options . . . . . . . . . . . . . . 53

Asynchronous put operations . . . . . Authentication and authorization . . . . Batch request processing . . . . . . . Message Properties . . . . . . . . . Enabling parsing for message properties. Filtering messages by properties . . . Manipulating message properties in the processing policy . . . . . . . . Monitoring, logging, and status. . . . . Ordered messaging . . . . . . . . . Publish and subscribe using topic strings . Publish topic strings . . . . . . . Subscribe to topic strings . . . . . . Subscribe to topic strings using wildcards Using MQ with a Web Service Proxy . . . MQ and JMS . . . . . . . . . . . Legacy WebSphere MQ service objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 53 54 54 54 55 55 56 56 57 57 58 59 59 60 61
Chapter 4. Units of Work . . . . . . . 35

WebSphere MQ client Units of Work capabilities Units of work implementation . . . . . . Transactions on a service . . . . . . . . Units of Work property . . . . . . . Transactional parameter . . . . . . . Sync parameter . . . . . . . . . . MQGMO and MQPMO syncpoint options .
Copyright IBM Corp. 2006, 2010
. . . . . . .
. . . . . . .
35 36 38 39 39 40 40
Appendix. Referenced objects
. . . . 63
63 63 63 65
Configuring a WebSphere MQ handler . . . . . High-level configuration . . . . . . . . . Defining the basic configuration . . . . . . Defining the publish and subscribe configuration
iii
Defining the properties and headers configuration . . . . . . . . . . . . Defining the advanced configuration . . . . MQ Queue Manager . . . . . . . . . . Identifying the MQ server . . . . . . . Securing communication with remote queue managers . . . . . . . . . . . . . Defining the timeout for dynamic connections . Enabling units of work . . . . . . . . Configuring Queue Manager objects . . . .
. . . . . . . .
65 66 66 66 67 68 68 69
| |
MQ Queue Manager Group . . . . . . . . . 72 Working with the multi-instance feature in the WebSphere MQ server . . . . . . . . . . 72 Configuring MQ Queue Manager Group objects 73
Notices and trademarks . . . . . . . 75

Trademarks . . . . . . . . . . . . . . 75
Index . . . . . . . . . . . . . . . 77
iv
DataPower SOA Appliances: Integrating with WebSphere MQ
Preface
IBM WebSphere DataPower SOA Appliances are purpose-built, easy-to-deploy network appliances that simplify, help secure, and accelerate your XML and Web Services deployments while extending your SOA infrastructure. These appliances offer an innovative, pragmatic approach to harness the power of SOA while simultaneously enabling you to leverage the value of your existing application, security, and Networking infrastructure investments.
Intended audience
This document is intended for administrators and application developers who manage the configuration of services, objects, and associated referenced objects related to integrating with WebSphere MQ on a DataPower appliance. You should have the following knowledge: v Network architecture and concepts v WebSphere MQ administration v WebSphere MQ application development
File naming guidelines

The maximum length for a file name can be approximately 4128 characters. The name of the base file can be up to 128 characters in length. The base file is the part after 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 a length of 4000 characters. When you create a domain, its name is the base file name 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 guidelines

The object name must be unique in the object namespace. The following characters are valid when specifying the name for an object: v a through z v v v v A 0 _ through Z through 9 (underscore) (dash)
v . (period) Note: Names cannot contain two consecutive periods (..).
Typeface conventions
The following typeface conventions are used in the documentation: bold italics Identifies commands, programming keywords, and GUI controls. Identifies words and phrases used for emphasis and user-supplied variables.
monospaced Identifies user-supplied input or computer output.
vi
Chapter 1. Introduction
The IBM WebSphere DataPower SOA Appliances can exchange messages with WebSphere MQ systems by connecting as a WebSphere MQ client. This capability allows the DataPower appliance to bridge disparate messaging and transport protocols, such as HTTP or TIBCO EMS, to WebSphere MQ. Messages originating within or outside of a WebSphere MQ system can flow easily to and from another WebSphere MQ system or other messaging system, such as HTTP or TIBCO EMS. To bridge the disparate messaging and transport protocols, the DataPower appliance uses a service, such as the Multi-Protocol Gateway service.
Software requirements
DataPower appliance integrates with IBM WebSphere MQ versions 6.0 and 7.0. The WebSphere MQ Information Center for each version is available at http://www.ibm.com/software/integration/wmq/library/.
Multi-Protocol Gateway service

A Multi-Protocol Gateway service is a DataPower appliance service that accepts client-originated messages in a variety of protocols and subsequently passes messages to a backend server using a variety of protocols. In addition to the messaging system bridging, the Multi-Protocol Gateway service can also apply the full range of transformation, security, authorization, routing, logging and customization services available to the messages flowing through the service to and from the WebSphere MQ system. In every case, the service behaves as an intermediary in the message flow. The service does not store or hold messages outside the context of a single transaction, as a WebSphere MQ queue manager might do. A Multi-Protocol Gateway service, and the other configuration objects employed on the appliance to implement integration with WebSphere MQ messaging systems, offers flexibility for tuning integration with WebSphere MQ. This discusses configuration options in the context of an enterprise architecture including routing to remote queue managers, handling MQ headers, and error processing.
Configuration for integration with WebSphere MQ

To define integration with WebSphere MQ, you must configure objects on the DataPower appliance. The following list of objects are those most frequently configured when developing a service for integration with WebSphere MQ. Many of 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 page 2.
Note: In this document, the DataPower object is referred to as the MQ Queue Manager 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 service
The 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 object

The MQ Front Side Handler object polls the configured request queue, managed by the referenced WebSphere MQ queue manager, for incoming requests. See Configuring a WebSphere MQ handler on page 63 for how to configure an MQ Front Side Handler object. The following properties are defined as part of the MQ Front 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 Backout threshold and Backout requeue queue name from the WebSphere MQ server. v Use Queue Manager in URL field to determine whether the value of the var://service/URL-in variable returns the name of the MQ Queue Manager or the name of the MQ Queue Manager Group.
MQ Queue Manager object

The MQ Queue Manager object defines the properties required to connect to the WebSphere MQ queue manager. The MQ Queue Manager object on the appliance does 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 of an MQ Queue Manager object. The following properties are defined as part of the MQ 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 not process.
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 what interval.
Processing policies
Processing policies might contain one or more processing rules with the following actions: 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, on page 45 for more information.
MQ Queue Manager Group

The MQ Queue Manager Group object implements a failover configuration. The following 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 becomes unavailable. See MQ Queue Manager Group on page 72 for information about how to configure the primary and backup MQ Queue Manager objects. | | | | | In WebSphere MQ server Version 7.0.1 or later, you can configure multi-instance queue managers for the failover in the WebSphere MQ server. In the DataPower appliance, you can configure the MQ Queue Manager Group object to work with the multi-instance feature for the failover. See Working with the multi-instance feature in the WebSphere MQ server on page 72 for more information.
Basic MQ architecture
When integrating with WebSphere MQ system, a DataPower service performs messaging system bridging from variety of protocols to the MQ protocol or from the MQ protocol to a variety of protocols. The service also supports message traffic from 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 system v 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 MQ client only. The service does not act as a WebSphere MQ queue manager. Figure 1 on page 4 illustrates the basic architecture implemented when a DataPower service is used to connect an HTTP-based messaging system (typical of a Web Services architecture) to a WebSphere MQ-based system inside the enterprise. The figure illustrates the primary configuration objects created on the
appliance as well as the configuration of the MQ Queue Manager to which the service connects and exchanges messages.
Figure 1. Basic architecture for HTTP to MQ messaging
The Front Side Handler object implements HTTP transport connectivity on the client, or front, side of the service. On the back end, the Multi-Protocol Gateway employs MQ-based URLs to determine the WebSphere MQ queue to which requests are forwarded, and also from which replies are pulled. Conversely, Figure 2 illustrates a DataPower service being used to extend a WebSphere MQ-based messaging system out to a Web Services architecture.
Figure 2. Basic architecture for MQ to HTTP messaging
Here, the Front Side Handler object polls a WebSphere MQ queue for request messages and places replies from the back-end services on another WebSphere MQ queue. The Front Side Queue Manager object might optionally place messages in an error queue on the WebSphere MQ queue manager. On the back end, a standard HTTP URL is used to determine the destination to which requests are forwarded, and from which answers are received in accordance with the HTTP specification.
Message workflow
The 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 MQ protocol example in which a DataPower service connects an HTTP-based messaging system to a back-end WebSphere MQ system. Next, the message workflow for the MQ protocol to HTTP example is provided. In this workflow the DataPower service connects a front side WebSphere MQ system to a back-end Web Services architecture.
HTTP to MQ
As illustrated in Figure 1 on page 4 (HTTP to MQ), messages flow to and from the DataPower appliance and work is performed by the appliance in the following sequence. 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 Gateway service object. The Multi-Protocol Gateway service then applies relevant Processing Policy actions on the message. 3. The Multi-Protocol Gateway either dynamically determines the appropriate destination to which to route the message, or routes all messages statically to a particular destination. In either case, in this architecture, the destination is a particular queue managed by a particular MQ queue manager. The DataPower MQ Queue Manager object contains the necessary information to establish a connection to the MQ queue manager. 4. The message is placed on the destination queue with the MQPUT command. If the network connection to a queue manager fails, the service will cancel the transaction and start error handling. See Chapter 5, Error handling, on page 45 for more information. 5. The appliance polls the reply-to queue specified in the Destination URL field to find a correlated response message. The Multi-Protocol Gateway examines the Correlation 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, the Multi-Protocol Gateway takes the message as the response. Note that the reply-to queue specified in the MQMD header of the message should agree with the reply-to queue specified in the Destination URL when the Multi-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 might again apply any of the configured Processing Policy actions to the response and returns the reply to the requesting HTTP client. The reply can include error responses from the back-end application server. If no response is found within the Timeout property set in the Destination URL, the Multi-Protocol Gateway handles the error in the same fashion as a back-end error. Note that the Timeout must be set in the Destination URL used to contact the WebSphere MQ back-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 any message 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 omit designating a reply-to queue. In this case, the Multi-Protocol Gateway does not wait for a correlated response message or any error message and terminates the transaction immediately after putting the message on the back-end queue. No response is sent to the front side HTTP client.
MQ to HTTP
As illustrated in Figure 2 on page 4 (MQ to HTTP), messages flow to and from the DataPower appliance, and work is performed by the appliance, in the following sequence. 1. An MQ Front Side Handler object polls the configured Request queue, managed by the referenced WebSphere MQ queue manager, for incoming requests. All messages found on the queue are copied from the queue. To control the GET command, use the MQ GET options that are available for large segmented messages through the MQ Front Side Handler. The MQ Front Side Handler accepts the decimal value for the desired MQ GET option. See the MQGMO_* (Get Message Options) topic in the Constants section of the WebSphere MQ Information Center for details. To implement redundancy, configure the Multi-Protocol Gateway to use more than one MQ Front Side Handler polling a range of queues. It is then up to the WebSphere MQ system, independent of the service, to route messages to an active queue. If the message is a Request, the Front Side Handler saves the MessageID, ReplyToQueue, and ReplyToQueueManager fields in the message for later processing of a reply. See item 4 on page 7 for more information. By default, all request messages are immediately removed from the request queue. To leave the request message on the request queue until processing by the Multi-Protocol Gateway is complete with no errors, set the Units of Work property of the MQ Queue Manager object in use by the MQ Front Side Handler 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 Gateway service object. The Multi-Protocol Gateway applies relevant Processing Policy actions on the message. The Multi-Protocol Gateway either dynamically determines the appropriate destination to which to route the message or routes all messages statically to a particular destination. In this scenario, the back end employs HTTP. The Multi-Protocol Gateway opens an HTTP connection and typically posts the request. If the gateway encounters a network error or is otherwise unable to establish a connection to the back-end server, by default the Gateway runs any matching error rule in the processing policy. The result is returned to the MQ Front Side Handler for delivery. See item 4 on page 7. 3. The Multi-Protocol Gateway gets the response from the back-end application server. In this scenario, the HTTP protocol requires a response (which might contain an error message) or the Multi-Protocol Gateway registers an error. When the back-end HTTP server returns a good response, the Multi-Protocol Gateway applies any applicable Processing Policy actions to the response. Any processing errors will typically terminate the transaction unless error handling has been built into the policy. When the back-end application returns a response with a protocol error, such as HTTP 500, by default the Gateway processes this response using the same response rules used for a good response. The result of any such processing is forwarded to the PUT queue of the MQ Front Side Handler. To configure the gateway to run an error rule, rather than a standard response rule 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 result of the Error rule on the Put queue of the MQ Front Side Handler unless the MQ Queue Manager object has the Units of Work property set to 1, in which case 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 MQ Front Side Handler. The Front Side Handler sets the MQMD CorrelID to the saved MsgID of the original request. If the original request message specifies a reply-to queue, the Front Side Handler places the response on the queue specified in the message, rather than on the Put queue specified in the Front Side Handler. Unlike HTTP, the MQ protocol does not require a response. However, if the response rule has changed the RepyToQ and the ReplyToQMgr in the 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 queues just as messages are routed to and from HTTP destinations. The Multi-Protocol Gateway uses either static or dynamically determined routes. The service provides several methods to determine where a message should be routed and how the routing 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 to determine 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 10 Provides information about setting a static or a dynamic MQ URL.
Back-side request routing

A Multi-Protocol Gateway can use either static or dynamic routing to a back-end destination. When using a static route, the Backend URL property of the Gateway determines the route. When using dynamic routing, the processing policy of the service must set the destination during processing. The Gateway can examine the following parts of the input message to help determine where the message should be routed. Message content The Multi-Protocol Gateway can dynamically determine the destination queue by employing either an XPath routing map or a custom style sheet to examine the content of the message. Protocol header The Multi-Protocol Gateway can also dynamically determine the destination queue by examining the value of the MQ protocol headers. For a list of all headers, use the var://service/header-manifest service variable, which contains a nodeset of all supported headers found in the message, including the required MQMD header. The complete header can be obtained by reading the extension variable var://context/INPUT/ _extension/header/MQMD. The header has already been parsed into a nodeset for easy reference. See Chapter 3, MQ header values, on page 19 for more information. Note that you can inspect the headers presented by other request protocols, such as HTTP or JMS, in similar fashion.
Back-side destinations
If 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 using the Results (or Results Async) processing actions, just as with HTTP messages. For example, a single request message might contain a number of attachments. These attachments can be separated from the original request and routed individually to a particular destination (that might not be a WebSphere MQ queue). The processing policy of the Multi-Protocol Gateway can collect the responses and construct a reply message, can ignore the responses, or can send a response message 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 destinations

The DataPower service employs an MQ URL to express a target queue on a WebSphere MQ server where messages are put and retrieved. To send to and to retrieve messages from a back-end WebSphere MQ system, use either a static or a dynamic 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 prior configuration of an MQ Queue Manager object whose properties provide the information (for example, host name and channel name) that is required to access the WebSphere MQ server. A Multi-Protocol Gateway service defined as having a static back end provides the MQ Helper utility in the WebGUI to construct the URL using selected options. v The dynamic URL format establishes a connection to a WebSphere MQ server in the absence of a locally configured MQ Queue Manager object. When a Multi-Protocol Gateway service is defined as having a dynamic back end, the back-end server address and port are determined by a processing policy action such as a transform action or a route action. The action can determine the route by using a style sheet, an XPath expression, or a variable. This provides the flexibility within a processing policy to dynamically determine the destination at run time.
Syntax for a static MQ URL

The 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 MQ back-end system.
QueueManagerObject Specifies the name of an existing MQ Queue Manager object stored on the appliance. The object provides the connection information needed to access a remote WebSphere MQ queue manager on a WebSphere MQ server. Optionally, use the name of a Queue Manager Group to implement failover. URI Specifies the URI portion of the path to the target queue.
RequestQueue=requestQueueName Specifies the name of the back-end WebSphere MQ request queue. This queue is where the DataPower service, acting as the WebSphere MQ client,
10
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 a request queue and a reply queue name. However, if a reply queue and a publish topic string are specified, the last one entered is used and the other parameter is ignored. ReplyQueue=replyQueueName Specifies the name of the back-end WebSphere MQ reply queue that the service polls for responses. The URL minimally must contain a request queue, a publish topic string, or a reply queue name. The URL can contain both a request queue and a reply queue name. queryParameters Specifies optional and required query parameters for static and dynamic URLs. AsyncPut={true|false} Specifies whether to put a message to a queue without waiting for a response from the queue manager. true false Specifies that the put operation is asynchronous. (Default) Specifies that the put operation is synchronous.
For additional information, see Asynchronous put operations on page 53. Browse={first|next|current} Browses (retrieve without removing) messages from the queue that is specified in the ReplyQueue parameter. Use one of the following values: first next Browses the first message on the queue. Browses the messages on the queue in incremental order. For example, if you specify next after browsing message one, the url-open browses message two. Specifying next on the first url-open attempt browses the first message on the queue. Browses the message on the queue that the url-open just read. For example, if you specify current and the previous browse result is message one, the url-open browses message one. You can also specify the MQGMO browse options in the GMO=optionsValue parameter. In the case of a conflict between the Browse parameter and the GMO parameter, the GMO flag takes precedence. ContentTypeHeader=header Specifies the name of the MQ header that identifies the content type of the message data. ContentTypeXPath=expression Specifies an XPath expression to run on a parsed MQ header (specified in the ContentTypeHeader parameter) to extract the content type of the message data.
current | | | |
Chapter 2. Routing
11
GMO=optionsValue Specifies an integer that identifies a field option for a MQ GMO GET operation. 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 to the RequestQueue indicated and use the dynamic, temporary Model queue defined by the ReplyQueue value to get the response. When the response is received, the connection to the temporary queue is closed. ParseHeaders={true|false} Specifies a Boolean value that parses and strips headers from message data. ParseProperties={on|off} Specifies whether to parse the properties of the incoming message from a queue or from a subscription. The ParseProperties parameter applies to the ReplyQueue or the SubscribeTopicString. on off Specifies that parsing is enabled. The WebSphere MQ server returns the messages with the properties. (Default) Specifies that parsing is disabled. The DataPower appliance does not request the properties with the message when issuing an MQGET call, and the WebSphere MQ server returns the messages without the properties.
For additional information, see Message Properties on page 54. PMO=optionsValue Sets the value for MQPMO.Options. This optional value is a cumulative value in decimal format of all acceptable options. For example, a value 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 the MQPUT call that is used to place the request message of the back-end request queue. See the MQPMO_* (Get Message Options) topic in the Constants section of the WebSphere MQ Information Center 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 one entered is used and the other parameter is ignored. For additional information, see Publish topic strings on page 57. Selector=expression
12
Specifies a variable length string containing a SQL92 query that filters messages based on the message properties. The Selector applies to the 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 value for 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 last one entered is used and the other parameter is ignored. For additional information, see Subscribe to topic strings on page 58. SubscriptionName=string Specifies a name for the subscription. The presence of this parameter makes the subscription a durable subscription. For additional information on durable subscriptions, see Subscribe to topic strings on page 58. Sync={true|false} Optional: Specifies whether the PUT operation to the request queue is committed immediately upon successful delivery of the message. true Specifies that the PUT operation is committed immediately upon successful delivery of the message so that back-end applications and GET operations can process the message from the request queue. (Default) Specifies that the PUT operation is not committed.
false
Note: Note that the QueueManagerObject identified must have the Units of Work property set to 1 (the default is 0). TimeOut=timeout Specifies the timeout value, in milliseconds, for a GET message operation. Transactional={true|false} Optional: Specifies whether the URL open call executes as part of a transaction. true The URL open call executes as part of a transaction and synchronizes the PUT operation to the request queue with the GET operation from the reply queue. (Default) The URL open call does not execute as part of a transaction.
false
Using the MQ Helper to build a static MQ URL

The MQ Helper is available in DataPower WebGUI when creating or editing a Multi-Protocol Gateway service through the service view. For information about the 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 is given the following input:
Chapter 2. Routing
13
v v v v v
The MQ Queue Manager object is specified as DPQM The RequestQueue is specified as BACK.REQUEST The ReplyQueue is specified as BACK.REPLY Transactionality is set to on 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 sheet

A static MQ URL can also be used in a custom style sheet. The following example combines the use of a static MQ URL with the Browse query parameter and the dp:mq-queue-depth extension function to locate message b3 in a WebSphere MQ queue with a message depth value of 4. See IBM WebSphere DataPower SOA Appliances: Extension Elements and Functions Catalog for more information on the dp:mq-queue-depth extension function, including the complete syntax for specifying the 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>
14
. </xsl:template> . .
Syntax for a dynamic MQ URL

The 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 host port Identifies the required protocol identifier for a dynamic WebSphere MQ URL. Specifies the host name or IP address of the target WebSphere MQ server. Specifies the associated port on the target WebSphere MQ server.
QueueManager=queueManager Specifies the name of a WebSphere MQ queue manager on the target WebSphere MQ server. UserName=userName Specifies the plain text string to identify the client to the WebSphere MQ server. Channel=channelName Specifies the name of the channel, defined on the WebSphere MQ server, to connect to the WebSphere MQ queue manager. ChannelTimeout=channelTimeout Specifies an integer that indicates the number of seconds that the DataPower appliance retains (keeps alive) a dynamic connection in the connection cache. This value specifies the Cache Timeout parameter for the dynamic MQ Queue Manager object. Specify a value that is greater than the 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 the timeout value for a channel. Not all channels have a defined, explicit keep alive interval on the WebSphere MQ server. Some queue managers use an automatic timeout setting (the KAINT attribute set to AUTO). In these cases, the keep alive interval is the negotiated heartbeat interval plus 60 seconds. When an inactive connection reaches this threshold, the appliance removes that dynamic connection from the cache. When the cache no longer contains dynamic connections, the appliance deletes the dynamic queue manager. Without a dynamic queue manager, there is no connection with the back-end WebSphere MQ server. Note: This timeout value is the only way to configure a timeout value from the appliance to the back-end WebSphere MQ server. No other configuration setting on the appliance can time out an MQ connection.
Chapter 2. Routing
15
ChannelLimit=channelLimit Specifies the maximum number of open channels to allow between the appliance and the remote WebSphere MQ queue manager. Use any value of 2 - 5000. Size=maxMsgSize Specifies the maximum size of messages that the WebSphere MQ queue manager accepts. Use an integer between 1024 bytes and 1 GB. | | | | | | MQCSPUserId=MQCSPUserId Specifies the user ID value of the MQCSP connection security parameter when MQCSP structure is used for authorization service. MQCSPPassword=MQCSPPassword Specifies the password value of the MQCSP connection security parameter when MQCSP structure is used for authorization service. queryParameters See queryParameters under Syntax for a static MQ URL on page 10 for more information. You can construct a dynamic MQ URL that points to a WebSphere MQ queue manager that has not been defined by a static MQ Queue Manager object on the appliance. 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 routing

The 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 message 2. Using the Reply-to queue specified in a request message 3. Using the PUT queue specified in the MQ Front Side Handler Set the Front Side ReplyTo Queue dynamically during processing by configuring a Response Header Injection property that sets the ReplyToQ header to the desired value. For example, specify the following Header Injection values to send a reply message to the QUEUE5 ReplyToQ.
Table 1. Header Injection Settings Property Direction Name Value Value Front ReplyToQ 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 MQ queue manager during processing. Use the same gateway Header Injection
16
configuration method, or extension function, changing the header name to ReplyToQM and the value to the desired queue manager name. Note that the queue manager name must match the name of a configured MQ Queue Manager object on the appliance which in turn connects to the desired remote WebSphere MQ queue manager, not the name of a Manager elsewhere on the network. For example, specify the following Header Injection values to send a reply message to the WASQM ReplyToQM where WASQM is the name of an existing MQ Queue Manager object.
Table 2. Header Injection Settings Property Direction Name Value Value Front ReplyToQM WASQM
You can also determine the routing of messages to front side WebSphere MQ queues by using the MQMD header contained in the message to be delivered by the MQ Front Side Handler. The MQMD header is covered in detail in Message descriptor header (MQMD) on page 24.
Chapter 2. Routing
17
18
Chapter 3. MQ header values

The DataPower service recognizes and can modify the content of a subset of MQ headers to alter the routing of messages and to control the behavior of the communications with the queue manager. The following MQ headers are supported by the DataPower service: v MQCD v MQCIH v MQCNO v MQDH v v v v v v v MQDLH MQGMO MQIIH MQMD MQOD MQPMO MQRFH
v MQRFH2 v MQSCO v MQTM v MQWIH v MQXQH When an incoming message contains an MQ header other than this subset, the service leaves the header as it is and passes the message to the back end. The service logs a message indicating that the MQ message contains a header that is not supported. For these unsupported headers, there is no guarantee that the message will be accepted or processed correctly on the WebSphere MQ server. The service provides several methods, from basic to completely customized, to manipulate MQ headers. The following sections describe these methods. v Front-side and back-side Injecting and suppressing headers parameters at the service level v MQ header action on page 20 of a processing rule v Using MQ headers with custom style sheets on page 23to manipulate of the header values from a processing rule
Injecting and suppressing headers

The 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 to meet your requirements. For instance, suppose you want to simply suppress the WebSphere MQ Message Descriptor (MQMD) message header on messages passing through a Multi-Protocol Gateway. This can be done from the Headers tab of the service: 1. Click Headers.
19
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 the specified header before forwarding the request. Similarly, using header injection, you can specify a header and a header value to inject. Even though the headers are not defined in the original request, the service provides the specified headers. For example, change the MQMD.Format to MQHRF2 using the following header injection parameters.
Table 3. Header Injection Settings Property Direction Name Value Value Back MQMD <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 a CodedCharSetId (CCSID) field, you must specify the CCSID value in the MQ header. If this is not done, the service will use 819 (ISO 8859-1 ASCII) as the 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 but the CCSID is 819, not 1208 (UTF-8).
MQ header action
The MQ Header action can perform the following header and queue modifications: Modify MQMD Request Message Headers Selectively override specified headers values in a request message or drops all header values from the request message and replaces with new or auto-generated values. Retrieve Responses using Message Id or Correlation Id Modify how the service retrieves response messages from a backend reply queue by specifying a message ID or Correlation ID. By default, the service looks in the backend reply queue for response messages that have a Correlation Id that matches the Message Id of the request message. Modify MQMD Response Message Headers Selectively override specified header values in a response message or drops all header values from the response message and replaces with new or auto-generated values. Modify Reply Queue for Response Messages Modify the destination reply queue for response messages. By default, the service sends responses to the reply queue specified in the MQ Front Side Handler. Modify Queue Manager for Response Messages Modify the destination MQ Queue Manager for response messages. By default, the service sends responses to the MQ Queue Manager specified in the MQ Front Side Handler.
20
Modifying MQMD request headers

To 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 next action. 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 another icon to the configuration path.
Retrieving responses by message ID or by correlation ID

To 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 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 next action. 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 messages from the backend reply queue with the specified message ID. v In the Correlation Id field, specify the correlation ID. The service pulls messages from the backend reply queue with the specified correlation ID. 10. Select an output context. If auto, processing inserts the output context.
21
11. Click Done. If this is the last action for the rule, click Apply Policy. Otherwise, drag another icon to the configuration path.
Modifying MQMD response headers

To modify MQMD header values for response messages placed to 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 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 next action. 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 v v v v Message Id Correlation Id Character Set Id Format Name 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 another icon to the configuration path.
Modifying the reply queue for responses

To 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 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 next action. 7. Select response as the MQ Processing Type. 8. Select ReplyToQ from the MQ Response Header Processing list.
22
9. From the ReplyToQ 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. If this is the last action for the rule, click Apply Policy. Otherwise, drag another icon to the configuration path.
Modifying the queue manager for responses

To 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 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 next action. 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. If this is the last action for the rule, click Apply Policy. Otherwise, drag another icon to the configuration path. 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 for response processing, the ReplyToQ name might be specified with static text or with a variable such as var://context/INPUT/hdrval.
Using MQ headers with custom style sheets

While header injection and suppression and the MQ Header action provide ease of use in handling MQ headers, using custom style sheets adds additional customization for dynamic, runtime control of MQ headers. Typically, the style sheet is used in a transform action in a request, response, or error rule of the processing policy. A results action is not needed, since the service will put the message to the queue and queue manager which are set dynamically in the style sheet. There are different ways to implement the desired routing as demonstrated with the sample style sheets that manipulate the following headers: v Message descriptor header (MQMD) on page 24 v IMS Information Header (MQIIH) on page 27 v CICS Bridge Header (MQCIH) on page 28 v Object descriptor header (MQOD) on page 29
23
Message descriptor header (MQMD)

The DataPower appliance provides the ability to determine the full set of MQMD header values. By manipulating these header values, you can alter the routing of messages by a DataPower service. You can also control the behavior of the communications with the remote queue manager (by determining a Reply-to queue, for instance). The DataPower service uses four nodes in particular to manage the routing and flow of messages. CorrelationID A unique identifier that matches a MessageID. The DataPower service compares the CorrelationID in a message to a list of outstanding MessageID values to get replies to specific requests from a given queue. MessageID A unique identifier assigned to a message by the originator of the message. ReplyToQ The name of the queue to place reply message. In the context of a client request, this is where the DataPower service places a reply. This might be specified by the client in the MQMD header of the request, might be specified by the reply from the back-end application, or might be specified by the configuration of the DataPower MQ Front Side Handler. In the context of a back-end request, this is where the back-end application server should place a reply. ReplyToQMgr The name of the queue manager managing the ReplyToQ. In the context of a client request, this is where the DataPower service connects to place a reply. This might be specified by the client in the MQMD header of the request, might be specified by the reply from the back-end application, or might be specified by the configuration of the DataPower MQ Front Side Handler object. In the context of a back-end request, this is where the back-end application server should place a reply. For complete details regarding the effect and consequences of these values as interpreted by an IBM WebSphere MQ instance, see the relevant WebSphere MQ documentation. The service processes MQMD headers as follows as the message moves from the request (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 for later 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 the message. When this is done, the gateway constructs a new header using the default values for the back-end connection. 5. The gateway can be configured to inject a new MQMD header, replacing any existing MQMD header. 6. The gateway can use a custom style sheet during policy processing to create or alter an MQMD header.
24
The service processes MQMD headers as follows as the message moves from the application (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 MQMD header. The saved ReplyToQ and ReplyToQMgr information corresponding to the request message are also provided for Front Side Reply routing. You can discover which supported MQ-related headers are contained in a message by reading the var://service/header-manifest variable. This returns a nodeset containing the names of all supported headers in the message. You can then obtain the values set for each header by using a dp:request-header() or dp:response-header() function. You can change or set the MQMD header by using the extension functions dp:set-request-header() or dp:set-response-header(). You must create an MQMD header containing all desired elements whenever you want to change or add just one. So, for example, if you wanted to change the UserIdentifier header value sent to the back-end queue, you would first need to save the entire MQMD header nodeset, change the desired value and then rewrite the MQMD header using the saved values. Here is an example MQMD request header 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 a reply message. When using this method, store a copy of the MQMD header (and other desired MQ-related headers) in a context variable during the request processing phase, using a style sheet executed in a Transform action as part of a
25
Request rule. You can then retrieve the original request MQMD header and alter it or reinstate it as needed in the response processing. Here are two examples that illustrate the request and reply style sheets. On the request rule, the style sheet retrieves the MQMD header contained in a client request to the front side of a Multi-Protocol Gateway. This style sheet stores the key 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 to construct a response header that the service uses to route the server reply to the front side client. Note that the special headers ReplyToQ and ReplyToQM specify the response queue and queue manager. These headers override the values in the MQMD header, allowing the service to put to this queue and queue manager but leave the MQMD in the message intact. If this is not the desired effect, the ReplyToQ 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)"/>
26
</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 and ReplyToQMgr : , dp:response-header(MQMD))"/> </xsl:message> </xsl:template> </xsl:stylesheet>
Setting the complete MQMD header, using variables containing the Request MQMD header, provides assured control of message routing. You can also create the complete MQMD header sent to a back-end application server queue using these functions.
IMS Information Header (MQIIH)

This example style sheet sets the MQMD and MQIIH headers to send messages to an 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 routing v 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:output method="xml"/> <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>
27
<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 the MQCIH (CICS Header Structure) as part of the message request. The example shows 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 the CICS DPL bridge
<?xml version="1.0" encoding="utf-8"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" xmlns:dp="http://www.datapower.com/extensions" extension-element-prefixes="dp" exclude-result-prefixes="dp"> <xsl:output method="xml"/> <xsl:template match="/"> <xsl:variable <xsl:variable <xsl:variable <xsl:variable <xsl:variable name="entries" select="dp:request-header(MQMD)"/> name="header" select="dp:parse($entries)"/> name="MsgId" select="$header//MsgId"/> name="CorrelId" select="$header//CorrelId"/> name="userID" select="$header//UserIdentifir"/>
 <xsl:variable name="newMQMDStr"> <MQMD> <Format>MQCICS</Format> <CorrelId> <xsl:value-of select="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">
28
<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 to local queues. The DataPower service propagates the MQOD header and the local (MQ server) queue manager has the responsibility to route the message. The MQOD 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 demonstrate how to configure a service to support a complex, clustered MQ architecture. The Figure 3 on page 30 illustrates the WebSphere MQ architecture used in this example. The routing infrastructure is comprised of multiple interactions of local and remote queues that use the MQ headers MQMD and MQOD to implement the MQ routing pattern.
29
Figure 3. Message flow in a clustered WebSphere MQ server environment
To start, the service picks up messages on a local queue that come from a remote queue. The routing headers are configured on the message such that it can be sent back to an appropriate remote response queue. The service communicates with a single local queue manager and therefore only requires a single connection channel definition. The MQOD header specifies which queue on which queue manager to send the message, but it does not specify connection information. To route to the DataPower service, an application will put a message to a service queue (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 service creates and injects an MQOD header with that information, and puts the message to an alias of the clustered queue on the local queue manager (QM_A). Next, the service reads the reply using a local queue (QA.LOOPBACK.REPLY), and finally replies to a remote queue (QB.REPLY) on a clustered queue manager (QM_B) by using another MQOD header and writing to the local queue manager (QM_A). To demonstrate various facets of this configuration, the style sheets used in the request, 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.
30
v Demonstrates custom error handling, such as sending an error reply as opposed to using the default backout logic. (See Chapter 5, Error handling, on page 45 for 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" xmlns:dp="http://www.datapower.com/extensions" extension-element-prefixes="dp" exclude-result-prefixes="dp"> <xsl:template match="/">  <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-of select="concat(dpmq://,/payload/route/queueManager, /?RequestQueue=,/payload/route/requestQueue)"/> </xsl:when> <xsl:otherwise> <xsl:value-of select="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"/>
31
</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" xmlns:dp="http://www.datapower.com/extensions" extension-element-prefixes="dp" exclude-result-prefixes="dp"> <xsl:template match="/"> <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>
32
</xsl:template> <xsl:template match="*"> <xsl:copy-of select="."/> </xsl:template> </xsl:stylesheet>
WebSphere MQ API support

The DataPower appliance supports the WebSphere MQ client API through the use of extension variables. For the user who is very familiar with the WebSphere MQ architecture and implementation details, this new capability might provide a needed flexibility. In general, these options should only be used by a WebSphere MQ expert who has a specific desire to set a certain option in an MQ call. These options only work for connections created using the dynamic mq:// URI format explained in Using an MQ URL to set back-side destinations on page 10. The options are set using the same values as detailed in the WebSphere MQ API documentation available at http://www.ibm.com/software/integration/wmq/library/. For example, suppose you need to send a message to a distribution list (a distribution 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 the ObjectName field set to one of the destination queues. The MQOD structure then points to this list and sets a field indicating the length of the list. This only works with version 2 of the MQOD structure. The MQOD structure is finally the input to the MQPUT call. The requirement can be implemented on a DataPower service by doing 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 MQMD header. 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 with no specified RequestQueue, such as:
mq://x.x.x.x/test/RequestQueue=
Here is a list of the extended header variables supported: v MQCONNX.QMgrName v MQCNO.ConnTag (z/OS only) v MQCNO.ConnectionId (output only) v MQCD.ChannelName v MQCD.Desc v MQCD.DiscInterval (inactivity timer in seconds) v MQCD.MaxMsgLength v MQCD.ConnectionName
33
v v v v v v v v v v v v
MQCD.HeartbeatInterval MQCD.LongRemoteUserId MQCD.SSLCipherSpec MQCD.SSLPeerName (indirectly sets the string pointer and length) MQCD.SSLClientAuth (value of REQUIRED or OPTIONAL) MQCD.KeepAliveInterval MQCD.LocalAddress MQCSP.UserId (indirectly sets the string pointer and length) MQCSP.Password (indirectly sets the string pointer and length) MQSCO.FipsRequired MQSCO.KeyResetCount 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 using X-MQOD-Get and X-MQOD-Put. Note that MQOD is write only; you cannot read the 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.
34
Chapter 4. Units of Work

The WebSphere MQ protocol includes the Units of Work concept. That is, the protocol includes the ability to put messages on queues within a unit of work such that those messages are made visible to other programs only when the program commits the unit of work. To commit a unit of work, all updates must be successful to preserve data integrity. This concept also includes the ability to roll back transactions. When a program performs a backout, WebSphere MQ restores the queues by removing the messages that were put on the queues by that unit of work. WebSphere MQ distinguishes between local and global units of work. Local units of work are those in which the only actions are puts to, and gets from, WebSphere MQ queues, and the coordination of each unit of work is provided within the queue manager. Global units of work are those in which other resources, such as tables in a relational database, are also updated. Transaction manager software must coordinate the global unit of work. The DataPower appliance supports only local units of work, not global units of work between the appliance and the queue manager. If different queue managers are used for the front side and the back end, two separate units of work are supported with each unit of work coordinated by the respective MQ Queue Manager object. The implementation supports units of work from front side to back 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 36 v Transactions on a service on page 38 v Common message delivery patterns on page 40 v Units of work with other protocols on page 44
WebSphere MQ client Units of Work capabilities

The standard WebSphere MQ client library supports the concept of local units of work. A unit of work begins when a WebSphere MQ client retrieves (calls MQGET) a message from a queue and ends with an MQCMIT or an MQBACK. The Queue Manager managing the queue from which the request message is retrieved automatically holds a copy of the message on the queue and allows no other client to retrieve the same message until the Queue Manager receives either an MQCMIT or an MQBACK signal on the same client connection. Upon receiving an MQCMIT, the Queue Manager deletes the message. Upon receiving an MQBACK, the Queue Manager makes the message again available to any client for retrieval. A unit of work might include more than one message. An application can specify a group of MQPUT or MQGET messages all belong to the same unit of work, or
35
transaction. There can be any number of MQPUT or MQGET messages within the unit of work. All of the messages in the group must process successfully or all of them are rolled back together. A unit of work is associated with the connection between the WebSphere MQ client and the queue manager. Multiple queues can be opened on the connection for MQGET and MQPUT operations. Because these operations take place on the same connection, 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 using MQCMIT, or rolled back using MQBACK, on the same connection. 2. When a WebSphere MQ client retrieves (MQGET) a message from a queue within a unit of work, that message remains on the queue but is not available to other clients. 3. The queue manager permanently deletes the message from the queue when the client issues an MQCMIT on the same connection. If the client issues an MQBACK, the queue manager restores the message by making it available to be 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 only when the client issues an MQCMIT on the same connection. If the client detects an error, it can issue an MQBACK. The queue manager restores the queue by removing the message that was put on the queue by that unit of work. 5. If the application failed before issuing MQCMIT or MQBACK, or the network failed, the unit of work is rolled back by the queue manager. If the application MQDISC before issuing MQCMIT or MQBACK, the queue manager will commit the unit of work. 6. Clients can determine the number of times the same message has been retrieved from a queue by examining the BackoutCount field in the MQMD. This field contains the number of times the message has been previously requested and subsequently backed out.
Units of work implementation

This section discusses how the DataPower appliance implements WebSphere MQ units of work. The MQ implementation functions as a special purpose WebSphere MQ 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 Side Handler object gets a connection to the queue manager of the Get queue from the connection cache. If no connections are available, the handler opens a new one using MQCONNX. 2. The MQ Front Side Handler object issues an MQOPEN for the Get Queue specified 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 to process. If the Units of Work property of the MQ Queue Manager object is set to 1 (that is, enabled), the MQGET is issued with SYNCPOINT=true to mark the start of a unit of work. 3. The Front Side Handler object passes the message returned by MQGET to the processing policy of the Multi-Protocol Gateway service. The service parses the message headers, which become available through various service variables.
36
The processing policy can consist of a request rule to process the request message before passing the message to any back-end server. The policy might also optionally include a response rule to process a reply message from the back-end server, and optionally an error rule to handle any errors that occur during processing. 4. When the request rule completes, the Multi-Protocol Gateway service sends the possibly altered message to the back-end server. When the service connects to the back-end server using the WebSphere MQ protocol, the gateway service employs 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 Manager object handling the transmission of the request to the back-end server has the Units of Work property set to 1, and the MQPUT is issued with SYNCPOINT=true, the MQPUT of the request message to the back-end queue is immediately followed by an MQCMIT upon success. It is important to note that the back-end MQPUT typically goes to a different queue manager than the front, and even if it is to the same queue manager as the front it would use a different connection. Therefore, the unit of work for the back-end connection is not the same as the unit of work for the front side connection. 5. The Multi-Protocol Gateway service retrieves a response from the back-end server using an MQGET issued to the queue specified by the ReplyToQueue of the destination URL. Note that although the MQGET for reply message can be issued with SYNCPOINT=true using GMO, there is no corresponding logic to later issue an MQCMIT or MQBACK and hence should be avoided. Any response rule in the processing policy matching the message executes, possibly altering the message or the message headers. 6. When the processing policy completes, the MQ Front Side Handler object is signaled and any response data from the back end is MQPUT to a front queue using 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 message v 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 Handler object 7. The MQ Front Side Handler object issues an MQCMIT on the same connection to the queue manager handling the queue from which the handler originally retrieved the message when the handler successfully places the response on the correct Reply-to queue. Note that if the statically configured Put Queue is used in step 6, the MQCMIT will apply to both the initial MQGET on the Get Queue and the MQPUT on the Put Queue. Any error that stops the processing policy processing or causes an error rule to run will result in a MQBACK issued instead of a MQCMIT. 8. When a message remains on a request (GET) queue after a failure, the MQ Front Side Handler object will again retrieve the same message. It is possible that this loop could continue indefinitely (although many queue managers detect messages left on a queue for a long time and remove them). You can handle this case automatically on the DataPower appliance if you configure the MQ Queue Manager object used by the MQ Front Side Handler object with the following property values: a. Set the Automatic Backout flag to on b. Set the Backout Threshold property to the appropriate value c. Set the Backout Queue Name property to the appropriate value
37
The MQ Front Side Handler object using the queue manager tracks the MQMD.BackoutCount header value of the MQGET of the request (GET) queue. If the MQMD.BackoutCount reaches the configured backout threshold, the MQ Front Side Handler object will move (MQPUT) the message on the queue identified by the Backout Queue Name property (typically the dead letter queue) and issue MQCMIT to the request queue to break the loop. The DataPower appliance MQ unit of work implementation is loosely coupled to allow users to meet different reliability requirements for different message delivery patterns through different configurations. Users must be careful to have the correct configuration for the message exchange pattern desired.
Transactions on a service
A transaction is a sequence of operations that end with either a commit or a roll back. A transaction commits if all the operations in the transaction succeed. A transaction rolls back if any one of the operations in the transaction fails. The DataPower appliance, acting as the WebSphere MQ client, participates in local transactions, or units of work. When enforcing transactions, when a message is fetched from a queue with an MQ GET operation, the message is not physically removed from the queue until the MQCMIT operation performs a commit. Similarly, when a message is put onto a queue with the PUT operation, the message is not available for another GET operation until the commit. Several configuration options on the DataPower appliance control when a transaction 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 of the Multi-Protocol Gateway service, front side and back end. The Units of Work setting controls front side synchronization. The Transaction and Sync parameters of the back-end MQ URL control back-end synchronization. Figure 4 on page 39 depicts a scenario where MQ operations are performed on both the front side and back end of a Multi-Protocol Gateway. In this example, two queue managers are used, A and B. The Multi-Protocol Gateway service uses an MQ Front Side Handler object to communicate with queue manager A and a static back-end MQ URL to target queue manager B. Queue manager A, on the front 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 from the queue manager on the back end, the scope of the unit of work is limited to either the front side or the back end.
38
Figure 4. Basic architecture for MQ to MQ messaging
Units of Work property

The Units of Work property manages transactionality on the front side. When this property is set to 1, retrieved messages are synchronized when they are successfully delivered to the back end destination queue and the transaction is complete. The queues in Figure 4 show the message flow when units of work is set to 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 parameter
The Transactional parameter is set to true on the back-end MQ URL to synchronize the PUT operation to the request queue with the GET operation from the reply queue. When the following conditions are true, the service uses the same connection 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 connections v 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 GET operation. The transaction commits as soon as the PUT operation to the
39
BACK.REQUEST queue completes. See Sync parameter for information on using the Transactional parameter with the Sync parameter. When the Transactional parameter is not specified, false is assumed.
Sync parameter
When the Sync parameter is set to true on the back-end MQ URL, the PUT operation to the request queue is committed immediately upon successful delivery of the message. The Sync parameter is used in conjunction with the Transactional parameter to force the transaction to use a single connection and to commit the back-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 successful delivery of the message, back-end applications can see the message on the request queue and can use the GET operation to process the message for potential delivery to BACK.REPLY. The Sync parameter must be set to true if there is both a back-end request and a reply queue. If it is not set, the back-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 options

When units of work is set to 1, you can use the MQGMO and the MQPMO syncpoint options to include GET and PUT operations in a unit of work. For instance, if you use a PUT operation with the MQPMO option set to 2 or MQPMO_SYNCPOINT, the PUT operation is committed inside a unit of work. If there are multiple PUT operations and any one fails, you can use the final action of a processing 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 patterns

The DataPower appliance supports a number of application-specific delivery patterns using all of the configuration tools available. Many sites require the ability to send a message from one WebSphere MQ queue to another (fire) and make no attempt to track the results or response (forget). The WebSphere MQ messaging system can easily support this pattern because WebSphere MQ is asynchronous. A response to a request is not required, unlike HTTP. Often, sites also require that this 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 request must result in a response. The WebSphere MQ system provides some mechanisms to support this delivery pattern, which the service uses (notably the correlation of requests to responses using the Message ID of the request set to the Correlation ID of the response). This section describes each of these two common delivery patterns. These patterns apply to scenarios in which the service retrieves messages from a WebSphere MQ
40
queue using an MQ Front Side Handler, and delivers messages to a destination WebSphere MQ queue on the back end. Figure 5 illustrates this architecture.
Figure 5. Common message delivery patterns
Independent asynchronous delivery

It is possible to implement asynchronous (fire-and-forget) delivery of requests and responses (independently in each direction). In this scenario, two separate Multi-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 errors are detected) v No Reply-to queue specified in the destination URL. This causes the Gateway to automatically send an MQCMIT to the front side request queue as soon as the MQPUT on the other side succeeds, completing the unit of work, without looking for a response. Note that the header of the message must also contain no ReplyToQ specification (that is, blank). Note that the back-end MQPUT is not on the same connection as the front side MQGET, especially if message routing is involved. However, with no response rule processing, the probability of an appliance failure between the back-end MQPUT and the front side MQCMIT is extremely small. In the unlikely event that this happens, the original front side request message will be restored by the Queue Manager automatically (due to a lost connection) and processed by the service again upon recovery of the appliance, resulting in duplicate delivery. For guaranteed asynchronous delivery with no duplicates, both Multi-Protocol Gateways can be configured to use loopback processing, thus omitting the back end altogether. Instead, the Gateway uses the Front Side Handler to place
41
(MQPUT) the message on the Front Side Handler's PUT queue after all Processing Policy actions for the request have completed. This is done by setting the write-only service variable var://service/mpgw/skip-backside to 1 (on) in the Multistep Policy. The configured Put Queue in the MQ Front Side Handler must be used as it is opened on the same connection as the MQ Front Side Handler Get Queue. The MQCMIT issued by the Gateway then commits both the MQGET and MQPUT messages atomically. This delivery pattern requires that the same MQ Queue Manager manages both the queue containing request messages (typically the front side) and the queue monitored by the back-end server (typically the back end). This delivery pattern also requires that the same MQ Queue Manager manages both the queue containing back-end response messages and the reply queue monitored by the requesting application. The two Queue Managers (one for each direction) might be different. All the policy contexts and variables for each direction are separate and not available to each other. It is not, for example, possible to correlate a request to the back-end server with the response using Message IDs and Correlation IDs.
Synchronous delivery
WebSphere MQ provides features to support synchronous (request-response transaction type) delivery patterns. Requests can be correlated with responses, and dynamic routing can be used to facilitate workflow. The DataPower appliance provides such support and other additional features such as failover across multiple queues and Queue Managers. Note that the use of these additional features does conflict with the ability to use units of work to guard against message duplication. For a synchronous delivery pattern, a single Multi-Protocol Gateway processes both the request and reply messages of the transaction. Here are the important configuration 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 the Queue Manager. v The Gateway's Processing Policy should include an error rule to handle failures encountered during the transaction. Using the reference diagram below, the following are the possible failure situations:
#1 #4 <--------- GET PUT GET <--------- PUT Request Request ---------> #2 Reply ---------> #3 Reply
Appliance failure between points 1 and 2

The Queue Manager detects failure (connections disappear) and recovers the request message on queue #1.
WebSphere MQ infrastructure failure at point 2

The DataPower service will try to issue MQBACK at #1 and start over. If MQBACK failed, the service would close the connection and start over. The closed connection will cause the Queue Manager to restore the request message.
42
Appliance failure between point 2 and point 3

The Queue Manager will restore request message at #1, but that request has been successfully delivered to queue #2 and the reply from the back-end server might be on queue #3. Because the DataPower appliance failed, the front side request Queue Manager restores the request message to the queue, even though the service has in fact successfully delivered it to the back-end server. However, when appliance recovers, it would not get the reply on queue #3 due to the use of a synchronous delivery pattern (matching response to request through IDs). The service might also be using dynamic Reply-to queues, which would no longer be known to the appliance. If the back-end server application is idempotent, the server application will produce the same result when the service again delivers the request message. The back-end server application places another reply message on its reply queue with the correct CorrelationID, and the transaction completes successfully. If the back-end application is not idempotent, the back-end server application will need to incorporate protections against receiving a request message twice.

Two kinds of errors can occur here. If the DataPower service encounters a connection 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, MQ Front Side Handler error handling will issue MQBACK at #1, causing the original request message to be restored to the queue. If the service can establish or maintain a connection to the back end Reply queue but the server application fails to produce a reply, the service will again run any matching Error rule and issue MQBACK at #1, provided the URL used to designate the back-end connection specifies 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 an MQCMIT at #1. To do this, set the Process Backend Errors property to on and set the Timeout parameter of the destination MQ URL. In addition, you must set the Response Type property of the Gateway to Non-XML. Upon timeout, because the service never gets a correlated response message from the application server, the service runs a response rule to send a specific message to queue #4. This again causes an MQCMIT to be sent to the Queue Manager of the request queue.
Appliance failure between point 3 and point 4

The reply message taken from #3 is lost. The Queue Manager handling the front side connection will detect the appliance failure and restore the request message at #1. If the backend transactionality is also turned on by appending the Transactional=true and Sync=true parameters to the backend URL, the response messages will be under backend unit of work and the response will not be committed until it is successfully delivered to the frontside reply queue. Thus, the response will not be lost in this kind of configuration.

The DataPower service will issue an MQBACK signal at #1, thus restoring the original request message to the queue, which will result in a duplicate message delivered to the back-end server. Note that the use of two separate Multi-Protocol Gateways for a synchronous delivery pattern is not recommended. The two separate Gateways cannot share transactional data, such as Message ID and Correlation ID.
43
Units of work with other protocols

The DataPower service interconnects the WebSphere MQ protocol system with other protocols, including HTTP, JMS, TIBCO EMS and FTP. This section discusses the behavior of the service when units of work is 1 and non-MQ protocols are used for either the front side connection or the back-end connection.
Front Side
The DataPower service only commits the GET of a message from the MQ Front Side Handler GET queue when the entire transaction completes successfully. This does not change when the protocol used to connect to the back-end application server is not MQ. As with a WebSphere MQ back end, errors can be handled by controlling the Process Backend Errors and Response Type properties of the Gateway, plus any Timeout parameters used in the back-end URL.
Back Side
The MQ units of work affects only the placement (PUT) of a message on the request queue of the back-end server, and is not in any way affected by the operations of a different protocol on the front side of the Gateway. The operation of the front side might be affected by the methods used to handle errors encountered when using units of work on the back-end WebSphere MQ connection. Errors can be handled by controlling the Process Backend Errors and Response Type properties of the Gateway, plus any Timeout parameters used in the back-end URL.
44
Chapter 5. Error handling

A Multi-Protocol Gateway service uses all of the standard error handling capabilities available for HTTP traffic. This includes processing policy Error rules, the On-Error action, automatic fault generation when a request or response message 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 will handle datagram (one-way) and request and reply (two-way) message traffic. The DataPower service considers a message a response when the MQMD header CorrelationId property of the response message matches the MQMD header MessageId property of the request message. The service does not use the WebSphere MQ defined message type, MQMD.MsgType, such as datagram, request, or reply, unless specifically instructed to do so within a style sheet. A service that receives both datagram and request and reply message traffic, must have a style sheet with customized error handling. The following topics highlight specific approaches to use for error handling in an integrated DataPower and WebSphere MQ environment. v Automatic Retry property v Process Backend Errors property on page 46 v v v v Automatic Backout property on page 46 The MQ reason code (MQRC) on page 47 Using the error-ignore service variable on page 49 Using an error rule on page 51
Automatic Retry property

If the network connection to a queue manager fails, the service cancels the transaction and starts error handling (such as running a configured Error rule). The service also starts the automatic retry mechanism as determined by the Automatic Retry property of the MQ Queue Manager object. When the Automatic Retry property is set to on, the DataPower service attempts to reconnect to the remote host. This setting does not affect attempts to put or get messages over an established connection. In response to a MQRC 2009 error, by default the service retries placing a message on a queue once. The number of retry attempts is determined by the Retry Interval property of the MQ Queue Manager object. If repeated connection attempts to an unresponsive remote queue manager fail, the service can instead connect to an alternative, or failover, queue manager. This alternative queue manager is defined by an MQ Queue Manager Group object. See MQ Queue Manager Group on page 72 for more information.
45
Process Backend Errors property

In general, back-end protocol level error handling is controlled by the Process Backend Errors property of the Multi-Protocol Gateway service. If this property is set to on, the service uses the response rule of the processing policy to process any message received with the error. In this way, transactions successfully complete even though an error occurred. If you do not create a response rule to handle this condition, 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 property is set to off, the service returns an HTTP 500 response to the caller unless an error rule is configured. To have the Gateway automatically generate an error message in all error cases, set Process Backend Errors to off. You can then optionally configure an error rule in the processing policy to handle the error condition.
When to use the Process Backend Errors property

When enabled, the Process Backend Errors property uses the response rule in a processing policy to handle any error messages. Because a datagram does not require a reply from the back-end application, a processing policy for this traffic most likely does not contain a response rule. The Process Backend Errors property is appropriate for services that handle request and reply messages. It is not intended to be used with services that exclusively handle datagrams unless custom error processing is desired and is configured in the response rule.
Automatic Backout property

With the Automatic Backout property enabled, the Multi-Protocol Gateway service requests the queue manager to remove a message that results in an error and place the offending message on an alternative queue available through the same queue manager. When enabled, the Automatic Backout property prevents an infinite loop if the queue manager handling the queue does not remove messages from its queues.
When to use the Automatic Backout property

Use the Automatic Backout property in conjunction with units of work so that the DataPower service reroutes any errors that are not specifically handled by other methods. For example, suppose you are using an error rule that matches specific MQ reason codes. When an MQRC is returned from the WebSphere MQ server, such as when a 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 as with a WebSphere MQ channel. In these situations, because the error does not match the error rule, the service moves the message to the backout queue specified by the Automatic Backout properties.
Enabling automatic backout

When a message remains on a request (GET) queue after a failure, the MQ Front Side Handler object retrieves the same message again, possibly causing a loop. This loop can continue indefinitely unless the queue manager detects the message
46
left on the queue and removes it. You can prevent this issue by configuring the following property values on the MQ Queue Manager object used by the MQ Front 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 server

Use the optional Retrieve Backout Settings field to determine whether to retrieve the backout threshold and backout requeue queue name from the WebSphere MQ server rather than using the Automatic Backout and associated Backout Threshold and Backout Queue Name settings on the MQ Queue Manager object. The Retrieve Backout Settings field on the MQ Front Side Handler object allows the service to retrieve the backout settings from the WebSphere MQ server. The retrieved settings override the values configured in the MQ Queue Manager object. When the MQ Queue Manager object defines backout values and the Retrieve Backout Settings is enabled, the MQ Front Side Handler object retrieves the backout threshold and backout requeue queue name from the WebSphere MQ server and compares these values to the backout values for the MQ Queue Manager object. If the WebSphere MQ server does not contain backout settings, the handler uses any existing backout values, either empty or populated, from the MQ Queue Manager object. The MQ Front Side Handler object retrieves the settings from the WebSphere MQ server at the time the MQ Front Side Handler object changes to the up state. If you modify the settings on the WebSphere MQ server queue, the MQ Front Side Handler 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 are provided on the appliance for error processing. The MQRC displays in the log when 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 1. 2. 3.
view the reason codes in the WebGUI, use the following steps: Select Administration from the navigation bar. Under the Debug heading, click View List of Event Codes. Scroll down to the mq category.
Reading the MQRC in a style sheet

Within a style sheet, you can capture MQ reason codes by using the dp:response-header extension function to read the x-dp-response-code protocol response code. If this value matches both of the following criteria, the response code is a WebSphere MQ error: v Starts with the number 2 v Has a length equal to 4
47
The following example checks the MQRC with dp:response-header(x-dpresponse-code) and depending on the reason code, issues dp:reject to trigger an error 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 sheet

While a style sheet can extract the MQRC and provide the reason code back to client, the associated text error message, such as The get call timed out before receiving any messages for MQRC 2033, is not available. To retrieve the text of the error, include a table with MQ reason codes and corresponding messages in an XML file in a style sheet. The following style sheet uses an XML file called mqrc-codes.xml that contains the MQRC and the associated error text. The style sheet captures the MQRC when used in an On error (on-error) action in the processing rule. The XML file format is provided after the style sheet.
<?xml version="1.0" encoding="utf-8"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:dp="http://www.datapower.com/extensions" xmlns:env="http://schemas.xmlsoap.org/soap/envelope" extension-element-prefixes="dp" exclude-result-prefixes="dp" version="1.0"> <xsl:output method="xml"/> <xsl:template match="/"> <xsl:variable name="mqData" select="document(local:///mqrc-codes.xml)"/> <xsl:variable name="mqrc" select="dp:response-header(x-dp-response-code)"/> <xsl:variable name="errorCode" select="dp:variable(var://service/error-code)"/> <xsl:variable name="mqrc2" select="normalize-space($mqrc)"/> <xsl:variable name="mqrc3" select="string-length($mqrc2)"/> <xsl:choose> <xsl:when test="(starts-with($mqrc, 2) and ($mqrc3 = 4))"> <xsl:variable name="mq-msg" select="$mqData/mqrc-codes/mqrc[@code=$mqrc]/@error-msg"/> <xsl:message dp:priority="error"> <xsl:value-of select="concat( ** MQ Reason Code (mqrc) ** : ,$mq-msg)"/> </xsl:message>  <dp:set-variable name="var://service/error-protocol-response" value="200"/> <dp:set-http-response-header name="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"
48
value="200 OK"/> <env:Envelope> <env:Body> <env:error> <xsl:value-of select="concat( ** MQ Reason Code (mqrc) ** : ,$mqrc)"/> </env:error> </env:Body> </env:Envelope> </xsl:otherwise> </xsl:choose> </xsl:template> </xsl:stylesheet>
The mqrc-codes.xml file used in the example contains the error text for MQ reason codes 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 2003 and 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 variable

The service variable, var://service/error-ignore, gets or sets a flag to control how the MQ Front Side Handler object processes error conditions. If the value is set and is greater than zero, the service does not run any error handling method and produces a regular response. You can then use a style sheet to implement customized manual error handling.
When to use the error-ignore service variable

Set the error-ignore service variable to 1 for datagram and request and reply traffic whenever the MQ Queue Manager object associated with the MQ Front Side Handler object is using units of work. Setting this variable will prevent an accumulation of uncommitted messages on the GET queue. For instance, consider a service with units of work enabled, Process Backend Errors enabled, and a backout queue defined. When an MQGET operation gets a message from the request queue, if any error causes an error rule to run, the MQPUT operation is not complete. Successful datagram messages complete the PUT operation to the back-side queue, but erroneous datagram messages require a manual PUT operation to a front-side backout queue. This situation might occur, for example, in a development environment where a style sheet fails to compile and the PUT operation does not complete. Therefore, the transaction does not commit and the message remains uncommitted on the GET queue. If this happens repeatedly, uncommitted messages can accumulate on the request queue and the DataPower appliance connections can hang.
49
With the error-ignore service variable set to 1, the MQPUT operation to the backout queue indicates successful completion of the transaction and the MQCMIT operation occurs, removing the message from the GET queue.
Using the error-ignore service variable in a style sheet

The sample style sheet that follows implements the error rule for the scenario described 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 sheet to disable the default backout logic. The variable also can be set with a Set variable action as the first action in the error rule. The style sheet performs the following steps: 1. Disables the default backout logic. 2. Tests whether the message originated from a remote queue manager. 3. Tests whether error handling should be performed based on the message type. 4. Sets the ReplyToQM back to the original requestqm queue manager and clears out the ReplyToQ queue. 5. Creates and injects the MQOD header with the remote queue manager and queue information. 6. Generates an error message.
<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" xmlns:dp="http://www.datapower.com/extensions" extension-element-prefixes="dp" exclude-result-prefixes="dp"> <xsl:template match="/">  <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>
50
</xsl:variable> <xsl:variable name="strMQOD"> <dp:serialize select="$xmlMQOD" omit-xml-decl="yes"/> </xsl:variable> <dp:set-response-header name="MQOD" value="$strMQOD"/> </xsl:if> </xsl:if>  <error> <xsl:copy-of select="dp:variable(var://context/mq/input)"/> </error> </xsl:template> </xsl:stylesheet>
Using an error rule

In a processing policy, an error rule is invoked when an error occurs during processing. The error rule acts as an error handler and allows you to create custom error messages. Error rules work in conjunction with the other error handling methods described in this chapter. For instance, you can invoke an error rule depending on the MQRC in the response rule as described in The MQ reason code (MQRC) on page 47. If the return code is an MQ error, invoke an error rule by using dp:reject. The error rule can generate an appropriate SOAP fault, non-XML error, or other error response, as well as send the original request message or a SOAP fault to another queue. If necessary, build an MQOD header to route to a target queue on a queue manager remote to the MQ Queue Manager object using the dp:set-response-header extension element. For instance, this might be needed to send the original request message to a remote dead letter queue. Typically, if an error rule is invoked in an MQ to MQ environment that has Units of Work enabled, set the error-ignore service variable to 1 as the first action of the error rule using a Set variable action or using the dp:set-variable extension element. The Set variable action might be followed by a Transform action or actions that determine routing based on message type or a Conditional action depending on how you want to handle the error. MQ to MQ traffic calls for different error handling depending on the type of message and whether Units of Work is enabled. The following sections list error handling methods used for MQ to MQ traffic in four different combinations of message type and Units of Work and show how an error rule is one part of error processing.
Datagram traffic with Units of Work disabled

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

Since datagram is one way traffic with no response expected, the processing policy will have a request rule but no response rule. Use the following error processing methods:
51
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 handling

Since datagram is one way traffic with no response expected, however, with customer error handling the processing policy will have both a request rule and a response rule to capture potential errors in the response header. Use the following error 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/errorignore service variable set to 1.
Request and reply traffic

With two way traffic in the request and reply traffic pattern, use a Request rule, a Response 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 Queue Manager 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/errorignore service variable set to 1.
52
Chapter 6. Additional configuration options

This chapter contains information about additional configuration options.
Asynchronous put operations

Using an asynchronous put operation, an application can put a message to a queue without waiting for a response from the queue manager. You can use this to improve messaging performance in some situations. Normally, when an application puts a message or messages on a queue, the application waits for the queue manager to confirm that it has processed the MQI request. If high qualities of service are not required, you can improve messaging performance, particularly for applications that put large numbers of small messages to a queue in a DataPower transaction, by choosing instead to put messages asynchronously. For the applications that require verification of delivery at the time of each put operation, 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 messages asynchronously to a queue for better performance. When an application puts a message 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 a DataPower service with an MQ front side handler is about to complete. If any error in any previous asynchronous call is found, a transaction in a DataPower service with an MQ Front-side handler will be rolled back in a transactional context. The DataPower appliance supports asynchronous put operations when the backend server is WebSphere MQ V7.
Authentication and authorization

A Multi-Protocol Gateway can use all of the standard AAA methods available through an AAA Policy object. For example, you can examine a WS-Security header to obtain an identity that can be used to authenticate or authorize, or both authenticate and authorize, against an external authority. In addition to the standard methods, you can also use values taken from the MQ header to implement Transport Independent AAA. This is done using a Processing Metadata object. A Processing Metadata object contains a list of the header name-value pairs. The AAA Extract Identity phase can use a Processing Metadata object. When the AAA action executes, the system extracts this list of pairs and forwards the results as a nodeset to the AAA Authentication phase. The AAA Authentication phase must
53
then use a custom style sheet to create an authentication query to some authority and pass on the results to the next phase of AAA. Consider a scenario in which all messages must contain a UserIdentity value authenticated by a local LDAP authority. In this case, the Processing Metadata object could contain just the UserIdentity node of the MQ header, which would then be returned to the custom Authentication phase style sheet.
Batch request processing

In batch request processing, the MQ Front Side Handler gets request messages of a specified 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 requests are processed, all requests in the batch will be committed. If any one of the requests fails, the batch is rolled back together. The batch size for batch request processing is configured in the MQ Front Side Handler object. The default is 0, meaning batch processing disabled. When batching 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 Managers in the front-side handler and as on the backend. Otherwise, you might get duplicate messages in the backend queue. For example, if batch processing is on when the MQ Queue Manager in the front-side handler and in backend are different and if a Multi-Protocol Gateway transaction fails, the MQBACK and MQCMIT calls are respectively issued to the MQ Queue Managers in the front-side handler and in the backend. The request in the front-side handler gets rolled back and the Multi-Protocol Gateway transaction restarts. When the second Multi-Protocol Gateway transaction is completed, the message will be committed into the backend queue again.
Message Properties
WebSphere MQ V6 messages have two parts, namely the message descriptor or headers and the message data or payload. The message descriptor is a fixed set of headers. The WebSphere MQ server processes the headers only, not the message data. You can only add the customized information in the message payload, not in the headers. WebSphere MQ V7 introduces another component into the messages. In addition to the fixed descriptor and the message data, there is a Properties component. A property is a named piece of data in name-value pair format. A property is not treated as part of the message payload. The namespace for the property name is hierarchical and splits the name into components by dots, for example car.weight. The DataPower appliance supports the processing of message properties when the backend server is WebSphere MQ V7. The feature provides the following support: v Enabling parsing for message properties v Filtering messages by properties on page 55 v Manipulating message properties in the processing policy on page 55
Enabling parsing for message properties

You can enable or disable parsing the properties of the incoming messages from a queue or subscription. If parsing is enabled, the server returns the messages with
54
their properties. If parsing is disabled, the DataPower appliance does not request the properties with the message when issuing an MQGET call, and the WebSphere MQ Server returns the messages without properties. Enable message properties parsing for the MQ Front Side Handler object with the WebGUI, the command line, or with the ParseProperties query parameter of the url-open extension element.
Filtering messages by properties

You can filter the incoming messages by the properties by specifying a selection string. The selection string filters the messages delivered to the DataPower appliance from a queue or a subscription. A selector is a variable-length string containing a SQL92 query. The selection is based on the message properties, not the payload. For example, a message selector sport = 'football' will limit messages to those that have a message property named sport with a value football. The property values have specific data types. The following data types are the supported 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 the WebGUI, the command line, or with the Selector query parameter of the url-open extension element.
Manipulating message properties in the processing policy

Message properties display in the probe and can be manipulated in custom style sheets. When the probe is turned on, use the MQMP tab to display the message properties. You can add, update, and delete message properties using a custom stylesheet in a Binary Transform (xformbin) action. The following stylesheet appends four properties to the incoming requests. The properties are of type string, integer (32 bit), 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> 
55
<dp:set-request-header name="MQMP" value="$result-mqmp"/> <xsl:copy-of select="."/> </xsl:template> </xsl:stylesheet>
Note the following points when you specify the name, type, and value for a property: v Each <Property> element in the <MQMP> header represents a message property. Use the name and type attributes to specify the property name and type respectively. Enclose the property value with the <Property> and </Property> tags. v The DataPower appliance supports the following data types for the type attribute: boolean, byte string, string, float32, float64, integer8, integer16, integer32, and integer64 types. Specify the type attribute with the following literals: 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 not specified, 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 when the 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 status

All of the standard capabilities of the Multi-Protocol Gateway can be applied to monitoring and logging of MQ transactions. These include Log Targets that send selected log messages to remote facilities off the appliance, rotating log files, the Log action that delivers a copy of an entire message to a remote facility and the standard Count and Duration monitors. Because MQ runs on a Multi-Protocol Gateway, the Service Level Monitor capability is also available. Through this capability, you can notify, shape and throttle traffic in accordance with policy rules that can filter by credentials (who is asking) and by resources (to do what). The Resource Class of an SLM policy offers the ability to select WebSphere MQ-specific attributes, such as Reply Queue Name and Request Queue Name. You implement SLM by including an SLM action in the Processing policy of the Multi-Protocol Gateway. Note that in the case of MQ, you can also log messages by sending a copy of the message to a particular remote queue by using a Results action. This queue can then simply be archived. You can use all of the standard means that are offered by a Gateway to collect status information, such as SNMP.
Ordered messaging
The DataPower appliance supports the processing of messages in the order in which they appear in the message queue. The feature provides the following support:
56
v Allows for the correct processing of messages that are order-dependent by server applications v Allows for the backing out of transactions that do not complete successfully when at least one message in the sequence is missing For additional information, see Message Processing Modes in the reference objects section of the IBM WebSphere DataPower Integration Appliance XI50: Multi-Protocol Gateway Developers Guide.
Publish and subscribe using topic strings

Publish and subscribe messaging allows users to decouple the provider of information from the consumers of that information. The sending application and receiving application do not need to know anything about each other for the information to be sent and received. A typical publish and subscribe system has more than one publisher and more than one subscriber. The provider of information is called a publisher. Publishers supply information about a subject, without needing to know anything about the applications that are interested in that information. Publishers generate this information in the form of messages, called publications that they want to publish and define the topic of these messages. The consumer of the information is called a subscriber. Subscribers create subscriptions that describe the topic that the subscriber is interested in. Thus, the subscription determines which publications are forwarded to the subscriber. Subscribers can make multiple subscriptions and can receive information from many different publishers. A topic is a character string that describes the subject of the information that is published. Topics are key to the successful delivery of messages in a publish and subscribe system. Instead of including a specific destination address in each message, a publisher assigns a topic to each message. The queue manager matches the topic with a list of subscribers who have subscribed to that topic, and delivers the message to each of those subscribers. In WebSphere MQ V7, publish and subscribe functionality is integrated into the queue manager. The MQ client publishes information directly to the WebSphere MQ server, and the WebSphere MQ server distributes the information to subscribers of that specific topic. The DataPower appliance supports publishing and subscribing to topic strings when the backend server is WebSphere MQ V7. The feature provides the following support: v Publish topic strings v Subscribe to topic strings on page 58 v Subscribe to topic strings using wildcards on page 59
Publish topic strings

In WebSphere MQ publish and subscribe, a publisher is an application that makes information about a specified topic available to a queue manager in the form of a standard WebSphere MQ message called a publication. A publisher can publish information about more than one topic. The following components specify the topic string to publish:
57
v MQ Front Side handler v Backend URL v url-open() extension element
Subscribe to topic strings

In WebSphere MQ publish and subscribe, a subscriber is an application that requests information about a specific topic from a queue manager in a publish and subscribe network. A subscriber can receive messages, about the same or different topics, from more than one publisher. Subscriptions are nondurable or durable. The following points apply to nondurable and durable subscriptions: v All subscriptions made by DataPower are managed subscriptions. The WebSphere MQ server automatically creates the subscription queue for the managed subscriptions. Managed queues are tidied up automatically in accordance with the durability of the subscription. v The MQSO option MQSO_NEW_PUBLICATIONS_ONLY is used for all subscriptions in DataPower. The subscribers do not receive any retained message that is published before the subscription is made. v For nondurable subscriptions, multiple concurrent connections will lead to the receiving of duplicate publications. For durable subscriptions, only a single user (connection) can have the named subscription at any one time. An attempt to resume a subscription currently in use by another connection will cause the call to fail with MQRC_SUBSCRIPTION_IN_USE. Thus, for both of the durable and nondurable subscriptions in DataPower, there is always only one connection working to poll the available publications. You can make a subscription through any of the following components by specifying the subscription topic for a nondurable subscription or by specifying the subscription topic and the subscription name for a durable subscription: v MQ Front Side handler v Backend URL v url-open() extension element Note: You can make a subscription to a topic or get a message from a queue, but you can not do both. If you specify a subscription topic and a GET queue, the subscription topic is ignored.
Nondurable subscriptions
Nondurable subscriptions exist only as long as the subscribing application's connection to the queue manager remains open. The subscription is removed when the subscribing application disconnects from the queue manager. In the context of DataPower, when the Multi-Protocol Gateway is down or disabled, the subscription is no longer valid and no more messages will be put to the subscriber queue. When the Multi-Protocol Gateway is up again, another subscription to the same topic will be created.
Durable subscriptions
Durable subscriptions continue to exist when the connection to the queue manager is closed. When the subscribing application disconnects, the subscription remains in place. In the context of DataPower, a queue manager will continue to send publications to the durable subscription even when the Multi-Protocol Gateway is down. These saved publications will be received later when the Multi-Protocol
58
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 used to identify a subscription. The default option MQCO_KEEP_SUB is used for closing a durable subscription in DataPower. When closing a durable subscription, the handle to the subscription is closed but the subscription made is kept on the WebSphere MQ server. Publications will continue to be sent to the subscription queue. To permanently delete a durable subscription, use the WebSphere MQ Explorer or the MQSC commands.
Subscribe to topic strings using wildcards

By specifying a subscription topic string, for example /ibm/datapower, you can create a durable or nondurable subscription that registers interest in an explicitly-specified single topic string and that polls messages that are published to the topic string to which it is subscribed. By using wildcards in the subscription topic string, the created subscribers can subscribe to multiple topics at one time. In WebSphere MQ, two wildcard schemes are supported: topic-based wildcard scheme and character-based wildcard scheme. In the topic-based wildcard scheme, wildcards operate on topic elements within the topic string. DataPower supports the topic-based wildcard scheme. Use wildcard topic strings in the backend URL or in a dp:url-open extension element by specifying the SubscribeTopicString parameter or in the MQ Front Side 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 using wildcards: 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 Proxy

The Web Service Proxy service can also integrate with the WebSphere MQ messaging system. Here are some of the methods available to create this configuration. 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 a corresponding 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 the format of /<MQ FSH name>?RequestQueue=<GetQ>&ReplyQueue=<PutQ>. If you don't want to place any response on a corresponding reply queue, specify the URI in the format of /<MQ FSH name>?RequestQueue=<GetQ>. v The Proxy can employ a statically-defined back end that uses WebSphere MQ queues to put requests and get responses. Because most WSDL files indicate an HTTP endpoint, you might need to manually change the Proxy type property to static backend from the typical default of static-from-wsdl. You will then need to specify the backend URL using the MQ URL syntax. v The Proxy can employ a Results (or Results Async) action in the Processing Policy that sends messages to a WebSphere MQ queue.
| | | | |
59
MQ and JMS
It is possible to transport JMS messages over an WebSphere MQ system. In this case, some architectures allow for the selection of WebSphere MQ messages based on values contained in the JMS message headers. The DataPower service views JMS messages over MQ as illustrated in Figure 6.
Figure 6. JMS messages over MQ
The DataPower service recognizes and parses JMS headers in WebSphere MQ messages. Although you can use the service to read and select messages based on JMS header values regardless of release, the methods will differ. It is possible to select WebSphere MQ messages based on JMS header values by using a Binary Transform operation on the WebSphere MQ message body to extract the JMS header values into an XML nodeset. This extracted nodeset can then be examined for the desired attributes. You can examine the nodeset contained in the var://service/header-manifest variable, which contains the parsed JMS headers. This includes headers in the following 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 standard MQMD header structure. The JMS header consists of the MQRFH2 structure followed by a number of short XML documents. The system now adds these XML documents to the header manifest as X-MQRFH2-Data-xxxx headers. The appliance supports WebSphere MQ messages with one MQRFH2 header. If a WebSphere MQ message contains multiple MQRFH2 headers, only the last one is parsed.
Table 4. Header manifest Header MQMD Value <MQMD>...</MQMD>
60
Table 4. Header manifest (continued) Header MQRFH2 X-MQRFH2-Data-0 X-MQRFH2-Data-1 Value <MQRFH2>...</MQRFH2> <mcd><Msd>jms_text</Msd></mcd> <jms><Dst>queue:///Q2</Dst><Tms>1164748514102</Tms></ jms>
Legacy WebSphere MQ service objects

The DataPower appliance includes the following WebSphere MQ-related services that predate the Multi-Protocol Gateway: v WebSphere MQ Gateway v WebSphere MQ Host v WebSphere MQ Proxy These objects should no longer be used for WebSphere MQ integration. The Multi-Protocol Gateway and the Web Service Proxy provide all of the functionality that 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 Web Service Proxy, do not use these variables. For a list of these variables, see the section on legacy MQ service variables in the IBM WebSphere DataPower SOA Appliances: Extension Elements and Functions Catalog.
61
62

This chapter contains information about creating objects that are referenced, or associated with, the configuration of other objects.
Configuring a WebSphere MQ handler

An MQ Front Side Handler object handles MQ protocol communications with DataPower services. This handler is available on the following appliances only: v DataPower appliance v B2B Appliance XB60 v Low Latency Appliance XM70 For additional information on DataPower integration with WebSphere MQ, see IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ. This section provides information about configuring an MQ Front Side Handler.
High-level configuration
To 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 and subscribe configuration on page 65 for details. 5. Define the properties and headers configuration. See Defining the properties and 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 configuration

To 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 v To make inactive, click disabled. 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.
63
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 or hexadecimal format. The value is passed directly to the MQ API. The default is 4097 (decimal value for the MQGMO_WAIT and the MQGMO_SYNCPOINT_IF_PERSISTENT options). See the MQGMO_* (Get Message Options) topic in the Constants section of the WebSphere MQ Information Center for details. When a message is too large for a queue, an attempt to put the message on the queue fails. Segmentation is a technique that allows the queue manager or application to split the message into smaller pieces, and place each segment on a queue as a separate physical message. The application that retrieves the message can either handle the multiple segments one-by-one, or request the queue manager to reassemble the segments into a single message that is returned by the MQGET call. The reassembly request is achieved by specifying the MQGMO_COMPLETE_MSG option (65536) on the MQGET call, and by providing a buffer large enough to accommodate the entire message. Note: Ensure that the associated queue manager supports the MQGMO_COMPLETE_MSG option. On z/OS, MQ queue managers do not support segmentation. On other operating systems, MQ queue managers might not be configured to support segmentation. 9. In the Polling Interval field, specify the number of seconds before an MQGET operation returns if no messages are available. The next attempt will be performed immediately. Setting a low value will help to detect quickly network connectivity issues and queue manager power shutdown. At the same time, a low value will increase network traffic. The minimum is 1. The default is 30. 10. Use the Retrieve Backout Settings field to determine whether to retrieve the backout threshold and backout queue name from the MQ server. on Retrieves backout settings from the MQ server and compares to the backout values set in the MQ Queue Manager object. On retry, the DataPower appliance uses the higher priority backout settings from the MQ server. If MQ server does not contain backout settings, the appliance uses existing backout properties, either empty or populated, that are stored in the MQ Queue Manager object. If there are no backout properties, backout is disabled.
(Default) Do not retrieve backout settings from the MQ server. If these properties already exist in the MQ Queue Manager object, the appliance use those values. 11. Use the Use Queue Manager in URL field to determine whether the var://service/URL-in variable returns the name of MQ Queue Manager or the name of the MQ Queue Manager Group when this configuration defines a queue manager group as the queue manager. off 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 for ISO-8859-1 (latin-1). For a list of CCSID, see the following web site: http://www.ibm.com/software/globalization/ccsid/ccsid_registered.jsp
64
This property is meaningful only when the MQ Queue Manager object has the Convert Input property set to on.
Defining the publish and subscribe configuration

To 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 configuration

To 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 off Specifies that parsing is enabled. The WebSphere MQ server returns the messages with the properties. (Default) Specifies that parsing is disabled. The DataPower appliance does not request the properties with the message when issuing an MQGET call, and the WebSphere MQ server returns the messages without the properties.
For additional information, see the section on Message Properties in IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ. 2. In the Selector field, specify the selector as a variable-length string containing a SQL92 query. For additional information, see the section on Message Properties in 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 MQMD header is parsed. The following headers after MQMD, when selected, can be removed: 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 structure from which to extract the Content-Type header. None (Default) No header
MQRFH MQRFH header MQRFH2 MQRFH2 header

65
5. If Header to Extract Content-Type is not None, specify the XPath expression to extract the value of the Content-Type header in the XPath expression to extract Content-Type from MQ header field. Click XPath Tool for help building the XPath expression.
Defining the advanced configuration

To 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 off Specifies that the put operation is asynchronous. (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 Manager
In WebSphere MQ, distributed send queues and receive queues are managed by a queue manager. A queue manager provides messaging services in the following ways: v Periodically monitoring and polling queues v Ensuring that sent messages are directed to the correct receive queue or are routed to another queue manager
Identifying the MQ server

The host for an MQ queue manager is the MQ server where the queue manager is running. The value for the Host Name field includes the listening port on the server. If you do not specify the port, the default is 1414. The value of the host depends on IP family. For IPv4 The value for the Host Name field can be in one of the following formats: v address:port For example, 10.10.1.2:1414 v address(port) For example, 10.10.1.2(1414) v address For example, 10.10.1.2 v host-name:port For example, server1:1414 v host-name(port) For example, server1(1414) v host-name For example, server1 For IPv6 The value for the Host Name field can be in one of the following formats: v [address]:port For example, [2202::148:248]:1414 v address(port) For example, 2202::148:248(1414) v address For example, 2202::148:248 v host-name:port For example, server1:1414 v host-name(port) For example, server1(1414) v host-name For example, server1
66
Securing communication with remote queue managers

Before configuring an MQ Queue Manager object, determine whether to support secure 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 DataPower appliance uses the selected SSL Proxy Profile. Note: To integrate with a MQ for z/OS, you must use an instance of the SSL Proxy Profile object.
Securing with GSKit

To 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 key database file has an associated stash file. The stash file holds encrypted passwords that allow programmatic access to the key database. The stash file must reside in the same directory as the key database file, must have the same file stem, and must end with the sth file extension. For example, if the key database 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 object

To define secure communication with an SSL Proxy Profile, select an SSL Proxy Profile from the SSL Proxy Profile list. Table 5 maps the relationship between the SSL Cipher Specification property and setting required on the Crypto Profile of the SSL Proxy Profile that is assigned to the MQ Queue Manager. Use this information when configuring the SSL Proxy Profile to communicate with the MQ Queue Manager.
Table 5. Mapping of the SSL Cipher setting the Crypto Profile settings
SSL Cipher Specification setting NULL_MD5 NULL_SHA RC4_MD5_EXPORT RC4_MD5_US RC4_SHA_US RC2_MD5_EXPORT DES_SHA_EXPORT RC4_56_SHA_EXPORT1024 DES_SHA_EXPORT1024 TRIPLE_DES_SHA_US Crypto Profile settings Cipher: NULL-MD5 Options: OpenSSL-default+Disable-TLSv1 Cipher: NULL-SHA Options: OpenSSL-default+Disable-TLSv1 Cipher: EXP-RC4-MD5 Options: OpenSSL-default+Disable-TLSv1 Cipher: RC4-MD5 Options: OpenSSL-default+Disable-TLSv1 Cipher: RC4-SHA Options: OpenSSL-default+Disable-TLSv1 Cipher: EXP-RC2-CBC-MD5 Options: OpenSSL-default+Disable-TLSv1 Cipher: DES-CBC-SHA Options: OpenSSL-default+Disable-TLSv1 Cipher: EX1024-RC4-SHA Options: OpenSSL-default+Disable-TLSv1 Cipher: EXP1024-DES-CBC-SHA Options: OpenSSL-default+Disable-TLSv1 Cipher: DES-CBC3-SHA Options: OpenSSL-default+Disable-TLSv1
67
Table 5. Mapping of the SSL Cipher setting the Crypto Profile settings (continued)
SSL Cipher Specification setting TLS_RSA_WITH_AES_128_CBC_SHA TLS_RSA_WITH_AES_256_CBC_SHA AES_SHA_US Crypto Profile settings Cipher: AES128-SHA Options: OpenSSL-default Cipher: AES256-SHA Options: OpenSSL-default Cipher: AES128-SHA Options: OpenSSL-default
Defining the timeout for dynamic connections

The Cache Timeout property defines the number of seconds that the appliance retains (keeps alive) a dynamic connection in the connection cache. This timeout value must be greater than the negotiated heartbeat interval but less than the keep alive 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 define the starting value for the negotiation. v The keep alive (timeout) interval is on the remote MQ server. The KAINT attribute on the MQ server defines the timeout value for a channel. Not all channels have an explicit keep alive interval on the MQ server. Some queue managers use an automatic timeout setting (the KAINT attribute set to AUTO). In these cases, the keep alive interval is the negotiated heartbeat interval plus 60 seconds. When an inactive connection reaches this threshold, the appliance removes that dynamic connection from the cache. When the cache no longer contains dynamic connections, the appliance deletes the dynamic queue manager. Without a dynamic queue manager, there is no connection with the remote MQ server. Note: The timeout value for the Cache Timeout property is the only way to configure a timeout value from the appliance to the MQ server. No other configuration setting on the appliance can time out an MQ connection.
Enabling units of work

The appliance supports only local units of work, not global units of work between the appliance and the remote MQ queue manager. When using synch points, the same 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 MQ systems require synchronization on each unit of work. In other words, the system commits the entire transaction or rolls back the entire transaction. This type of synchronization ensures that the remote system and the application with which it interacts 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, not the entire transaction. When specified, the appliance does not remove the message that it gets from a queue until it completes its transaction using that message (such as placing the message on a server queue for processing). If the transaction fails and the message is left available on the queue, the appliance can attempt to get the message and process it again.
68
If not enable, undeliverable messages are discarded. Higher level protocols are responsible for detecting and for retransmitting any undeliverable message within the transaction. 2. Set Automatic Backout to on. This value enables the automatic backout of poison messages. A poison message is any message that the receiving application does not know how to process. Usually an application rolls back the GET of this message, which leaves the message on the input queue. However, the backout count (MQMD.Backoutcount) is increased. As the MQ Queue Manager object continues to re-get the message, the backout count continues 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 a custom style sheet in the request rule. 3. Specify the number of reprocessing attempt per message in the Backout Threshold field. Use an integer greater than 1 to specify the maximum number of reprocessing attempts per message. The default is 1. The count starts at 0, which accounts for the initial processing attempt. The default value specifies two attempts: the initial attempt and a single reprocessing attempt. 4. Specify the name of the backout queue in the Backout Queue Name field. The backout queue contains messages that cannot be processed or delivered. Typically, the name of the queue is SYSTEM.DEAD.LETTER.QUEUE. Messages that have exceeded the backout threshold are rerouted to this queue.
Configuring Queue Manager objects

To configure queue managers that makes the DataPower appliance aware of the location 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. 5. 6. 7. v To make active, click enabled. Optional: In the Comments field, enter a descriptive summary. 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. 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 to this queue manager. Optional: In the Channel Name field, specify the name of the channel. Use as an alternative to the default SYSTEM.DEF.SVRCONN. In the Channel Heartbeat field, specify the approximate time in seconds between heartbeat flows on a channel when waiting for a message on a queue. If 0, no heartbeat flow is exchanged when waiting for a message on the channel. This setting does not set the heartbeat on the channel. This setting negotiates the heartbeat value with the channel. The greater of the two values is used. Optional: In the User Name field, specify a plaintext string that identifies this client to the MQ server.
8. 9.
10.
69
11. Optional: In the Maximum Message Size field, specify the size in bytes of the largest message to process. Use a value that is equal to or greater than the MaxMsgLength 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 appliance retains a dynamic connection in the connection cache. Use a value that is greater than the negotiated heartbeat interval but less than the keep alive interval. 13. Determine whether to support transactions (units of work) with roll back support. 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 a single TCP/IP connection. In WebSphere MQ Version 7 or later, you can use the shared conversations feature to control the number of connections between the DataPower appliance and the MQ server. To enable conversation sharing, specify a value that 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 queue manager. v To secure with artifacts from GSKit: a. With the SSL Key Repository controls, select the location of the key database 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. This conversion is done by the remote queue manager, not the DataPower appliance. 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 Queue Manager object when it initially tries to connect to the queue manager. Setting a short retry interval, the number of times to attempt to connect at the short interval, and a long retry interval allow you to configure the DataPower appliance to handle repeated connection failures such as when the queue manager is unavailable for maintenance purposes.
| | | | | | | | | |
70
a. Set Automatic Retry to define whether to attempt to reconnect to the remote 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 PUT or GET messages over established, active connections. 2) In the Retry Attempts field, specify the number of attempts to retry the failed connection. After the reaching this number of attempts, use the long retry interval. If the long retry interval is disabled, the queue manager repeatedly attempts to reconnect using the retry interval setting. 3) In the Long Retry Interval field, specify the number of seconds between retrying the failed connections after the number of retry attempts is reached. This value (long retry interval) must be greater than the value of the short interval. To disable, change the retry attempts setting to 0. 4) In the Reporting Interval field, specify the number of seconds between the creation of error messages when failed connections are retried. This setting filters the generation of identical error messages to MQ logging target. 19. Set Alternate User to determine whether to use MQOD.AlternateUserId or MQMD.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 to port 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 setting has the same effect as setting the MQCCSID environment variable for an MQ client. 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 user ID and password. You can specify the MQCSP connection security parameters structure on an MQCONNX call. Before using the MQCSP support, you need to define a security exit in the MQ Queue Manager on the MQ server. Ensure that your MQCSP user ID and password in the security exit are consistent with what you input in the MQ Queue Manager object configuration. Either an inconsistent MQCSP user ID or an inconsistent password causes a failure of connection between the DataPower appliance and the MQ server. Take the following actions to define your MQCSP configuration in the MQ Queue Manager: a. Click the Advanced tab. b. In the MQCSP User ID field, specify the user ID value of the MQCSP connection security parameter.
| | | | | | | | | | | | | | | |
71
| | | | | | | | |
c. In the MQCSP Password field, specify the password value of the MQCSP connection security parameter. Notes: a. If neither the MQCSP user ID or the password is defined, the DataPower appliance connects to the MQ server without MQCSP settings. b. If only one is defined, a warning occurs and the MQ Queue Manager object is not up. c. If both are defined but one is not consistent with that defined on the MQ server, 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 Group

An instance of the MQ Queue Manager Group object implements a failover configuration. These objects provide connection redundancy in the event of a critical queue manager or bus error that results in a loss of connectivity between clients and remote queue managers. An MQ Queue Manager Group object defines one primary queue manager and one or more backup queue managers. The appliance periodically monitors the status of the primary queue manager. In the event of failure, the appliance selects a backup queue manager to assume the role of the primary queue manager. When the original primary queue manager returns to service, the appliance reassigns this queue manager to its former role. For information about creating MQ Queue Manager objects, see MQ Queue Manager on page 66. | | | | | | | | | | | | | | | | | | | |
Working with the multi-instance feature in the WebSphere MQ server

In WebSphere MQ server Version 7.0.1 or later, you can configure multi-instance queue managers for the failover in the WebSphere MQ server. The active instance and the standby instance of a queue manager reference the same queue manager data and logs in shared network storage. When the active instance fails, the standby instance automatically takes over the data and logs from the active instance, and accepts re-connections from clients and channels. To work with the multi-instance feature in the WebSphere MQ server for the failover in the DataPower appliance, you need to configure your MQ Queue Manager Group object with the multi-instance queue managers in the WebSphere MQ server. Connect the primary queue manager to one of the instances of a queue manager in the MQ server, and the backup queue manager to the other instance. If the active instance in the MQ server fails, the DataPower appliance selects the queue manager connected to the standby instance, and this queue manager automatically takes over all the data and logs from the queue manager connected to the original active instance. For more information about multi-instance queue managers, see http://publib.boulder.ibm.com/infocenter/wmqv7/v7r0/index.jsp?topic=/ com.ibm.mq.amqzag.doc/fa70150_.htm.
72
Configuring MQ Queue Manager Group objects

To 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.
73
74
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 in other countries. Consult your local IBM representative for information about the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements or changes in the product(s) or the program(s) described in this publication at any time without notice.
Trademarks
IBM, the IBM logo, DataPower, and WebSphere are registered trademarks of the International Business Machines Corporation in the United States or other countries. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol ( or ), these symbols indicate U.S. registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at Copyright and trademark information at www.ibm.com/legal/ copytrade.shtml. Adobe is either a registered trademark or trademark of Adobe Systems Incorporated in the United States, and/or other countries.
75
Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Other product and service names might be trademarks of IBM or other companies.
76
Index A
actions MQ Header modifying reply queue 22 modifying reply queue manager 23 modifying request message headers 21 modifying response message headers 22 overview 20 retrieving responses with correlation ID 21 retrieving responses with message ID 21 IP addresses MQ queue managers italics typeface vi 66 MQ Queue Manager (continued) sharing conversations 70 MQ Queue Manager Group backup queues 72 configuring 73 primary queue 72 MQ queue managers automatic backout 68 backup 72 dynamic connections timing out 68 failover configuration 72 host name 66 IP addresses 66 key database file 67 primary 72 securing communication 67 securing with GSKit 67 securing with SSL Proxy Profile 67 stash file 67 synch points 68 transactions 68 units of work 68 z/OS integration 67 MQ request messages modifying message headers 21 specifying correlation ID 21 specifying message ID 21 MQ response messages modifying headers 22 modifying reply queue 22 modifying reply queue manager 23 MQ servers host name 66 IP addresses 66 KAINT attribute 68 keep alive interval 68 MQCO_KEEP_SUB 58 MQMD.UserIdentifier 71 MQOD.AlternateUserId 71 MQRC_SUBSCRIPTION_IN_USE 58 MQSO_NEW_PUBLICATIONS_ONLY option 58
K
KAINT attribute, MQ server key database file MQ 67 68
L
licensing sending inquiries 75
B
backout queue, MQ 68 backup queue managers, MQ 72 basic configuration MQ Front Side Handler 63 bold typeface vi
M
messages poison, MQ 68 monospaced typeface vi MQ error 2010 70 MQ error 2110 70 MQ Front Side Handler 63 advanced configuration 66 basic configuration 63 configuration 63 properties and headers configuration 65 publish and subscribe configuration 65 MQ Get Message Options (GMO) MQGET options 64 MQGMO_* 64 MQ header action modifying reply queue 22 reply queue manager 23 request message headers 21 response message headers 22 overview 20 retrieving responses with correlation ID 21 with message ID 21 MQ headers MQMD UserIdentifier 71 MQOD AlternateUserId 71 MQ integration GSKit 67 z/OS 67 MQ Queue Manager automatic retry 70 configuring 69 error 2010 70 error 2110 70 MQCSP password 71 MQCSP support 71 MQCSP userID 71 retry behavior 70
D
documentation conventions, typefaces durable subscriptions 58 vi
E
error 2010, MQ 70 error 2110, MQ 70
F
failover configurations MQ queue managers 72 files MQ key database file 67 stash file 67 Front Side Handler object pages MQ 63
N
nondurable subscriptions notices 75 58
G
GSKit, MQ integration 67
O
object pages Front Side Handler MQ 63 objects MQ Queue Manager 69 MQ Queue Manager Group
H
header-manifest variable 60
73
I
intellectual property 75 Copyright IBM Corp. 2006, 2010
77
P
patents 75 poison messages, MQ 68 primary queue manager, MQ 72 publish MQ Front Side Handler 65
Q
queue managers See MQ queue managers
S
software requirements 1 SSL Proxy Profile MQ Queue Manager 67 stash file MQ 67 subscribe MQ Front Side Handler 65 subscriptions durable 58 nondurable 58 synch points, MQ 68 SYSTEM.DEAD.LETTER.QUEUE
68
T
topic strings subscribing 58 wildcards 59 trademarks 75 transactions MQ automatic backout 68 MQMD.Backoutcount 68 transactions, MQ 68 typeface conventions vi
U
units of work, MQ 68
V
variables header-manifest 60
W
WebSphere MQ supported version wildcards topic strings 59 1
Z
z/OS MQ integration 67
78
Printed in USA

Data Power Integrating With MQ

Uploaded by

Copyright:

Available Formats

Data Power Integrating With MQ

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Data Power Integrating With MQ

Uploaded by

Copyright:

Available Formats

What is the document about?

What is the document about?

What are some of the MQ objects discussed?

What are some of the MQ objects discussed?

DataPower SOA Appliances

Integrating with WebSphere MQ

DataPower SOA Appliances

Integrating with WebSphere MQ

Chapter 5. Error handling. . . . . . . 45

Chapter 3. MQ header values . . . . . 19

Chapter 6. Additional configuration options . . . . . . . . . . . . . . 53

Chapter 4. Units of Work . . . . . . . 35

Appendix. Referenced objects

Notices and trademarks . . . . . . . 75

DataPower SOA Appliances: Integrating with WebSphere MQ

File naming guidelines

Object naming guidelines

Copyright IBM Corp. 2006, 2010

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

monospaced Identifies user-supplied input or computer output.

DataPower SOA Appliances: Integrating with WebSphere MQ

Multi-Protocol Gateway service

Configuration for integration with WebSphere MQ

Copyright IBM Corp. 2006, 2010

MQ Front Side Handler object

MQ Queue Manager object

DataPower SOA Appliances: Integrating with WebSphere MQ

MQ Queue Manager Group

Figure 1. Basic architecture for HTTP to MQ messaging

Figure 2. Basic architecture for MQ to HTTP messaging

DataPower SOA Appliances: Integrating with WebSphere MQ

DataPower SOA Appliances: Integrating with WebSphere MQ

DataPower SOA Appliances: Integrating with WebSphere MQ

Back-side request routing

Copyright IBM Corp. 2006, 2010

Using an MQ URL to set back-side destinations

Syntax for a static MQ URL

DataPower SOA Appliances: Integrating with WebSphere MQ

DataPower SOA Appliances: Integrating with WebSphere MQ

Using the MQ Helper to build a static MQ URL

Using a static MQ URL in a style sheet

DataPower SOA Appliances: Integrating with WebSphere MQ

Syntax for a dynamic MQ URL

Front Side reply routing

DataPower SOA Appliances: Integrating with WebSphere MQ

DataPower SOA Appliances: Integrating with WebSphere MQ

Chapter 3. MQ header values

Injecting and suppressing headers

DataPower SOA Appliances: Integrating with WebSphere MQ

Modifying MQMD request headers

Retrieving responses by message ID or by correlation ID

Modifying MQMD response headers

Modifying the reply queue for responses

DataPower SOA Appliances: Integrating with WebSphere MQ

Modifying the queue manager for responses

Using MQ headers with custom style sheets

Message descriptor header (MQMD)

DataPower SOA Appliances: Integrating with WebSphere MQ

DataPower SOA Appliances: Integrating with WebSphere MQ