Data Power Integrating With Mq

DataPower SOA AppliancesVersion 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. . . . . . Error handling. . . IMS Information Header (MQIIH) . . . . . . . . . Syntax for a dynamic MQ URL . . . . HTTP to MQ . . . 35 WebSphere MQ client Units of Work capabilities Units of work implementation . . . . When to use the Process Backend Errors property Automatic Backout property. . 1 Software requirements . . . . . . MQ header action . . . . Basic MQ architecture . . . Configuration for integration with DataPower service . . Referenced objects . . . . . . . . . . . . . . 1 1 1 2 2 2 3 3 3 5 5 6 Chapter 5. Datagram traffic with Units of Work enabled . . . . . . . Filtering messages by properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 . . . 10 . . . . . . . . 2006. . . . . . . . . Retrieving responses by message ID or by correlation ID. . . . . . . . . . . . . . . . . . vi Common message delivery patterns . . . Ordered messaging . . . . . . . . . . . . . . . . . Authentication and authorization . . . . . . Using the MQ Helper to build a static MQ URL Using a static MQ URL in a style sheet . . . 20 . . . . . . logging. . . MQ . . . . . . . 10 13 . . .Contents Preface . . . . . . . . . . . . . . . . . MQ Queue Manager Group . . . . . . When to use the error-ignore service variable . . Processing policies . . . . . . . Batch request processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 22 22 23 23 24 27 28 29 33 Chapter 6. . Using the backout settings from the WebSphere MQ server . . . High-level configuration . . . . . . . . . . . MQ header values . . . . Request and reply traffic . . . . . . . . . . . . Enabling automatic backout . . . . . . . . . . . . . . . . . . . Multi-Protocol Gateway service . . . . . . . . Modifying MQMD response headers . . . . . . . . Routing . . . . Datagram traffic with custom error handling . . . Front Side reply routing . . Defining the publish and subscribe configuration iii . v Typeface conventions . . . . . . . . . 40 41 42 44 44 44 Chapter 1. Units of Work . . . . . . . . MQ and JMS . . . . . 9 . . . . . . . . . . . . . . . Using an MQ URL to set back-side destinations . . . . . . . Transactional parameter . 9 Back-side request routing . . . . Using the error-ignore service variable in a style sheet . . Defining the basic configuration . . . . . Independent asynchronous delivery Synchronous delivery . Manipulating message properties in the processing policy . . . 21 . Process Backend Errors property . . . . 35 36 38 39 39 40 40 Appendix. . . . . Object descriptor header (MQOD) . . . . . Front Side . 2010 . . . . . . . . . . . . . Publish and subscribe using topic strings . . . . . . . . . . . v Object naming guidelines . . . . . 15 . . . MQ Front Side Handler object MQ Queue Manager object . . . . . . . Modifying the queue manager for responses Using MQ headers with custom style sheets . Using an error rule . . . . . . . . . . . . . . . . . . . WebSphere MQ API support. Message Properties . . . . . . . Returning the MQ error message in a style sheet Using the error-ignore service variable . . . . . 19 . . . . . . . . . 53 53 54 54 54 55 55 56 56 57 57 58 59 59 60 61 Chapter 4. © Copyright IBM Corp. . . Units of work with other protocols . . . . . . . . . . . Monitoring. . . . . . Message workflow . 45 46 46 46 46 46 47 47 47 48 49 49 50 51 51 51 52 52 Chapter 2. . . . . . . 63 63 63 63 65 Configuring a WebSphere MQ handler . . . . . Sync parameter . . . . . . . . . . . . . . . . . . . . Reading the MQRC in a style sheet . . . . . . . . Modifying MQMD request headers . 53 Asynchronous put operations . . . . . . . . . . When to use the Automatic Backout property . . . . 45 Automatic Retry property . . . . . . . . Additional configuration options . . . . . WebSphere . . . . . . . . . . Legacy WebSphere MQ service objects . Introduction . . . . . . MQ to HTTP . . . . . . . Modifying the reply queue for responses . . . . . . . . . . . . . . Subscribe to topic strings . . and status. . . . . . CICS Bridge Header (MQCIH) . . Enabling parsing for message properties. . . . . Units of Work property . Message descriptor header (MQMD) . . . . . . 14 . . . . . . . . . Transactions on a service . . . . . . . . . . . . . . . . v File naming guidelines . Back-side destinations . . . . . . . . . . . . . . . . . 16 Chapter 3. . . MQGMO and MQPMO syncpoint options . . . . . Back Side . . . . . . . . . . . . . 19 Injecting and suppressing headers . . . . Subscribe to topic strings using wildcards Using MQ with a Web Service Proxy . . . . . . v Intended audience . Publish topic strings . . . . . . . . . . . . Datagram traffic with Units of Work disabled . . . . . . The MQ reason code (MQRC) . . . . . Syntax for a static MQ URL . . . . . 72 Working with the multi-instance feature in the WebSphere MQ server . . . . . . . . . . . . Defining the timeout for dynamic connections . Securing communication with remote queue managers . . . . . . . . . . . . . . . 75 Index . . . 65 66 66 66 67 68 68 69 | | MQ Queue Manager Group . . . . . . . . . 72 Configuring MQ Queue Manager Group objects 73 Notices and trademarks . MQ Queue Manager . . . .Defining the properties and headers configuration . . . . . . . . . . . . . . . . . . . Identifying the MQ server . . . . . . . . Defining the advanced configuration . . . . . . . . . Configuring Queue Manager objects . . . . . . . . . . . . . . . . 75 Trademarks . . . . . . . . . . . . . . . . . . . . 77 iv DataPower SOA Appliances: Integrating with WebSphere MQ . . . Enabling units of work . . store:. (period) Note: Names cannot contain two consecutive periods (. 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 . If the directory (or domain) supports subdirectories. and associated referenced objects related to integrating with WebSphere MQ on a DataPower appliance. the path to the file can have a length of 4000 characters. Object naming guidelines The object name must be unique in the object namespace. When you create a domain. The name of the base file can be up to 128 characters in length.). Intended audience This document is intended for administrators and application developers who manage the configuration of services. and Networking infrastructure investments.Preface IBM® WebSphere® DataPower® SOA Appliances are purpose-built. and temporary:. The base file is the part after the name of the DataPower directory. 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. security. help secure. 2010 v . Examples of directories are local:. easy-to-deploy network appliances that simplify. objects. 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) © Copyright IBM Corp.. pragmatic approach to harness the power of SOA while simultaneously enabling you to leverage the value of your existing application. These appliances offer an innovative. 2006. its name is the base file name in several DataPower directories when viewed from the default domain. and accelerate your XML and Web Services deployments while extending your SOA infrastructure. .). programming keywords. and GUI controls. Identifies words and phrases used for emphasis and user-supplied variables. (period) Note: Names cannot contain two consecutive periods (. Typeface conventions The following typeface conventions are used in the documentation: bold italics Identifies commands.v . monospaced Identifies user-supplied input or computer output. vi DataPower SOA Appliances: Integrating with WebSphere MQ . 0. logging and customization services available to the messages flowing through the service to and from the WebSphere MQ system. handling MQ headers. such as HTTP or TIBCO EMS. v An MQ Queue Manager object to define the communication between a service and a WebSphere MQ queue manager. The WebSphere MQ Information Center for each version is available at http://www. See “DataPower service” on page 2. 2010 1 . and error processing.com/software/integration/wmq/library/. such as the Multi-Protocol Gateway service. v A DataPower service to define the architecture. 2006. Messages originating within or outside of a WebSphere MQ system can flow easily to and from another WebSphere MQ system or other messaging system. The service does not store or hold messages outside the context of a single transaction. the Multi-Protocol Gateway service can also apply the full range of transformation. Configuration for integration with WebSphere MQ To define integration with WebSphere MQ. 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.0 and 7. © Copyright IBM Corp. such as HTTP or TIBCO EMS. you must configure objects on the DataPower appliance. In addition to the messaging system bridging. the DataPower appliance uses a service. See “MQ Front Side Handler object” on page 2. The following list of objects are those most frequently configured when developing a service for integration with WebSphere MQ. Introduction The IBM WebSphere DataPower SOA Appliances can exchange messages with WebSphere MQ systems by connecting as a WebSphere MQ client. Many of these objects are discussed in the “Basic MQ architecture” on page 3. routing. To bridge the disparate messaging and transport protocols.ibm. Software requirements DataPower appliance integrates with IBM WebSphere MQ versions 6. This capability allows the DataPower appliance to bridge disparate messaging and transport protocols. to WebSphere MQ. as a WebSphere MQ queue manager might do.Chapter 1. A Multi-Protocol Gateway service. security. and the other configuration objects employed on the appliance to implement integration with WebSphere MQ messaging systems. See “MQ Queue Manager object” on page 2. the service behaves as an intermediary in the message flow. This discusses configuration options in the context of an enterprise architecture including routing to remote queue managers. authorization. v An MQ handler to define a WebSphere MQ system as the front side. offers flexibility for tuning integration with WebSphere MQ. In every case. See “Configuring a WebSphere MQ handler” on page 63 for how to configure an MQ Front Side Handler object. v Process Backend Errors property. v Optional: A PUT Queue field for response messages. See “MQ Queue Manager” on page 66 for how to configure the following properties of an MQ Queue Manager object. See “Using an MQ URL to set back-side destinations” on page 10 for more information. See “Processing policies” on page 3. for incoming requests.” on page 45 for more information. MQ Front Side Handler object The MQ Front Side Handler object polls the configured request queue.Note: In this document. v One or more processing policies. See “MQ Queue Manager Group” on page 3. v Queue Manager Name to specify the queue manager on the WebSphere MQ server. 2 DataPower SOA Appliances: Integrating with WebSphere MQ . v Get Message Options field to specify the MQGET options that are applicable to an MQ message. the DataPower object is referred to as the “MQ Queue Manager object. The MQ Queue Manager object on the appliance does not store or hold messages outside the context of a single transaction. See “Referenced objects. 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. See “Injecting and suppressing headers” on page 19 for more information. See Chapter 5. See the “MQGMO_* (Get Message Options)” topic in the “Constants” section of the WebSphere MQ Information Center for details. v A GET Queue field to poll for messages. managed by the referenced WebSphere MQ queue manager. 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 An MQ Queue Manager Group to implement a failover configuration. v Static or dynamic back end. v Units of Work to enable support for local units of work with roll back support. “Error handling. 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. The following properties are defined as part of the MQ Queue Manager object. MQ Queue Manager object The MQ Queue Manager object defines the properties required to connect to the WebSphere MQ queue manager. DataPower service The following properties are defined at the DataPower service level. v MQ Front Side Handler object. v Host Name to specify the WebSphere MQ server.” on page 63 for more information. v Front-side and back-side Header injection and Header suppression parameters. v Retrieve Backout Settings field to determine whether to retrieve the Backout threshold and Backout requeue queue name from the WebSphere MQ server.” The WebSphere MQ queue manager is referred to as the “WebSphere MQ queue manager” or simply the “queue manager”. See “MQ header action” on page 20 for more information. The service does not act as a WebSphere MQ queue manager. The service also supports message traffic from the MQ protocol to the MQ protocol and provides transformation. 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. logging and customization services. | | | | | In WebSphere MQ server Version 7. See “Using MQ headers with custom style sheets” on page 23 for more information. Introduction 3 . See Chapter 5. Basic MQ architecture When integrating with WebSphere MQ system. routing. MQ Queue Manager Group The MQ Queue Manager Group object implements a failover configuration. you can configure the MQ Queue Manager Group object to work with the multi-instance feature for the failover. you can configure multi-instance queue managers for the failover in the WebSphere MQ server. authorization. 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. 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.” on page 45 for more information. v An Error rule for custom error handling. v Primary MQ Queue Manager to specify an existing MQ Queue Manager object. In the DataPower appliance. to define style sheets for custom MQ message header processing. 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. 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. 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 “Working with the multi-instance feature in the WebSphere MQ server” on page 72 for more information. “Error handling. the DataPower service acts as a WebSphere MQ client only. The following properties are defined as part of the MQ Queue Manager object. v Actions. See “MQ Queue Manager Group” on page 72 for information about how to configure the primary and backup MQ Queue Manager objects. such as a Transform action. security. The figure illustrates the primary configuration objects created on the Chapter 1.0.v Total Connection Limit to specify the total number of open connections to allow.1 or later. The Front Side Queue Manager object might optionally place messages in an error queue on the WebSphere MQ queue manager. and from which answers are received in accordance with the HTTP specification. Figure 2 illustrates a DataPower service being used to extend a WebSphere MQ-based messaging system out to a Web Services architecture.appliance as well as the configuration of the MQ Queue Manager to which the service connects and exchanges messages. or front. the Multi-Protocol Gateway employs MQ-based URLs to determine the WebSphere MQ queue to which requests are forwarded. 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. Figure 1. and also from which replies are pulled. a standard HTTP URL is used to determine the destination to which requests are forwarded. On the back end. 4 DataPower SOA Appliances: Integrating with WebSphere MQ . Conversely. side of the service. Basic architecture for MQ to HTTP messaging Here. Figure 2. On the back end. Basic architecture for HTTP to MQ messaging The Front Side Handler object implements HTTP transport connectivity on the client. Next. the service will cancel the transaction and start error handling. rather than only the correlated message. but possibly binary data) to the appliance. This can be done by using the setvar action. Chapter 1. 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. or routes all messages statically to a particular destination. 5. The HTTP client sends an HTTP-based request (typically an HTTP Post containing a SOAP XML document. If no response is found within the Timeout property set in the Destination URL. The appliance polls the reply-to queue specified in the Destination URL field to find a correlated response message. causing the front side HTTP connection to time out. in this architecture. or by using the set-variable() extension function.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. 4. HTTP to MQ As illustrated in Figure 1 on page 4 (HTTP to MQ). The Multi-Protocol Gateway service then applies relevant Processing Policy actions on the message. messages flow to and from the DataPower appliance and work is performed by the appliance in the following sequence. If the network connection to a queue manager fails. 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. The reply can include error responses from the back-end application server. 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. the Multi-Protocol Gateway handles the error in the same fashion as a back-end error.” on page 45 for more information. set the variable ’var://context/ INPUT/_extension/header/X-MQMD-Get’ to ’<MQMD/>’. the Multi-Protocol Gateway takes the message as the response. See Chapter 5. 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. 1. the Gateway will not be able to find the response message. In this workflow the DataPower service connects a front side WebSphere MQ system to a back-end Web Services architecture. If a correlated response message is found. The Multi-Protocol Gateway either dynamically determines the appropriate destination to which to route the message. when the ID is the same as the Message ID assigned to the request. 3. The Front Side Handler passes the message to the Multi-Protocol Gateway service object. The DataPower MQ Queue Manager object contains the necessary information to establish a connection to the MQ queue manager. Introduction 5 . The message is placed on the destination queue with the MQPUT command. The Multi-Protocol Gateway examines the Correlation ID value in the MQ header of messages on the reply-to queue. In either case. 2. The Multi-Protocol Gateway can be configured to retrieve and process any message found on the Reply-to queue. An HTTP Front Side Handler listens on an assigned port for incoming requests. the destination is a particular queue managed by a particular MQ queue manager. the message workflow for the MQ protocol to HTTP example is provided. Using either method. If it does not. “Error handling. The Front Side Handler passes the message to the Multi-Protocol Gateway service object. An MQ Front Side Handler object polls the configured Request queue. 1. to route messages to an active queue. rather than a standard response rule when the back end returns an error (such as HTTP 500).” on page 35 for more information. The Multi-Protocol Gateway opens an HTTP connection and typically posts the request. all request messages are immediately removed from the request queue. configure the Multi-Protocol Gateway to use more than one MQ Front Side Handler polling a range of queues. 3. If the gateway encounters a network error or is otherwise unable to establish a connection to the back-end server. The Multi-Protocol Gateway applies relevant Processing Policy actions on the message. To configure the gateway to run an error rule. “Units of Work. set the Process 6 DataPower SOA Appliances: Integrating with WebSphere MQ . To implement redundancy. by default the Gateway runs any matching error rule in the processing policy.The URL used to open the connection to the back end Request queue can omit designating a reply-to queue. the Front Side Handler saves the MessageID. See item 4 on page 7 for more information. No response is sent to the front side HTTP client. by default the Gateway processes this response using the same response rules used for a good response. MQ to HTTP As illustrated in Figure 2 on page 4 (MQ to HTTP). In this case. In this scenario. See the “MQGMO_* (Get Message Options)” topic in the “Constants” section of the WebSphere MQ Information Center for details. To control the GET command. All messages found on the queue are copied from the queue. See item 4 on page 7. Any processing errors will typically terminate the transaction unless error handling has been built into the policy. 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. 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. ReplyToQueue. use the MQ GET options that are available for large segmented messages through the MQ Front Side Handler. messages flow to and from the DataPower appliance. in the following sequence. The result of any such processing is forwarded to the PUT queue of the MQ Front Side Handler. See Chapter 4. If the message is a Request. and work is performed by the appliance. 2. When the back-end HTTP server returns a good response. The Multi-Protocol Gateway gets the response from the back-end application server. It is then up to the WebSphere MQ system. In this scenario. the Multi-Protocol Gateway applies any applicable Processing Policy actions to the response. The result is returned to the MQ Front Side Handler for delivery. and ReplyToQueueManager fields in the message for later processing of a reply. the HTTP protocol requires a response (which might contain an error message) or the Multi-Protocol Gateway registers an error. By default. for incoming requests. When the back-end application returns a response with a protocol error. independent of the service. 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. such as HTTP 500. managed by the referenced WebSphere MQ queue manager. the back end employs HTTP. The MQ Front Side Handler accepts the decimal value for the desired MQ GET option. Introduction 7 .Backend Errors property of the gateway to off. See “Message descriptor header (MQMD)” on page 24 for more details. the MQ protocol does not require a response. rather than on the Put queue specified in the Front Side Handler. However. If the original request message specifies a reply-to queue. in which case the Error rule runs but no response message is delivered. Unlike HTTP. the Front Side Handler places the response on the queue specified in the message.” on page 35 for more information. 4. “Units of Work. if the response rule has changed the RepyToQ and the ReplyToQMgr in the MQMD header. those will be honored. The response message can be placed on the reply-to queue specified in the MQ Front Side Handler. 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. See Chapter 4. Chapter 1. The Front Side Handler sets the MQMD CorrelID to the saved MsgID of the original request. 8 DataPower SOA Appliances: Integrating with WebSphere MQ . v “Back-side destinations” Provides information about what method to use to set the destination. use the var://service/header-manifest service variable. Some common ways for doing this include the following methods: v Use the Route action. 2010 9 . in similar fashion. “MQ header values. v “Using an MQ URL to set back-side destinations” on page 10 Provides information about setting a static or a dynamic MQ URL. v Use the set-target() or xset-target() DataPower Extension Function calls in a custom style sheet. Back-side request routing A Multi-Protocol Gateway can use either static or dynamic routing to a back-end destination. including the required MQMD header. the Backend URL property of the Gateway determines the route. Protocol header The Multi-Protocol Gateway can also dynamically determine the destination queue by examining the value of the MQ protocol headers. Routing A Multi-Protocol Gateway routes messages to and from WebSphere MQ queues just as messages are routed to and from HTTP destinations. v Use the var://service/routing-url service variable. such as HTTP or JMS. When using a static route. then the Multi-Protocol Gateway Processing Policy must set a back-end target.” on page 19 for more information. 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. The service provides several methods to determine where a message should be routed and how the routing can be specified. v “Back-side request routing” Provides information about what parts of an input message are used to determine where the message should be routed. which contains a nodeset of all supported headers found in the message. The Multi-Protocol Gateway uses either static or dynamically determined routes. The following sections describe these methods. © Copyright IBM Corp. The Gateway can examine the following parts of the input message to help determine where the message should be routed. 2006. the processing policy of the service must set the destination during processing. Back-side destinations If the Multi-Protocol Gateway dynamically determines the back-end destination. The header has already been parsed into a nodeset for easy reference. The complete header can be obtained by reading the extension variable var://context/INPUT/ _extension/header/MQMD. When using dynamic routing. For a list of all headers. Note that you can inspect the headers presented by other request protocols. See Chapter 3.Chapter 2. Optionally. For example. host name and channel name) that is required to access the WebSphere MQ server. These attachments can be separated from the original request and routed individually to a particular destination (that might not be a WebSphere MQ queue).ReplyQueue=replyQueueName. 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 object provides the connection information needed to access a remote WebSphere MQ queue manager on a WebSphere MQ server. v The static URL uses a fixed server address that is defined in an MQ Queue Manager object on the appliance. an XPath expression. just as with HTTP messages. URI Specifies the URI portion of the path to the target queue. This provides the flexibility within a processing policy to dynamically determine the destination at run time. The action can determine the route by using a style sheet. queryParameters The parameters in the URL are as follows: dpmq Indicates the required protocol identifier for a static WebSphere MQ back-end system. To send to and to retrieve messages from a back-end WebSphere MQ system. use the name of a Queue Manager Group to implement failover. The static URL format requires the prior configuration of an MQ Queue Manager object whose properties provide the information (for example. a single request message might contain a number of attachments. can ignore the responses. 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.You can send or route messages to one or more alternative destinations by using the Results (or Results Async) processing actions. 10 DataPower SOA Appliances: Integrating with WebSphere MQ . Syntax for a static MQ URL The syntax for a static MQ URL is as follows: dpmq://QueueManagerObject/ URI?RequestQueue=requestQueueName. 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. This queue is where the DataPower service. The processing policy of the Multi-Protocol Gateway can collect the responses and construct a reply message. use either a static or a dynamic URL format. RequestQueue=requestQueueName Specifies the name of the back-end WebSphere MQ request queue. or can send a response message that does nothing more than acknowledge receipt of the original request. acting as the WebSphere MQ client. An MQ URL can be used to express all back-end destinations. QueueManagerObject Specifies the name of an existing MQ Queue Manager object stored on the appliance. or a variable. the back-end server address and port are determined by a processing policy action such as a transform action or a route action. ContentTypeHeader=header Specifies the name of the MQ header that identifies the content type of the message data. However. the GMO flag takes precedence. Routing 11 . The URL can contain both a request queue and a reply queue name. if a reply queue and a publish topic string are specified. The URL minimally must contain a request queue. true false Specifies that the put operation is asynchronous. Browses the messages on the queue in incremental order. queryParameters Specifies optional and required query parameters for static and dynamic URLs. Browse={first|next|current} Browses (retrieve without removing) messages from the queue that is specified in the ReplyQueue parameter. if you specify next after browsing message one. You can also specify the MQGMO browse options in the GMO=optionsValue parameter. Use one of the following values: first next Browses the first message on the queue. Browses the message on the queue that the url-open just read. For example. a publish topic string. AsyncPut={true|false} Specifies whether to put a message to a queue without waiting for a response from the queue manager. the last one entered is used and the other parameter is ignored. current | | | | Chapter 2. 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. or a reply queue name. if you specify current and the previous browse result is message one. the url-open browses message one. (Default) Specifies that the put operation is synchronous. The URL minimally must contain a request queue. For additional information. Specifying next on the first url-open attempt browses the first message on the queue. the url-open browses message two. see “Asynchronous put operations” on page 53. a publish topic string. For example. or a reply queue name.puts request messages. In the case of a conflict between the Browse parameter and the GMO parameter. ReplyQueue=replyQueueName Specifies the name of the back-end WebSphere MQ reply queue that the service polls for responses. The URL can contain both a request queue and a reply queue name. Selector=expression 12 DataPower SOA Appliances: Integrating with WebSphere MQ . PMO=optionsValue Sets the value for MQPMO.Options field on the MQPUT call that is used to place the request message of the back-end request queue. By default. See the “MQPMO_* (Get Message Options)” topic in the “Constants” section of the WebSphere MQ Information Center for details. The WebSphere MQ server returns the messages with the properties. a value of 2052 (hexadecimal 0x0804) sets the following MQPMO options: v MQPMO_NO_SYNCPOINT (decimal 4. For example. hexadecimal 0x00008000) See the “MQGMO_* (Get Message Options)” topic in the “Constants” section of the WebSphere MQ Information Center for details. only MQPMO_NO_SYNCPOINT is set. and the WebSphere MQ server returns the messages without the properties. see “Publish topic strings” on page 57. hexadecimal 0x00000020) v MQGMO_LOGICAL_ORDER (decimal 32768. When the response is received. 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. the connection to the temporary queue is closed. a value of 32800 (hexadecimal 0x00008020) sets the following MQGMO options: v MQGMO_BROWSE_NEXT (decimal 32. For example. If a ReplyQueue and a PublishTopicString are specified. hexadecimal 0x00000800) With the PMO parameter. The DataPower appliance does not request the properties with the message when issuing an MQGET call. the last one entered is used and the other parameter is ignored.Options. (Default) Specifies that parsing is disabled. ParseProperties={on|off} Specifies whether to parse the properties of the incoming message from a queue or from a subscription. For additional information. see “Message Properties” on page 54. PublishTopicString=string Specifies a topic string associated with the identified queue manager. on off Specifies that parsing is enabled. you can set the MQPMO. hexadecimal 0x00000004) v MQPMO_SET_ALL_CONTEXT (decimal 2048. For additional information.GMO=optionsValue Specifies an integer that identifies a field option for a MQ GMO GET operation. Model={true|false} When true. ParseHeaders={true|false} Specifies a Boolean value that parses and strips headers from message data. The ParseProperties parameter applies to the ReplyQueue or the SubscribeTopicString. This optional value is a cumulative value in decimal format of all acceptable options. Specifies a variable length string containing a SQL92 query that filters messages based on the message properties. For additional information. 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. SubscriptionName=string Specifies a name for the subscription. see “Subscribe to topic strings” on page 58. For information about the values to specify in the MQ Helper fields. For additional information on durable subscriptions. see the online help. see “Subscribe to topic strings” on page 58. for a GET message operation. the last one entered is used and the other parameter is ignored. If a ReplyQueue and a SubscribeTopicString are specified. SubscribeTopicString=string Specifies a topic string associated with the identified queue manager. in milliseconds. 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. Routing 13 . false Note: Note that the QueueManagerObject identified must have the Units of Work property set to 1 (the default is 0). Here is an example of a static MQ URL constructed when the MQ Helper utility is given the following input: Chapter 2. TimeOut=timeout Specifies the timeout value. For additional information. (Default) The URL open call does not execute as part of a transaction. Transactional={true|false} Optional: Specifies whether the URL open call executes as part of a transaction. The presence of this parameter makes the subscription a durable subscription. see “Message Properties” on page 54. (Default) Specifies that the PUT operation is not committed. 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. Sync={true|false} Optional: Specifies whether the PUT operation to the request queue is committed immediately upon successful delivery of the message. The Selector applies to the ReplyQueue or the SubscribeTopicString. 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). inquire queue depth of MQ096 and start looking for specified message--> <xsl:call-template name="find-something-using-browse"> <xsl:with-param name="num" select="dp:mq-queue-depth(’queuemgr1’. .REQUEST The ReplyQueue is specified as BACK.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 . . including the complete syntax for specifying the queue manager parameter.ReplyQueue=BACK.REQUEST. .REPLY Transactionality is set to on User Identifier is set to on dpmq://DPQM/?RequestQueue=BACK.GMO=256" response="xml"/> <xsl:call-template name="find-something-using-browse"> <xsl:with-param name="num" select="$num . 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. TimeOut=500. <xsl:template match="/"> . .REPLY. Transactional=true.1"/> <xsl:with-param name="url" select="$url"/> </xsl:call-template> </xsl:otherwise> </xsl:choose> </xsl:if> 14 DataPower SOA Appliances: Integrating with WebSphere MQ .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.’MQ096’)"/> <xsl:with-param name="url" select="’dpmq://queuemgr1/?ReplyQueue=MQ096. See IBM WebSphere DataPower SOA Appliances: Extension Elements and Functions Catalog for more information on the dp:mq-queue-depth extension function. . <!-.v v v v v The MQ Queue Manager object is specified as DPQM The RequestQueue is specified as BACK.PMO=2052 Using a static MQ URL in a style sheet A static MQ URL can also be used in a custom style sheet. . to connect to the WebSphere MQ queue manager. defined on the WebSphere MQ server. v The negotiated heartbeat interval is between the DataPower appliance and the back-end WebSphere MQ server. there is no connection with the back-end WebSphere MQ server. Some queue managers use an automatic timeout setting (the KAINT attribute set to AUTO). channelLimit=channelLimit.. MQCSPUserId=MQCSPUserID. Routing 15 . the appliance removes that dynamic connection from the cache. Not all channels have a defined. | QueueManager=queueManager Specifies the name of a WebSphere MQ queue manager on the target WebSphere MQ server. When the cache no longer contains dynamic connections.Size=maxMsgSize. No other configuration setting on the appliance can time out an MQ connection. Chapter 2. When an inactive connection reaches this threshold. the keep alive interval is the negotiated heartbeat interval plus 60 seconds. The KAINT attribute on the WebSphere MQ server defines the timeout value for a channel. explicit keep alive interval on the WebSphere MQ server. Syntax for a dynamic MQ URL The syntax for a dynamic MQ URL is as follows: mq://host:port?QueueManager=queueManager. </xsl:template> . In these cases. Without a dynamic queue manager. Specifies the associated port on the target WebSphere MQ server. Specify a value that is greater than the negotiated heartbeat interval but less than the keep alive interval. Note: This timeout value is the only way to configure a timeout value from the appliance to the back-end WebSphere MQ server. This value specifies the Cache Timeout parameter for the dynamic MQ Queue Manager object. 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.ChannelTimeout=channelTimeout. Channel=channelName Specifies the name of the channel.UserName=userName. the appliance deletes the dynamic queue manager.queryParameters The parameters in the URL are as follows: mq host port Identifies the required protocol identifier for a dynamic WebSphere MQ URL. v The keep alive (timeout) interval is on the back-end WebSphere MQ server. Channel=channelName. Specifies the host name or IP address of the target WebSphere MQ server. UserName=userName Specifies the plain text string to identify the client to the WebSphere MQ server.MQCSPPassword=MQCSPPassword. MQCSPPassword=MQCSPPassword Specifies the password value of the MQCSP connection security parameter when MQCSP structure is used for authorization service. For example. Use an integer between 1024 bytes and 1 GB. queryParameters See “queryParameters” under “Syntax for a static MQ URL” on page 10 for more information. Table 1.ReplyQueue=BACK.ChannelLimit=channelLimit Specifies the maximum number of open channels to allow between the appliance and the remote WebSphere MQ queue manager. 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. In addition to the Reply-to queue. Use any value of 2 . as illustrated here: <dp:set-response-header name="’ReplyToQ’" value="QUEUE5"/> Note the inner single quotes for the name parameter. Using the Reply-to queue specified in a request message 3. you can dynamically set the WebSphere MQ queue manager during processing.REPLY Front Side reply routing The Multi-Protocol Gateway routes reply messages using the following order: 1. RequestQueue=BACK.CHANNEL. 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.QueueManager=MQQM.5000.REQUEST. Such dynamic MQ URLs take the following form: mq://MQhost:1414/test/?Channel=DP. Using the Reply-to queue specified by header injection or created by rule actions in the response message 2. Use the same gateway Header Injection 16 DataPower SOA Appliances: Integrating with WebSphere MQ . | | | | | | MQCSPUserId=MQCSPUserId Specifies the user ID value of the MQCSP connection security parameter when MQCSP structure is used for authorization service. 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. Size=maxMsgSize Specifies the maximum size of messages that the WebSphere MQ queue manager accepts. specify the following Header Injection values to send a reply message to the QUEUE5 ReplyToQ. 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. Routing 17 . Chapter 2. 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. not the name of a Manager elsewhere on the network.configuration method. 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. changing the header name to ReplyToQM and the value to the desired queue manager name. or extension function. Table 2. The MQMD header is covered in detail in “Message descriptor header (MQMD)” on page 24. 18 DataPower SOA Appliances: Integrating with WebSphere MQ . While this controls headers at a high level ability. suppose you want to simply suppress the WebSphere MQ Message Descriptor (MQMD) message header on messages passing through a Multi-Protocol Gateway. 2006. 2010 19 . 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 service provides several methods. This can be done from the Headers tab of the service: 1. there is no guarantee that the message will be accepted or processed correctly on the WebSphere MQ server. it might be the easiest way to meet your requirements. to manipulate MQ headers. For these unsupported headers. For instance. the service leaves the header as it is and passes the message to the back end.Chapter 3. from basic to completely customized. © Copyright IBM Corp. Click 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. The service logs a message indicating that the MQ message contains a header that is not supported. 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. If this is not done. Even though the headers are not defined in the original request. you must specify the CCSID value in the MQ header. the service provides the specified headers. using header injection. you can specify a header and a header value to inject. the service removes the specified header before forwarding the request. 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. the service sends responses to the MQ Queue Manager specified in the MQ Front Side Handler. 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. 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. 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. 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. Click Add under Header Suppression Parameters.Format to MQHRF2 using the following header injection parameters. Note: When you inject any MQ header. By default. 4. Specify the direction as either Front or Back. Similarly. By default. 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. the service will use 819 (ISO 8859-1 ASCII) as the default value. For example. change the MQMD. not 1208 (UTF-8). 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. Modify Reply Queue for Response Messages Modify the destination reply queue for response messages. 20 DataPower SOA Appliances: Integrating with WebSphere MQ . such as MQCIH. When the header is defined in the original request. Specify the header to suppress.2. Table 3. By default. that has a CodedCharSetId (CCSID) field. 3. v In the Message Id field. processing inserts the correct context identifier. Click Done. 3. Set Asynchronous to indicate whether to process asynchronously. processing inserts the correct context identifier. If auto. Click the MQ Header radio button. Select request as the MQ Processing Type. 9. specify the message ID. 9. 2. processing inserts the output context. 10. Optional: Specify the input context. Chapter 3. 12. 8. Set Override Existing MQMD to choose a mode for overriding the MQMD headers in the request message: 10. If auto. Set Asynchronous to indicate whether to process asynchronously. click Apply Policy. 6. the action does not need to complete before the rule starts processing its next action. Select MQMD for Get from the MQ Request Header Processing list. 5.Modifying MQMD request headers To modify MQMD header values for request messages placed to the backend: 1. 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. Double-click the Advanced icon. MQ header values 21 . If auto. 4. 8. Double-click the Advanced icon. 5. Select an output context. If enabled. processing inserts the output context. Click Next. Select request as the MQ Processing Type. Optional: Specify the input context. The service pulls messages from the backend reply queue with the specified message ID. If this is the last action for the rule. Otherwise. If enabled. v In the Correlation Id field. 3. Click Next. If auto. 2. Define how the service pulls messages from the backend reply queue. Click the MQ Header radio button. 4. drag another icon to the configuration path. Select MQMD for Put from the MQ Request Header Processing list. Drag the Advanced icon to the configuration path (the horizontal line). 7. Retrieving responses by message ID or by correlation ID To retrieve response messages from the backend reply queue: 1. 6. specify the correlation ID. Drag the Advanced icon to the configuration path (the horizontal line). Select an output context. 7. the action does not need to complete before the rule starts processing its next action. The service pulls messages from the backend reply queue with the specified correlation ID. Select response as the MQ Processing Type. 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. Click the MQ Header radio button. 8. 7. 3. drag another icon to the configuration path. Set Asynchronous to indicate whether to process asynchronously. Double-click the Advanced icon. 2. 12. 4. Modifying MQMD response headers To modify MQMD header values for response messages placed to the backend reply queue: 1. If enabled. 6. If this is the last action for the rule. 5. Click Done. If auto. 6. Click Next. If this is the last action for the rule. the action does not need to complete before the rule starts processing its next action. 22 DataPower SOA Appliances: Integrating with WebSphere MQ . 2. 8. If enabled. Select ReplyToQ from the MQ Response Header Processing list. processing inserts the correct context identifier. Double-click the Advanced icon. Select response as the MQ Processing Type. 10. Set Override Existing MQMD to choose a mode for overriding the MQMD headers in the response message. Drag the Advanced icon to the configuration path (the horizontal line). Drag the Advanced icon to the configuration path (the horizontal line). Select an output context.11. Otherwise. 4. 5. Set Asynchronous to indicate whether to process asynchronously. Optional: Specify the input context. 7. Modifying the reply queue for responses To change the destination reply queue for response messages: 1. If auto. click Apply Policy. If auto. processing inserts the correct context identifier. click Apply Policy. Click Done. Click Next. the action does not need to complete before the rule starts processing its next action. Click the MQ Header radio button. drag another icon to the configuration path. Optional: Specify the input context. 9. Select MQMD from the MQ Response Header Processing list. processing inserts the output context. 3. Otherwise. using custom style sheets adds additional customization for dynamic. drag another icon to the configuration path. If enabled. the style sheet is used in a transform action in a request. Click Next. Click Done. an input field can be specified as static text or as a variable. drag another icon to the configuration path. processing inserts the correct context identifier. select the processing method for the response message. specify a value. since the service will put the message to the queue and queue manager which are set dynamically in the style sheet. 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. Note: To set values. If auto. select the processing method for the response message. Drag the Advanced icon to the configuration path (the horizontal line). response. the action does not need to complete before the rule starts processing its next action. Select an output context. 10. 7. Optional: Specify the input context. 12. 5. runtime control of MQ headers. 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 Chapter 3. 2. 12. 6. If this is the last action for the rule. processing inserts the output context. Double-click the Advanced icon. click Apply Policy. Modifying the queue manager for responses To change the destination MQ Queue Manager for response messages: 1. If auto. Otherwise. processing inserts the output context. click Apply Policy. or error rule of the processing policy. A results action is not needed. 10. Click Done. the ReplyToQ name might be specified with static text or with a variable such as var://context/INPUT/hdrval. 8. From the ReplyToQM Processing Type list. Click the MQ Header radio button. Select an output context. For instance. 11. If this is the last action for the rule. Optional: In the ReplyToQMgr field. If auto. 11. Set Asynchronous to indicate whether to process asynchronously.9. MQ header values 23 . Select response as the MQ Processing Type. 9. 4. 3. Select ReplyToQM from the MQ Response Header Processing list. specify a value. Otherwise. From the ReplyToQ Processing Type list. to add an MQ Header action to specify the reply queue for response processing. Optional: In the ReplyToQMgr field. Typically. handling a request message. The service processes MQMD headers as follows as the message moves from the request (front) side to the application (back) side. In the context of a back-end request. might be specified by the reply from the back-end application. 1. or might be specified by the configuration of the DataPower MQ Front Side Handler. ReplyToQ The name of the queue to place reply message. 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. 5. You can also control the behavior of the communications with the remote queue manager (by determining a Reply-to queue. In the context of a client request. or might be specified by the configuration of the DataPower MQ Front Side Handler object. this is where the back-end application server should place a reply. this is where the back-end application server should place a reply. CorrelationID A unique identifier that matches a MessageID. 3. The handler saves the MessageID. ReplyToQ and ReplyToQMgr header values for later use in processing the response message. replacing any existing MQMD header. MessageID A unique identifier assigned to a message by the originator of the message. The gateway can be configured to inject a new MQMD header. When this is done. might be specified by the reply from the back-end application. see the relevant WebSphere MQ documentation. 4. for instance). CICS® or IMS™ headers. This might be specified by the client in the MQMD header of the request. In the context of a client request. The gateway can use a custom style sheet during policy processing to create or alter an MQMD header. This might be specified by the client in the MQMD header of the request. such as JMS. 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. this is where the DataPower service places a reply. 2. The handler can be configured to strip out unwanted headers. 24 DataPower SOA Appliances: Integrating with WebSphere MQ . The gateway can be configured to suppress the existing MQMD header in the message. In the context of a back-end request. the gateway constructs a new header using the default values for the back-end connection. 6. For complete details regarding the effect and consequences of these values as interpreted by an IBM WebSphere MQ instance. The DataPower service uses four nodes in particular to manage the routing and flow of messages. By manipulating these header values.Message descriptor header (MQMD) The DataPower appliance provides the ability to determine the full set of MQMD header values. this is where the DataPower service connects to place a reply. ReplyToQMgr The name of the queue manager managing the ReplyToQ. you can alter the routing of messages by a DataPower service. If the message is in response to a request. using a style sheet executed in a Transform action as part of a Chapter 3. When using this method. The Gateway can be configured to suppress or inject the header as detailed above. for example. This returns a nodeset containing the names of all supported headers in the message. store a copy of the MQMD header (and other desired MQ-related headers) in a context variable during the request processing phase. 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. you would first need to save the entire MQMD header nodeset.The service processes MQMD headers as follows as the message moves from the application (back) side to the request (front) side. change the desired value and then rewrite the MQMD header using the saved values. You must create an MQMD header containing all desired elements whenever you want to change or add just one. handling a response message. You can then obtain the values set for each header by using a dp:request-header() or dp:response-header() function. So. if you wanted to change the UserIdentifier header value sent to the back-end queue. 2. You can change or set the MQMD header by using the extension functions dp:set-request-header() or dp:set-response-header(). The saved ReplyToQ and ReplyToQMgr information corresponding to the request message are also provided for Front Side Reply routing. the service provides the CorrelID corresponding to the MessageID provided no response rule alters the MQMD header. 1. MQ header values 25 .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. You can discover which supported MQ-related headers are contained in a message by reading the var://service/header-manifest variable. 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. These headers override the values in the MQMD header. <?xml version="1.datapower.w3.org/1999/XSL/Transform" version="1.0" xmlns:dp="http://www. You can then retrieve the original request MQMD header and alter it or reinstate it as needed in the response processing. If this is not the desired effect.Request rule.org/1999/XSL/Transform" version="1.get the MQMD header from the request message --> <xsl:variable name="entries" select="dp:request-header(’MQMD’)"/> <!-. <?xml version="1.create a variable to hold the new MQMD --> <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 DataPower SOA Appliances: Integrating with WebSphere MQ . allowing the service to put to this queue and queue manager but leave the MQMD in the message intact.make sure these values are blank or they will override MQMD --> <dp:set-response-header name="’ReplyToQ’" value="’ ’"/> <dp:set-response-header name="’ReplyToQM’" value="’ ’"/> <!-. This style sheet stores the key elements of the header in DataPower variables.store the desired values in a variable available for later --> <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 :’. Here are two examples that illustrate the request and reply style sheets. the ReplyToQ and ReplyToQM should be cleared with the dp:set-response-header() extension element as shown in this example. the style sheet retrieves the MQMD header contained in a client request to the front side of a Multi-Protocol Gateway. Note that the special headers ReplyToQ and ReplyToQM specify the response queue and queue manager.0" xmlns:dp="http://www.datapower.0" encoding="utf-8"?> <xsl:stylesheet xmlns:xsl="http://www.com/extensions" extension-element-prefixes="dp" exclude-result-prefixes="dp"> <xsl:output method="xml"/> <xsl:template match="/"> <!-.w3. On the request rule.parse into a usable nodeset --> <xsl:variable name="header" select="dp:parse($entries)"/> <!-.0" encoding="utf-8"?> <xsl:stylesheet xmlns:xsl="http://www.com/extensions" extension-element-prefixes="dp" exclude-result-prefixes="dp"> <xsl:output method="xml"/> <xsl:template match="/"> <!-. com/param/config" xmlns:soapenv="http://schemas. MQ header values 27 .org/wsdl/soap/"> <xsl:output method="xml"/> <xsl:template match="/"> <!-. ’?>’)"/> <xsl:message> <xsl:value-of select="concat (’MQMD with modified Response ReplyToQ and ReplyToQMgr : ’.datapower.serialize the nodeset for transport --> <xsl:variable name="mqmdStr"> <dp:serialize select="$newMQMDStr"/> </xsl:variable> <!-.</ReplyToQMgr> <Format>MQSTR</Format> </MQMD> </xsl:variable> <!-.xmlsoap.0"?> <xsl:stylesheet version="1. 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.xmlsoap.create a variable to hold the MQMD header --> <xsl:variable name="mqmd"> <MQMD> <Format>MQIMS</Format> <ReplyToQ>MQBREPLY</ReplyToQ> <ReplyToQMgr>WMQB</ReplyToQMgr> </MQMD> </xsl:variable> <!-. The style sheet is used in a transform action of a request rule. provides assured control of message routing.create a variable to hold the MQIIH header --> <xsl:variable name="mqiih"> <MQIIH> <Encoding>0</Encoding> <CodedCharSetId>1208</CodedCharSetId> <Format>MQSTR</Format> <Flags>0</Flags> <LTermOverride /> <MFSMapName /> <ReplyToFormat>MQSTR</ReplyToFormat> Chapter 3.serialize the nodeset for transport --> <xsl:variable name="mqmd-serl"> <dp:serialize select="$mqmd" /> </xsl:variable> <!-.w3. You can also create the complete MQMD header sent to a back-end application server queue using these functions. using variables containing the Request MQMD header. IMS Information Header (MQIIH) This example style sheet sets the MQMD and MQIIH headers to send messages to an IMS application.org/1999/XSL/Transform" xmlns:dp="http://www. dp:response-header(’MQMD’))"/> </xsl:message> </xsl:template> </xsl:stylesheet> Setting the complete MQMD header.set the MQMD of the response with new MQMD --> <dp:set-response-header name="’MQMD’" value="substring-after($mqmdStr.datapower.0" xmlns:xsl="http://www.org/soap/envelope/" extension-element-prefixes="dp" exclude-result-prefixes="dp dpconfig" xmlns:wsdlsoap="http://schemas.com/extensions" xmlns:dpconfig="http://www. datapower.serialize the nodeset for transport --> <xsl:variable name="mqiih-serl"> <dp:serialize select="$mqiih" /> </xsl:variable> <!-.<Authenticator>IMSSOAP</Authenticator> <TranInstanceId>01234567890123456</TranInstanceId> <TranState>0</TranState> <CommitMode>1</CommitMode> <SecurityScope>0</SecurityScope> </MQIIH> </xsl:variable> <!-.set the MQMD request header value --> <dp:set-http-request-header name="’MQMD’" value="$mqmdStr"/> <!-.org/1999/XSL/Transform" version="1.populate new MQCIH.0" encoding="utf-8"?> <xsl:stylesheet xmlns:xsl="http://www.set the request headers to the variables --> <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. This value specifies the use of the CICS DPL bridge <?xml version="1.BRIDGE’"/> </ReplyToQ> </MQMD> </xsl:variable> <!-.serialize the nodeset for transport --> <xsl:variable name="mqmdStr"> <dp:serialize select="$newMQMDStr" omit-xml-decl="yes"/> </xsl:variable> <!-.w3.UOWControl is set to MQCUOWC_ONLY v MQCIH.CICS.Format is set to MQCICS v MQCIH.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"/> <!-.LinkType is set to MQCLT_PROGRAM.populate new MQMD Format and CorrelId --> <xsl:variable name="newMQMDStr"> <MQMD> <Format>MQCICS</Format> <CorrelId> <xsl:value-of select="’414D51214E45575F53455353494F4E5F434F5252454C4944’"/> </CorrelId> <ReplyToQ> <xsl:value-of select="’FROM.UOWControl to MQCUOWC_ONLY --> <xsl:variable name="newMQCIHStr"> 28 DataPower SOA Appliances: Integrating with WebSphere MQ .0" xmlns:dp="http://www. The example shows the following practices: v MQMD. the service might include the MQCIH (CICS Header Structure) as part of the message request. <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. Chapter 3. MQ header values 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 DataPower SOA Appliances: Integrating with WebSphere MQ 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"/> Chapter 3. MQ header values 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 DataPower SOA Appliances: Integrating with WebSphere MQ ibm.x. 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. MQ header values 33 . 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).MaxMsgLength v MQCD. This only works with version 2 of the MQOD structure. This is done by defining an array of MQOR structures.ConnectionName Chapter 3. this new capability might provide a needed flexibility.QMgrName v MQCNO. In general. 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.x.ConnTag (z/OS® only) v MQCNO. Employ a Set Variable action that sets the var://context/INPUT/_extension/ header/MQOR variable to: <MQOR><ObjectName>Q1</ObjectName></MQOR>. 3. The requirement can be implemented on a DataPower service by doing the following : 1. For the user who is very familiar with the WebSphere MQ architecture and implementation details. <MQOR><ObjectName>Q3</ObjectName></MQOR> 4.Desc v MQCD. Employ a Results action with a destination determined by an mq:// URL with no specified RequestQueue. The MQOD structure then points to this list and sets a field indicating the length of the list.DiscInterval (inactivity timer in seconds) v MQCD. <MQOR><ObjectName>Q2</ObjectName></MQOR>.x/test/RequestQueue= Here is a list of the extended header variables supported: v MQCONNX.ConnectionId (output only) v MQCD. Create a Processing Policy with a rule matching the desired criteria. Each structure needs the ObjectName field set to one of the destination queues."/> </xsl:template> </xsl:stylesheet> WebSphere MQ API support The DataPower appliance supports the WebSphere MQ client API through the use of extension variables. in the same way you can set the MQMD header. 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. For example.com/software/integration/wmq/library/.ChannelName v MQCD.</xsl:template> <xsl:template match="*"> <xsl:copy-of select=". 2. The options are set using the same values as detailed in the WebSphere MQ API documentation available at http://www. The MQOD structure is finally the input to the MQPUT call. such as: mq://x. SSLPeerName (indirectly sets the string pointer and length) MQCD.Options are set in the MQ URI using the PMO= attribute. you cannot read the values in this structure.LDAPPassword You can differentiate between the Object Descriptor for the Get and Put by using X-MQOD-Get and X-MQOD-Put.KeepAliveInterval MQCD.SSLClientAuth (value of REQUIRED or OPTIONAL) MQCD.AuthInfoConnName (LDAP server host and port) v MQAIR. MQPMO.KeyResetCount MQSCO.LDAPUserName (indirectly sets the string pointer and length) v MQAIR.Options) are set in the MQ Front Side Handler configuration. Note that MQOD is write only.LocalAddress MQCSP.Password (indirectly sets the string pointer and length) MQSCO.AuthInfoRec (indirectly sets the pointer and count) You can set multiple AIR just by adding more headers: v MQAIR.UserId (indirectly sets the string pointer and length) MQCSP. Headers can be ordered on the wire in the sequence that they are set.v v v v v v v v v v v v MQCD.SSLCipherSpec MQCD.HeartbeatInterval MQCD.FipsRequired MQSCO.LongRemoteUserId MQCD. Options for GET (MQGMO. 34 DataPower SOA Appliances: Integrating with WebSphere MQ . two separate units of work are supported with each unit of work coordinated by the respective MQ Queue Manager object. This concept also includes the ability to roll back transactions. Transaction manager software must coordinate the global unit of work. That is. WebSphere MQ queues. and gets from. and the coordination of each unit of work is provided within the queue manager. or © Copyright IBM Corp. Upon receiving an MQBACK. 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. WebSphere MQ restores the queues by removing the messages that were put on the queues by that unit of work. are also updated. 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. To commit a unit of work. not global units of work between the appliance and the queue manager.Chapter 4. An application can specify a group of MQPUT or MQGET messages all belong to the same unit of work. all updates must be successful to preserve data integrity. Local units of work are those in which the only actions are puts to. A unit of work might include more than one message. Upon receiving an MQCMIT. 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. the Queue Manager makes the message again available to any client for retrieval. v The MQ URL of the back end contains the Transactional = true parameter. v The MQ Queue Manager object used by the front side has the Units of Work field set to 1. Units of Work The WebSphere MQ protocol includes the Units of Work concept. the Queue Manager deletes the message. 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. 2010 35 . WebSphere MQ distinguishes between local and global units of work. 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. such as tables in a relational database. The DataPower appliance supports only local units of work. 2006. Global units of work are those in which other resources. When a program performs a backout. If different queue managers are used for the front side and the back end. if it is not already opened and cached. The sequence of events is as follows: 1. 3. Clients can determine the number of times the same message has been retrieved from a queue by examining the BackoutCount field in the MQMD. enabled). The unit of work is committed using MQCMIT. If the application MQDISC before issuing MQCMIT or MQBACK. If the client detects an error. When a client places a message (MQPUT) on a queue within a unit of work. If the application failed before issuing MQCMIT or MQBACK. Units of work implementation This section discusses how the DataPower appliance implements WebSphere MQ units of work. 2. it can issue an MQBACK. on the same connection. There can be any number of MQPUT or MQGET messages within the unit of work. that message remains on the queue but is not available to other clients. A unit of work begins when a WebSphere MQ client specifies SYNCPOINT=True on the first MQGET or MQPUT. When a WebSphere MQ client retrieves (MQGET) a message from a queue within a unit of work. or rolled back using MQBACK. the handler opens a new one using MQCONNX. which become available through various service variables. the queue manager restores the message by making it available to be retrieved by any client.transaction. 3. 2. This field contains the number of times the message has been previously requested and subsequently backed out. the MQ Front Side Handler object gets a connection to the queue manager of the Get queue from the connection cache. If the client issues an MQBACK. 6. or the network failed. The MQ implementation functions as a special purpose WebSphere MQ client. Because these operations take place on the same connection. The queue manager permanently deletes the message from the queue when the client issues an MQCMIT on the same connection. A unit of work is associated with the connection between the WebSphere MQ client and the queue manager. The queue manager restores the queue by removing the message that was put on the queue by that unit of work. The MQ Front Side Handler object issues an MQOPEN for the Get Queue specified in the handler configuration. the queue manager makes that message available to other applications only when the client issues an MQCMIT on the same connection. the queue manager will commit the unit of work. the MQGET is issued with SYNCPOINT=true to mark the start of a unit of work. 4. When an MQ Front Side Handler object associated with a Multi-Protocol Gateway service is ready to retrieve a new message. The service parses the message headers. Multiple queues can be opened on the connection for MQGET and MQPUT operations. If no connections are available. Here is a summary discussion of unit of work: 1. The Front Side Handler object passes the message returned by MQGET to the processing policy of the Multi-Protocol Gateway service. 36 DataPower SOA Appliances: Integrating with WebSphere MQ . All of the messages in the group must process successfully or all of them are rolled back together. 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. the unit of work is rolled back by the queue manager. 5. the queues are all managed by the same queue manager. the MQCMIT will apply to both the initial MQGET on the Get Queue and the MQPUT on the Put Queue. and even if it is to the same queue manager as the front it would use a different connection. It is important to note that the back-end MQPUT typically goes to a different queue manager than the front. Note that although the MQGET for reply message can be issued with SYNCPOINT=true using GMO. and the GMO of the MQGET for the reply. 6. the unit of work for the back-end connection is not the same as the unit of work for the front side connection. When the service connects to the back-end server using the WebSphere MQ protocol. When the request rule completes. 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. the MQ Front Side Handler object will again retrieve the same message. 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. Set the Backout Queue Name property to the appropriate value Chapter 4. 8. and the MQPUT is issued with SYNCPOINT=true. 4. and optionally an error rule to handle any errors that occur during processing. Units of Work 37 . which can set PMO for the MQPUT of the request. the gateway service employs an MQ URL opener. 5. Any response rule in the processing policy matching the message executes. When a message remains on a request (GET) queue after a failure. Set the Backout Threshold property to the appropriate value c. 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). there is no corresponding logic to later issue an MQCMIT or MQBACK and hence should be avoided.The processing policy can consist of a request rule to process the request message before passing the message to any back-end server. the Multi-Protocol Gateway service sends the possibly altered message to the back-end server. possibly altering the message or the message headers. the MQPUT of the request message to the back-end queue is immediately followed by an MQCMIT upon success. 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. Set the Automatic Backout flag to on b. When the processing policy completes. Therefore. 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. The policy might also optionally include a response rule to process a reply message from the back-end server. 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. 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. Note that if the statically configured Put Queue is used in step 6. When enforcing transactions. 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”.BackoutCount reaches the configured backout threshold. Transactions on a service A transaction is a sequence of operations that end with either a commit or a roll back. See “Units of Work property” on page 39. Users must be careful to have the correct configuration for the message exchange pattern desired. 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. 38 DataPower SOA Appliances: Integrating with WebSphere MQ . 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.BACK.GET and FRONT. See “Sync parameter” on page 40. on the front side. when a message is fetched from a queue with an MQ GET operation. “A” and “B”. when a message is put onto a queue with the PUT operation. In this example. on the back end. has two queues: BACK. the message is not available for another GET operation until the commit. The DataPower appliance. v The MQGMO and MQPMO syncpoint options. A transaction commits if all the operations in the transaction succeed.REQUEST and BACK. See “MQGMO and MQPMO syncpoint options” on page 40. 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. v The Sync parameter of the back-end MQ URL. has two queues: FRONT. A transaction rolls back if any one of the operations in the transaction fails. 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. The Units of Work setting controls front side synchronization. In this scenario. the message is not physically removed from the queue until the MQCMIT operation performs a commit. The Transaction and Sync parameters of the back-end MQ URL control back-end synchronization. v The Transactional parameter of the back-end MQ URL.BackoutCount header value of the MQGET of the request (GET) queue. Queue manager “A”. front side and back end. If the MQMD.The MQ Front Side Handler object using the queue manager tracks the MQMD. The DataPower MQ client library provides transactional support on both sides of the Multi-Protocol Gateway service.REPLY. participates in local transactions. or units of work. acting as the WebSphere MQ client. See “Transactional parameter” on page 39. the scope of the unit of work is limited to either the front side or the back end. Similarly. because there is a different queue manager on the front side from the queue manager on the back end. two queue managers are used. Queue manager “B”. The queues in Figure 4 show the message flow when units of work is set to 1: 1. retrieved messages are synchronized when they are successfully delivered to the back end destination queue and the transaction is complete. format is used. The transaction commits and the message is removed from the FRONT. When the following conditions are true. 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. Units of Work 39 .REQUEST queue. The MQ Front Side handler object retrieves messages from the FRONT.GET queue. v The Transactional parameter is set to true. When this property is set to 1.GET queue. the service uses the same connection on the front side and the backend. 2. dpmq://.REQUEST queue.Figure 4.REPLY queue. A GET operation retrieves the message from the BACK. The transaction commits as soon as the PUT operation to the Chapter 4. v The same queue manager manages both the front side and the back-side connections v The static MQ URL. Figure 4 shows the message flow when the Transactional parameter is set to true: 1. 3. 3. Note: If no reply queue is specified. Basic architecture for MQ to MQ messaging Units of Work property The Units of Work property manages transactionality on the front side. The GET and PUT operations are committed when the GET operation from the BACK. The message is PUT to the back-end BACK. The message is successfully delivered to the back-end destination BACK.REPLY queue is successful and the transaction is complete. the transaction does not require the GET operation. 2. If it is not set. you can use the MQGMO and the MQPMO syncpoint options to include GET and PUT operations in a unit of work. When the Sync parameter is not specified. the PUT operation to the request queue 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. all the messages within the unit of work are committed. if you use a PUT operation with the MQPMO option set to 2 or MQPMO_SYNCPOINT. false is assumed. Common message delivery patterns The DataPower appliance supports a number of application-specific delivery patterns using all of the configuration tools available. The Sync parameter must be set to true if there is both a back-end request and a reply queue. Many sites require transaction-style (synchronous) delivery. Note: Because the PUT operation is committed immediately upon successful delivery of the message. the PUT operation is committed inside a unit of work.REPLY. Sync parameter When the Sync parameter is set to true on the back-end MQ URL. unlike HTTP. The WebSphere MQ system provides some mechanisms to support this delivery pattern.BACK. 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. When the Transactional parameter is not specified. Otherwise. The WebSphere MQ messaging system can easily support this pattern because WebSphere MQ is asynchronous.REQUEST queue completes. 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). the back-end application will not see the message placed on BACK. The PUT operation is committed and completes the transaction.REQUEST. sites also require that this asynchronous (fire-and-forget) pattern provide assured delivery of messages. Often. you can use the final action of a processing policy to perform a dp:reject to roll back the transaction. with no loss of messages and no duplication of messages during operation. These patterns apply to scenarios in which the service retrieves messages from a WebSphere MQ 40 DataPower SOA Appliances: Integrating with WebSphere MQ . false is assumed. 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). See “Sync parameter” for information on using the Transactional parameter with the Sync parameter. The queues in Figure 4 on page 39 show the message flow: 1. This section describes each of these two common delivery patterns.REQUEST queue. 2. For instance. in which each request must result in a response. If there are multiple PUT operations and any one fails. A response to a request is not required. MQGMO and MQPMO syncpoint options When units of work is set to 1. The message is delivered to the back-end BACK. queue using an MQ Front Side Handler. and delivers messages to a destination WebSphere MQ queue on the back end. Figure 5. 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. Figure 5 illustrates this architecture. Note that the back-end MQPUT is not on the same connection as the front side MQGET. 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. the probability of an appliance failure between the back-end MQPUT and the front side MQCMIT is extremely small. For guaranteed asynchronous delivery with no duplicates. completing the unit of work. In the unlikely event that this happens. 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. However. without looking for a response. one for each direction. thus omitting the back end altogether. blank). Units of Work 41 . Instead. resulting in duplicate delivery. 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. especially if message routing is involved. two separate Multi-Protocol Gateways are used. For each Gateway. Note that the header of the message must also contain no ReplyToQ specification (that is. the Gateway uses the Front Side Handler to place Chapter 4. both Multi-Protocol Gateways can be configured to use loopback processing. with no response rule processing. The two Queue Managers (one for each direction) might be different. the following are the possible failure situations: #1 #4 <--------. Requests can be correlated with responses. the service would close the connection and start over. 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. It is not. All the policy contexts and variables for each direction are separate and not available to each other.GET PUT GET <--------. This is done by setting the write-only service variable var://service/mpgw/skip-backside to 1 (on) in the Multistep Policy. If MQBACK failed. The DataPower appliance provides such support and other additional features such as failover across multiple queues and Queue Managers. Synchronous delivery WebSphere MQ provides features to support synchronous (request-response transaction type) delivery patterns. Using the reference diagram below. 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. and dynamic routing can be used to facilitate workflow. 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). 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. a single Multi-Protocol Gateway processes both the request and reply messages of the transaction. for example. Note that the use of these additional features does conflict with the ability to use units of work to guard against message duplication. possible to correlate a request to the back-end server with the response using Message IDs and Correlation IDs. enabling units of work. For a synchronous delivery pattern.(MQPUT) the message on the Front Side Handler's PUT queue after all Processing Policy actions for the request have completed. WebSphere MQ infrastructure failure at point 2 The DataPower service will try to issue MQBACK at #1 and start over. 42 DataPower SOA Appliances: Integrating with WebSphere MQ . The closed connection will cause the Queue Manager to restore the request message. The MQCMIT issued by the Gateway then commits both the MQGET and MQPUT messages atomically.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. 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. v The Gateway's Processing Policy should include an error rule to handle failures encountered during the transaction. After the error rule completes. If the back-end server application is idempotent. the response will not be lost in this kind of configuration. because the service never gets a correlated response message from the application server. If the service can establish or maintain a connection to the back end Reply queue but the server application fails to produce a reply. WebSphere MQ infrastructure failure at point 4 The DataPower service will issue an MQBACK signal at #1. The two separate Gateways cannot share transactional data. Units of Work 43 . thus restoring the original request message to the queue. However. Appliance failure between point 3 and point 4 The reply message taken from #3 is lost. The service might also be using dynamic Reply-to queues.Appliance failure between point 2 and point 3 The Queue Manager will restore request message at #1. such as Message ID and Correlation ID. You can alternatively cause the service to place an error message at #4 and issue an MQCMIT at #1. which will result in a duplicate message delivered to the back-end server. the server application will produce the same result when the service again delivers the request message. but that request has been successfully delivered to queue #2 and the reply from the back-end server might be on queue #3. The back-end server application places another reply message on its reply queue with the correct CorrelationID. set the Process Backend Errors property to on and set the Timeout parameter of the destination MQ URL. Chapter 4. To do this. which would no longer be known to the appliance. when appliance recovers. the service will wait indefinitely. the service will again run any matching Error rule and issue MQBACK at #1. If the back-end application is not idempotent. Because the DataPower appliance failed. If no timeout is set. If the backend transactionality is also turned on by appending the Transactional=true and Sync=true parameters to the backend URL. provided the URL used to designate the back-end connection specifies a Timeout value. the service runs a response rule to send a specific message to queue #4. even though the service has in fact successfully delivered it to the back-end server. 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 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. Upon timeout. causing the original request message to be restored to the queue. MQ Front Side Handler error handling will issue MQBACK at #1. In addition. This again causes an MQCMIT to be sent to the Queue Manager of the request queue. If the DataPower service encounters a connection error and cannot establish a connection to the back-end Reply queue. the front side request Queue Manager restores the request message to the queue. you must set the Response Type property of the Gateway to Non-XML. WebSphere MQ infrastructure failure at point 3 Two kinds of errors can occur here. the service will run the configured error rule. The Queue Manager handling the front side connection will detect the appliance failure and restore the request message at #1. and the transaction completes successfully. Thus. the back-end server application will need to incorporate protections against receiving a request message twice. Note that the use of two separate Multi-Protocol Gateways for a synchronous delivery pattern is not recommended. JMS. As with a WebSphere MQ back end. 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. Back Side The MQ units of work affects only the placement (PUT) of a message on the request queue of the back-end server. 44 DataPower SOA Appliances: Integrating with WebSphere MQ .Units of work with other protocols The DataPower service interconnects the WebSphere MQ protocol system with other protocols. 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. and is not in any way affected by the operations of a different protocol on the front side of the Gateway. TIBCO EMS and FTP. 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. plus any Timeout parameters used in the back-end URL. including HTTP. 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. This does not change when the protocol used to connect to the back-end application server is not MQ. 2010 45 . 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. must have a style sheet with customized error handling. and custom error message generation. the DataPower service attempts to reconnect to the remote host. Error handling A Multi-Protocol Gateway service uses all of the standard error handling capabilities available for HTTP traffic. This alternative queue manager is defined by an MQ Queue Manager Group object. When designing an error handling strategy. If repeated connection attempts to an unresponsive remote queue manager fail. When the Automatic Retry property is set to on. request. queue manager. The service also starts the automatic retry mechanism as determined by the Automatic Retry property of the MQ Queue Manager object. automatic fault generation when a request or response message does not pass validation checks. or reply. the service can instead connect to an alternative. 2006. This setting does not affect attempts to put or get messages over an established connection. 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. unless specifically instructed to do so within a style sheet. The service can also use custom style sheets to implement error handling. © Copyright IBM Corp. by default the service retries placing a message on a queue once. or failover.Chapter 5. See “MQ Queue Manager Group” on page 72 for more information. The following topics highlight specific approaches to use for error handling in an integrated DataPower and WebSphere MQ environment.MsgType. the service cancels the transaction and starts error handling (such as running a configured Error rule). The number of retry attempts is determined by the Retry Interval property of the MQ Queue Manager object. the On-Error action. A service that receives both datagram and request and reply message traffic. This includes processing policy Error rules. In response to a MQRC 2009 error. The service does not use the WebSphere MQ defined message type. such as datagram. MQMD. consider whether the service will handle datagram (one-way) and request and reply (two-way) message traffic. 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. possibly causing a loop. the service runs any configured error rule. suppose you are using an error rule that matches specific MQ reason codes. If you do not create a response rule to handle this condition. 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. the service moves the message to the backout queue specified by the Automatic Backout properties. 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. if an error occurs that does not return an MQRC. In this way. If this property is set to on. This might happen if there is a back-end communication problem error such as with a WebSphere MQ channel. When an MQRC is returned from the WebSphere MQ server. Because a datagram does not require a reply from the back-end application. In these situations. a processing policy for this traffic most likely does not contain a response rule. when an error occurs. Because errors in WebSphere MQ often contain no message. the MQ Front Side Handler object retrieves the same message again. The Process Backend Errors property is appropriate for services that handle request and reply messages. such as when a queue is full or inhibited. the service returns an HTTP 500 response to the caller unless an error rule is configured. back-end protocol level error handling is controlled by the Process Backend Errors property of the Multi-Protocol Gateway service. This loop can continue indefinitely unless the queue manager detects the message 46 DataPower SOA Appliances: Integrating with WebSphere MQ . because the error does not match the error rule. the service generates an automatic error message. 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 Process Backend Errors property When enabled. However. Enabling automatic backout When a message remains on a request (GET) queue after a failure.Process Backend Errors property In general. the error rule does not capture it. For example. To have the Gateway automatically generate an error message in all error cases. the Process Backend Errors property uses the response rule in a processing policy to handle any error messages. the configured error rule processes the error. Automatic Backout property With the Automatic Backout property enabled. When enabled. transactions successfully complete even though an error occurred. set Process Backend Errors to off. the service uses the response rule of the processing policy to process any message received with the error. If the Process Backend Errors property is set to off. You can then optionally configure an error rule in the processing policy to handle the error condition. 2. In the Units of Work field. 2. In the Backout Queue Name field. In the Automatic Backout field. queue managers. 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. 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. designate an alternative queue. the MQ Front Side Handler object must be restarted to synchronize the settings. and so forth.x. Error handling 47 . from the MQ Queue Manager object. queues. If you modify the settings on the WebSphere MQ server queue. 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. The retrieved settings override the values configured in the MQ Queue Manager object.left on the queue and removes it. If this value matches both of the following criteria. In the Backout Threshold field. When the MQ Queue Manager object defines backout values and the Retrieve Backout Settings is enabled. set the value to on. Reading the MQRC in a style sheet Within a style sheet. 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. click View List of Event Codes. Scroll down to the mq category. specify the number of times for the message to be reprocessed. 4.x. 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. view the reason codes in the WebGUI. the handler uses any existing backout values. If the WebSphere MQ server does not contain backout settings. either empty or populated.x]: The get call timed out before receiving any messages (Reason Code 2033) To 1. 3. the response code is a WebSphere MQ error: v Starts with the number 2 v Has a length equal to 4 Chapter 5. set the value to 1 to expose the backout fields. use the following steps: Select Administration from the navigation bar. 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. 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. 3. Under the Debug heading. you can capture MQ reason codes by using the dp:response-header extension function to read the x-dp-response-code protocol response code. The following style sheet uses an XML file called mqrc-codes.0"> <xsl:output method="xml"/> <xsl:template match="/"> <xsl:variable name="mqData" select="document(’local:///mqrc-codes.The following example checks the MQRC with dp:response-header(’x-dpresponse-code’) and depending on the reason code. <xsl:variable name="mqrc" select="normalize-space(dp:response-header(’x-dp-response-code’))" /> <xsl:if test="starts-with($mqrc.set the error-protocol-response code to 200 if the client is HTTP --> <dp:set-variable name="’var://service/error-protocol-response’" value="’200’"/> <dp:set-http-response-header name="’x-dp-response-code’" 48 DataPower SOA Appliances: Integrating with WebSphere MQ . the associated text error message.org/soap/envelope" extension-element-prefixes="dp" exclude-result-prefixes="dp" version="1. The style sheet captures the MQRC when used in an On error (on-error) action in the processing rule.set the error-protocol-response code to 200 if the client is HTTP --> <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> <!-.org/1999/XSL/Transform" xmlns:dp="http://www.$mq-msg)"/> </xsl:message> <!-. issues dp:reject to trigger an error rule.w3. include a table with MQ reason codes and corresponding messages in an XML file in a style sheet.com/extensions" xmlns:env="http://schemas.xmlsoap. <?xml version="1.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.datapower. is not available.0" encoding="utf-8"?> <xsl:stylesheet xmlns:xsl="http://www. such as “The get call timed out before receiving any messages” for MQRC 2033. To retrieve the text of the error. ’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. ’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) ** : ’.xml that contains the MQRC and the associated error text. The XML file format is provided after the style sheet. 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 . for example. This situation might occur. Error handling 49 . and a backout queue defined. Setting this variable will prevent an accumulation of uncommitted messages on the GET queue. event-code. </mqrc-codes> Using the error-ignore service variable The service variable. but erroneous datagram messages require a manual PUT operation to a front-side backout queue. the service does not run any error handling method and produces a regular response. Successful datagram messages complete the PUT operation to the back-side queue.xml file used in the example contains the error text for MQ reason codes provided in View List of Event Codes. You can then use a style sheet to implement customized manual error handling. When an MQGET operation gets a message from the request queue.value="’200 OK’"/> <env:Envelope> <env:Body> <env:error> <xsl:value-of select="concat(’ ** MQ Reason Code (mqrc) ** : ’. gets or sets a flag to control how the MQ Front Side Handler object processes error conditions. Therefore. the transaction does not commit and the message remains uncommitted on the GET queue. 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. Process Backend Errors enabled. If this happens repeatedly. and error-msg Here is an example file showing the child elements for the MQ reason codes 2003 and 2009: <?xml version="1. For instance. uncommitted messages can accumulate on the request queue and the DataPower appliance connections can hang. in a development environment where a style sheet fails to compile and the PUT operation does not complete. var://service/error-ignore. if any error causes an error rule to run.$mqrc)"/> </env:error> </env:Body> </env:Envelope> </xsl:otherwise> </xsl:choose> </xsl:template> </xsl:stylesheet> The mqrc-codes. If the value is set and is greater than zero. The file has the following elements: v A root element <mqrc-codes> v A child element <mqrc> with three attributes: code. . error-msg="Connection was broken (Reason Code 2009)"/> . the MQPUT operation is not complete. Chapter 5. consider a service with units of work enabled. Test whether the message contained a reply-to-qm that was different then the request-qm used. The style sheet performs the following steps: 1. Tests whether error handling should be performed based on the message type. Creates and injects the MQOD header with the remote queue manager and queue information.Disable the default ’backout’ logic useful when DP must construct an actual error reply --> <dp:set-variable name="’var://service/error-ignore’" value="’1’"/> <!-. Generates an error message. 3.0" encoding="UTF-8"?> <xsl:stylesheet xmlns:xsl="http://www. Tests whether the message originated from a remote queue manager. The variable also can be set with a Set variable action as the first action in the error rule. removing the message from the GET queue. 2. Disables the default backout logic. 4.Do not perform this error handling for datagrams. assume this is a remote qm and create an MQOD to let MQ route the message --> <xsl:if test="dp:variable(’var://context/mq/requestqm’) != dp:variable(’var://context/mq/replytoqm’)"> <!-.w3. the MQPUT operation to the backout queue indicates successful completion of the transaction and the MQCMIT operation occurs. Sets the ReplyToQM back to the original requestqm queue manager and clears out the ReplyToQ queue. If so. 5.With the error-ignore service variable set to 1. since no response is expected --> <xsl:if test="dp:variable(’var://context/mq/msgtype’) != ’8’"> <!-.0" xmlns:dp="http://www. <?xml version="1.Set the reply-to-qm back to the original request-qm.Create and inject the MQOD with the remote queue manager and queue info --> <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 DataPower SOA Appliances: Integrating with WebSphere MQ .datapower. 6. and clear out the reply-to-q --> <dp:set-response-header name="’ReplyToQM’" value="dp:variable(’var://context/mq/requestqm’)" /> <dp:set-response-header name="’ReplyToQ’" value="’’" /> <!-.org/1999/XSL/Transform" version="1. Note that the error-ignore service variable is set to 1 at the top of the style sheet to disable the default backout logic. 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.com/extensions" extension-element-prefixes="dp" exclude-result-prefixes="dp"> <xsl:template match="/"> <!-. this might be needed to send the original request message to a remote dead letter queue. Datagram traffic with Units of Work enabled Since datagram is one way traffic with no response expected. If necessary. For instance. 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. For instance. if an error rule is invoked in an MQ to MQ environment that has Units of Work enabled. The error rule acts as an error handler and allows you to create custom error messages. 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. If the return code is an MQ error. 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. Typically. The error rule can generate an appropriate SOAP fault. but here wrap the original input an an error node --> <error> <xsl:copy-of select="dp:variable(’var://context/mq/input’)"/> </error> </xsl:template> </xsl:stylesheet> Using an error rule In a processing policy.Typically. Error rules work in conjunction with the other error handling methods described in this chapter. 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. non-XML error. 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.</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> <!-. generate and return a SOAP Fault. Use the following error processing methods: Chapter 5. Error handling 51 . invoke an error rule by using dp:reject. MQ to MQ traffic calls for different error handling depending on the type of message and whether Units of Work is enabled. or other error response. an error rule is invoked when an error occurs during processing. v Optional: Specify an error rule if desired. 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. the processing policy will have a request rule but no response rule. as well as send the original request message or a SOAP fault to another queue. v Enable Automatic Backout and specify the associated Backout Threshold and Backout Queue Name settings on the MQ Queue Manager object. v If Units of Work is enabled. Use the following error processing methods: v Set the Process Backend Errors property to on. 52 DataPower SOA Appliances: Integrating with WebSphere MQ . 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 a Request rule. specify an error rule with the var://service/errorignore service variable set to 1. v Optional: Specify an error rule with the var://service/error-ignore service variable set to 1.v Set the Process Backend Errors property to off. enable Automatic Backout and specify the associated Backout Threshold and Backout Queue Name settings on the MQ Queue Manager object. v If Units of Work is enabled. a Response rule. however. v If Units of Work is enabled. Datagram traffic with custom error handling Since datagram is one way traffic with no response expected. 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. Request and reply traffic With two way traffic in the request and reply traffic pattern. 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. Use the following error processing methods: v Set the Process Backend Errors property to on. and an Error rule. specify an error rule with the var://service/errorignore service variable set to 1. When the AAA action executes. you can improve messaging performance. all MQPUT calls wait for a response to be returned from the queue manager. the system extracts this list of pairs and forwards the results as a nodeset to the AAA Authentication phase. Additional configuration options This chapter contains information about additional configuration options. For the applications that require verification of delivery at the time of each put operation. by choosing instead to put messages asynchronously. or both authenticate and authorize. v The queue manager does not return the success or failure of each call. If high qualities of service are not required. users should choose to put the message synchronously to a queue. Normally. Then. When an application puts a message asynchronously. A Processing Metadata object contains a list of the header name-value pairs. you can also use values taken from the MQ header to implement Transport Independent AAA. For example. an application can put a message to a queue without waiting for a response from the queue manager.Chapter 6. You can use this to improve messaging performance in some situations. This is done using a Processing Metadata object. The AAA Authentication phase must © Copyright IBM Corp. the application waits for the queue manager to confirm that it has processed the MQI request. Asynchronous put operations Using an asynchronous put operation. 2006. The AAA Extract Identity phase can use a Processing Metadata object. a transaction in a DataPower service with an MQ Front-side handler will be rolled back in a transactional context. you can choose to put the messages asynchronously to a queue for better performance. the following statements apply: v MQPUT calls do not wait for a response to return from the queue manager. against an external authority. Authentication and authorization A Multi-Protocol Gateway can use all of the standard AAA methods available through an AAA Policy object. For "fire-and-forget" applications. In addition to the standard methods. particularly for applications that put large numbers of small messages to a queue in a DataPower transaction. you can examine a WS-Security header to obtain an identity that can be used to authenticate or authorize. This is the default behavior. 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. 2010 53 . If any error in any previous asynchronous call is found. when an application puts a message or messages on a queue. The DataPower appliance supports asynchronous put operations when the backend server is WebSphere MQ V7. the MQBACK and MQCMIT calls are respectively issued to the MQ Queue Managers in the front-side handler and in the backend. the batch is rolled back together. No separate commit or rollback is performed for each message. you might get duplicate messages in the backend queue. WebSphere MQ V7 introduces another component into the messages. not in the headers. The batch size for batch request processing is configured in the MQ Front Side Handler object. the MQ Front Side Handler gets request messages of a specified batch size from the request queue and process the requests in one batch. which would then be returned to the custom Authentication phase style sheet. Only enable batch request processing when using the same MQ Queue Managers in the front-side handler and as on the backend. Otherwise. The message descriptor is a fixed set of headers. 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.weight. and commits each request separately. When batching is off. The default is 0.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. A property is a named piece of data in name-value pair format. namely the message descriptor or headers and the message data or payload. the message will be committed into the backend queue again. When the second Multi-Protocol Gateway transaction is completed. The request in the front-side handler gets rolled back and the Multi-Protocol Gateway transaction restarts. The namespace for the property name is hierarchical and splits the name into components by dots. not the message data. If parsing is enabled. 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 DataPower appliance supports the processing of message properties when the backend server is WebSphere MQ V7. In this case. The WebSphere MQ server processes the headers only. all requests in the batch will be committed. If any one of the requests fails. completes processing. A property is not treated as part of the message payload. Batch request processing In batch request processing. the Processing Metadata object could contain just the UserIdentity node of the MQ header. For example. the MQ Front Side Handler gets the request. there is a Properties component. In addition to the fixed descriptor and the message data. When all requests are processed. Consider a scenario in which all messages must contain a UserIdentity value authenticated by a local LDAP authority. meaning batch processing disabled. for example car. You can only add the customized information in the message payload. Message Properties WebSphere MQ V6 messages have two parts. the server returns the messages with 54 DataPower SOA Appliances: Integrating with WebSphere MQ . The following data types are the supported types: boolean. a message selector “sport = 'football'” will limit messages to those that have a message property named “sport” with a value “football”. integer8. and binary string respectively. Manipulating message properties in the processing policy Message properties display in the probe and can be manipulated in custom style sheets.year" type="int32">1997</Property> <Property name="car. the command line.set the new MQMP headers --> Chapter 6. Enable message properties parsing for the MQ Front Side Handler object with the WebGUI. Filtering messages by properties You can filter the incoming messages by the properties by specifying a selection string. integer16. and delete message properties using a custom stylesheet in a Binary Transform (xformbin) action. For example. not the payload. When the probe is turned on. <?xml version="1. integer32. or with the Selector query parameter of the url-open extension element. The property values have specific data types. the command line. float64. update. Additional configuration options 55 . A selector is a variable-length string containing a SQL92 query. or with the ParseProperties query parameter of the url-open extension element.0"> <xsl:output method="xml" encoding="UTF-8"/> <xsl:template match="/"> <xsl:variable name="newMQMP"> <MQMP> <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> <!-. and the WebSphere MQ Server returns the messages without properties. and integer64. If parsing is disabled. The following stylesheet appends four properties to the incoming requests.0" encoding="UTF-8"?> <xsl:stylesheet version="1.domestic" type="boolean">TRUE</Property> <Property name="car. boolean. The selection is based on the message properties. You can add. string. integer (32 bit). The selection string filters the messages delivered to the DataPower appliance from a queue or a subscription. float32. Specify the SQL92 query filter for the MQ Front Side Handler object with the WebGUI. the DataPower appliance does not request the properties with the message when issuing an MQGET call. use the MQMP tab to display the message properties. byte string. The properties are of type string.their properties.color" type="string">red</Property> <Property name="car. code> The hex string “41 42 43 44 45” is “65 66 67 68 69” in decimal. v For the properties of byte string (type = “hexstr”). v The default type of the property value is string. integer32. Note that in the case of MQ. byte string. the value of car."/> </xsl:template> </xsl:stylesheet> Note the following points when you specify the name. the Log action that delivers a copy of an entire message to a remote facility and the standard Count and Duration monitors. The Resource Class of an SLM policy offers the ability to select WebSphere MQ-specific attributes. 68. For example. integer16. and 69 are “A”. hexstr. Enclose the property value with the <Property> and </Property> tags. you can notify. float32. you can also log messages by sending a copy of the message to a particular remote queue by using a Results action. These include Log Targets that send selected log messages to remote facilities off the appliance. such as SNMP. and value for a property: v Each <Property> element in the <MQMP> header represents a message property. Ordered messaging The DataPower appliance supports the processing of messages in the order in which they appear in the message queue. v The DataPower appliance supports the following data types for the type attribute: boolean. “D”. logging. “B”. such as Reply Queue Name and Request Queue Name. Through this capability. and “E” respectively. integer8. type.<dp:set-request-header name="’MQMP’" value="$result-mqmp"/> <xsl:copy-of select=". You implement SLM by including an SLM action in the Processing policy of the Multi-Protocol Gateway. The bytes 65.code will be saved as ABCDE when the property is specified with the following byte string: <car. If the type attribute is not specified. and int64. “C”. The feature provides the following support: 56 DataPower SOA Appliances: Integrating with WebSphere MQ . string. Use the name and type attributes to specify the property name and type respectively. Monitoring. the Service Level Monitor capability is also available. int8. Because MQ runs on a Multi-Protocol Gateway. the value should be in hexadecimal. rotating log files.code type="hexstr">4142434445</car. 66. Specify the type attribute with the following literals: boolean. This queue can then simply be archived. int32. float32. v The boolean literals are TRUE and FALSE. string. the appliance treats the given property as string type. shape and throttle traffic in accordance with policy rules that can filter by credentials (who is asking) and by resources (to do what). float64. float64. and status All of the standard capabilities of the Multi-Protocol Gateway can be applied to monitoring and logging of MQ transactions. 67. int16. You can use all of the standard means that are offered by a Gateway to collect status information. and integer64 types. without needing to know anything about the applications that are interested in that information. 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. Publishers generate this information in the form of messages. Instead of including a specific destination address in each message. Topics are key to the successful delivery of messages in a publish and subscribe system. a publisher assigns a topic to each message. A publisher can publish information about more than one topic. the subscription determines which publications are forwarded to the subscriber. and delivers the message to each of those subscribers. The provider of information is called a publisher. The following components specify the topic string to publish: Chapter 6. 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. 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. Publish and subscribe using topic strings Publish and subscribe messaging allows users to decouple the provider of information from the consumers of that information.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. The queue manager matches the topic with a list of subscribers who have subscribed to that topic. Publishers supply information about a subject. The consumer of the information is called a subscriber. and the WebSphere MQ server distributes the information to subscribers of that specific topic. called publications that they want to publish and define the topic of these messages. Additional configuration options 57 . Subscribers create subscriptions that describe the topic that the subscriber is interested in. Thus. The MQ client publishes information directly to the WebSphere MQ server. Subscribers can make multiple subscriptions and can receive information from many different publishers. publish and subscribe functionality is integrated into the queue manager. A topic is a character string that describes the subject of the information that is published. see Message Processing Modes in the reference objects section of the IBM WebSphere DataPower Integration Appliance XI50: Multi-Protocol Gateway Developers Guide. In WebSphere MQ V7. If you specify a subscription topic and a GET queue. v For nondurable subscriptions. from more than one publisher. An attempt to resume a subscription currently in use by another connection will cause the call to fail with MQRC_SUBSCRIPTION_IN_USE. the subscription topic is ignored. the subscription is no longer valid and no more messages will be put to the subscriber queue. the subscription remains in place. For durable subscriptions.v MQ Front Side handler v Backend URL v url-open() extension element Subscribe to topic strings In WebSphere MQ publish and subscribe. Nondurable subscriptions Nondurable subscriptions exist only as long as the subscribing application's connection to the queue manager remains open. there is always only one connection working to poll the available publications. about the same or different topics. The WebSphere MQ server automatically creates the subscription queue for the managed subscriptions. These saved publications will be received later when the Multi-Protocol 58 DataPower SOA Appliances: Integrating with WebSphere MQ . A subscriber can receive messages. 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. Durable subscriptions Durable subscriptions continue to exist when the connection to the queue manager is closed. 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. Thus. another subscription to the same topic will be created. a subscriber is an application that requests information about a specific topic from a queue manager in a publish and subscribe network. multiple concurrent connections will lead to the receiving of duplicate publications. In the context of DataPower. but you can not do both. The subscription is removed when the subscribing application disconnects from the queue manager. When the Multi-Protocol Gateway is up again. In the context of DataPower. When the subscribing application disconnects. Subscriptions are nondurable or durable. The subscribers do not receive any retained message that is published before the subscription is made. The following points apply to nondurable and durable subscriptions: v All subscriptions made by DataPower are managed subscriptions. a queue manager will continue to send publications to the durable subscription even when the Multi-Protocol Gateway is down. only a single user (connection) can have the named subscription at any one time. for both of the durable and nondurable subscriptions in DataPower. when the Multi-Protocol Gateway is down or disabled. 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. or /ibm/message-broker. Here are some of the methods available to create this configuration. Use “#” or “+” for wildcard matching. v The Proxy can employ an MQ Front Side Handler to get SOAP request messages from a WebSphere MQ queue. By using wildcards in the subscription topic string. Chapter 6. a subscription name is required. The default option MQCO_KEEP_SUB is used for closing a durable subscription in DataPower. dpmq://mq-qm/?SubscribeTopicString=# v Subscribes to every topic in /ibm/datapower/. In the topic-based wildcard scheme. When closing a durable subscription. Additional configuration options | | | | | 59 . wildcards operate on topic elements within the topic string. To permanently delete a durable subscription. Because most WSDL files indicate an HTTP endpoint. the created subscribers can subscribe to multiple topics at one time. for example /ibm/datapower. such as /ibm/# or /ibm/+/+. /ibm/wmq. To use an MQ Front Side Handler with the Proxy. DataPower supports the topic-based wildcard scheme. specify the URI in the format of /<MQ FSH name>?RequestQueue=<GetQ>. and optionally place any response on a corresponding reply queue. Subscription names must be unique within a queue manager so that it can be used to identify a subscription. v The Proxy can employ a statically-defined back end that uses WebSphere MQ queues to put requests and get responses. 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. you might need to manually change the Proxy type property to static backend from the typical default of static-from-wsdl.Gateway is up again. 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. Publications will continue to be sent to the subscription queue. the handle to the subscription is closed but the subscription made is kept on the WebSphere MQ server. Subscribe to topic strings using wildcards By specifying a subscription topic string. In WebSphere MQ. v The Proxy can employ a Results (or Results Async) action in the Processing Policy that sends messages to a WebSphere MQ queue. You will then need to specify the backend URL using the MQ URL syntax. two wildcard schemes are supported: topic-based wildcard scheme and character-based wildcard scheme. use the WebSphere MQ Explorer or the MQSC commands. If you don't want to place any response on a corresponding reply queue. For example. the following MQ URLs specify a subscription topic string using wildcards: v Subscribes to all topics. you need to specify the local URI in the Proxy endpoint configuration in the format of /<MQ FSH name>?RequestQueue=<GetQ>&ReplyQueue=<PutQ>. With durable subscriptions. This includes headers in the following formats: v MQMD v MQRFH2 v MQRFH v MQIIH v MQDLH v MQCIH The MQMD. some architectures allow for the selection of WebSphere MQ messages based on values contained in the JMS message headers. JMS messages over MQ The DataPower service recognizes and parses JMS headers in WebSphere MQ messages.. which contains the parsed JMS headers. Table 4. The system now adds these XML documents to the header manifest as “X-MQRFH2-Data-xxxx” headers. Figure 6.. the methods will differ. The JMS header consists of the MQRFH2 structure followed by a number of short XML documents. A JMS header follows after the standard MQMD header structure. If a WebSphere MQ message contains multiple MQRFH2 headers. The appliance supports WebSphere MQ messages with one MQRFH2 header. This extracted nodeset can then be examined for the desired attributes. Header manifest Header MQMD Value <MQMD>.MQ and JMS It is possible to transport JMS messages over an WebSphere MQ system. You can examine the nodeset contained in the var://service/header-manifest variable. only the last one is parsed. 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. Although you can use the service to read and select messages based on JMS header values regardless of release.Format field value is MQRFH2.</MQMD> 60 DataPower SOA Appliances: Integrating with WebSphere MQ . In this case. The DataPower service views JMS messages over MQ as illustrated in Figure 6. do not use these variables. The Multi-Protocol Gateway and the Web Service Proxy provide all of the functionality that these legacy services offer.. Header manifest (continued) Header MQRFH2 X-MQRFH2-Data-0 X-MQRFH2-Data-1 Value <MQRFH2>. see the section on legacy MQ service variables in the IBM WebSphere DataPower SOA Appliances: Extension Elements and Functions Catalog. Additionally.</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 appliance provides a number of legacy MQ service variables..Table 4. Chapter 6. Additional configuration options 61 . For a list of these variables. Because these variables are not available to the Multi-Protocol Gateway or Web Service Proxy. 62 DataPower SOA Appliances: Integrating with WebSphere MQ . Click Add. See “Defining the properties and headers configuration” on page 65 for details. Define the advanced configuration. In the Name field. select a queue manager. See “Defining the basic configuration” for details. click enabled. enter the name for the object. Click Apply to save the changes to the running configuration. 2010 63 . click disabled. In the Get Queue field. See “Defining the publish and subscribe configuration” on page 65 for details. 7. From the Queue Manager list. © Copyright IBM Corp. 2. Define the basic configuration of the handler. Select Objects → Protocol Handlers → MQ Front Side Handler to display the MQ Front Side Handler catalog. 3. 6. Set Administrative State to identify the administrative state of the configuration. 5. specify the name of the GET queue. v v To make inactive. Referenced objects This chapter contains information about creating objects that are referenced. enter a descriptive summary. Optional: In the Comments field. Configuring a WebSphere MQ handler An MQ Front Side Handler object handles MQ protocol communications with DataPower services. 4. Defining the basic configuration To define the basic configuration for an MQ Front Side Handler: 1. 4. or associated with. Define the properties and headers configuration.Appendix. These fields are only supported with WebSphere MQ V7 queue managers. 5. Define the publish and subscribe configuration. 2006. 8. Optional: Click Save Config to save the changes to the startup configuration. see IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ. To make active. High-level configuration To configure an MQ Front Side Handler: 1. 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 “Defining the advanced configuration” on page 66 for details. the configuration of other objects. 3. 2. This section provides information about configuring an MQ Front Side Handler. When a message is too large for a queue. the appliance uses existing backout properties.jsp 64 DataPower SOA Appliances: Integrating with WebSphere MQ . off on The variable returns the name of the queue manager | | off (Default) The variable returns the name of the queue manager group. In the CCSI field. If there are no backout properties. specify the number of seconds before an MQGET operation returns if no messages are available. see the following web site: http://www. Use the Retrieve Backout Settings field to determine whether to retrieve the backout threshold and backout queue name from the MQ server. If these properties already exist in the MQ Queue Manager object. a low value will increase network traffic. specify the Coded Character Set Identifier (CCSID) that the remote MQ queue manager converts output data. backout is disabled. The value is passed directly to the MQ API. (Default) Do not retrieve backout settings 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. The minimum is 1. specify the cumulative value of the MQGET options that are applicable to an MQ message in decimal or hexadecimal format. 8. On retry. or request the queue manager to reassemble the segments into a single message that is returned by the MQGET call. either empty or populated.ibm.6. See the “MQGMO_* (Get Message Options)” topic in the “Constants” section of the WebSphere MQ Information Center for details. 7. specify the name of the PUT queue. The default is 1. 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. the DataPower appliance uses the higher priority backout settings from the MQ server. and by providing a buffer large enough to accommodate the entire message. Segmentation is a technique that allows the queue manager or application to split the message into smaller pieces. The application that retrieves the message can either handle the multiple segments one-by-one. that are stored in the MQ Queue Manager object. At the same time. and place each segment on a queue as a separate physical message. MQ queue managers do not support segmentation. the appliance use those values. In the The number of concurrent MQ connections field. 11. The default CCSID is for ISO-8859-1 (latin-1).com/software/globalization/ccsid/ccsid_registered. MQ queue managers might not be configured to support segmentation. In the Polling Interval field. In the Get Message Options field. The default is 30. 10. Setting a low value will help to detect quickly network connectivity issues and queue manager power shutdown. 9. The next attempt will be performed immediately. an attempt to put the message on the queue fails. For a list of CCSID. In the Put Queue field. specify the number of concurrent MQ connections to allocate. The reassembly request is achieved by specifying the MQGMO_COMPLETE_MSG option (65536) on the MQGET call. On z/OS. The default is 4097 (decimal value for the MQGMO_WAIT and the MQGMO_SYNCPOINT_IF_PERSISTENT options). The minimum is 1. If MQ server does not contain backout settings. On other operating systems. 12. Note: Ensure that the associated queue manager supports the MQGMO_COMPLETE_MSG option. In the Selector field. this field is ignored. Use the Parse Properties field to specify whether to parse the properties of the incoming message from a queue or from a subscription. 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. For additional information. In the Publish Topic String field. 2. (Default) Specifies that parsing is disabled.This property is meaningful only when the MQ Queue Manager object has the Convert Input property set to on. None (Default) No header MQRFH MQRFH header MQRFH2 MQRFH2 header Appendix. specify the selector as a variable-length string containing a SQL92 query. 3. when selected. In the Subscription Name field. Note: These fields are only supported with WebSphere MQ V7 queue managers. on off Specifies that parsing is enabled. Referenced objects 65 . The following headers after MQMD. specify a topic string associated with the identified queue manager. Note: This field is only supported with WebSphere MQ V7 queue managers. see the section on Message Properties in IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ. For additional information. In the Subscribe Topic String field. this field is ignored. Defining the properties and headers configuration To define the properties and headers configuration for an MQ Front Side Handler: 1. If the Get Queue is specified. select the MQ header structure from which to extract the Content-Type header. By default only the MQMD header is parsed. Defining the publish and subscribe configuration To define the publish and subscribe configuration for an MQ Front Side Handler: 1. 2. see the section on Message Properties in IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ. The handler publishes messages to this topic string. 3. The WebSphere MQ server returns the messages with the properties. specify the name for the durable subscription. and the WebSphere MQ server returns the messages without the properties. Use the Exclude Message Headers check boxes to select which types of MQ headers after the MQMD to remove from the message. specify a topic string. If the Put Queue field is specified. The DataPower appliance does not request the properties with the message when issuing an MQGET call. server1:1414 v host-name(port) — For example. In the Batch Size field. server1 For IPv6 The value for the Host Name field can be in one of the following formats: v [address]:port — For example. Click XPath Tool for help building the XPath expression.1. 2202::148:248 v host-name:port — For example. server1 66 DataPower SOA Appliances: Integrating with WebSphere MQ . specify the number of messages to be processed as a batch. 2. Note: This field is only supported with WebSphere MQ V7 queue managers. server1:1414 v host-name(port) — For example. server1(1414) v host-name — For example. If Header to Extract Content-Type is not None. 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. For IPv4 The value for the Host Name field can be in one of the following formats: v address:port — For example.10.10. The value of the host depends on IP family.1. 2202::148:248(1414) v address — For example.1. If you do not specify the port. 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. Use the Async Put field to specify whether to put a message to a queue without waiting for a response from the queue manager. 10.5.10. 10.2 v host-name:port — For example. Defining the advanced configuration To define the advanced configuration for an MQ Front Side Handler: 1. The value for the Host Name field includes the listening port on the server. distributed send queues and receive queues are managed by a queue manager. on off Specifies that the put operation is asynchronous. 10.2(1414) v address — For example. the default is 1414. The default is 0 which disables batch processing.2:1414 v address(port) — For example. [2202::148:248]:1414 v address(port) — For example. server1(1414) v host-name — For example. (Default) Specifies that the put operation is synchronous. MQ Queue Manager In WebSphere MQ. From the SSL Cipher Specification list. 2. Note: To integrate with a MQ for z/OS. Securing with an SSL Proxy Profile object To define secure communication with an SSL Proxy Profile.pem or MQkeys. select an SSL Proxy Profile from the SSL Proxy Profile list. 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 Appendix. the stash file must be MQkeys. and must end with the sth file extension. For secure communication. The key database file contains the required keys and certificates. select the cipher suite.kdb. Referenced objects 67 . upload or fetch them. Securing with GSKit To define secure communication with artifacts from GSKit: 1. Use this information when configuring the SSL Proxy Profile to communicate with the MQ Queue Manager. 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. Table 5. If these files are not on the appliance. For example. if the key database file is MQkeys.Securing communication with remote queue managers Before configuring an MQ Queue Manager object. you must use an instance of the SSL Proxy Profile object. The stash file holds encrypted passwords that allow programmatic access to the key database.sth. determine whether to support secure communication with the remote queue manager. the DataPower appliance uses the selected SSL Proxy Profile. The stash file must reside in the same directory as the key database file. must have the same file stem. define the location of the key database file. Each key database file has an associated stash file. 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. With the SSL Key Repository controls. Enabling units of work The appliance supports only local units of work. 68 DataPower SOA Appliances: Integrating with WebSphere MQ . 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. When using synch points. This timeout value must be greater than the negotiated heartbeat interval but less than the keep alive interval. the keep alive interval is the negotiated heartbeat interval plus 60 seconds. The KAINT attribute on the MQ server defines the timeout value for a channel. 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. 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. In other words. 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). This type of synchronization ensures that the remote system and the application with which it interacts remain in synch. In these cases. A transaction (unit of work) can consist of one or more MQ messages. not the entire transaction. If the transaction fails and the message is left available on the queue. the same queue manager must maintain the request queue and the reply queue. the appliance removes that dynamic connection from the cache. When specified. Set the Units of Work field to 1. Some queue managers use an automatic timeout setting (the KAINT attribute set to AUTO). When an inactive connection reaches this threshold. A synch point commits or rolls back each MQ message. not global units of work between the appliance and the remote MQ queue manager. Not all channels have an explicit keep alive interval on the MQ server.Table 5. No other configuration setting on the appliance can time out an MQ connection. the appliance can attempt to get the message and process it again. the appliance deletes the dynamic queue manager. When the cache no longer contains dynamic connections. To use unit of work: 1. Some MQ systems require synchronization on each unit of work. the system commits the entire transaction or rolls back the entire transaction. Without a dynamic queue manager. This value indicates that the queue manager uses synch points. there is no connection with the remote MQ server. v The negotiated heartbeat interval is between the appliance and the backend MQ server. DEAD. click enabled. As the MQ Queue Manager object continues to “re-get” the message. 2. When the backout count exceeds the backout threshold. This value enables the automatic backout of poison messages. specify the name of the queue manager.QUEUE. Referenced objects 69 . A poison message is any message that the receiving application does not know how to process. Use as an alternative to the default SYSTEM. the poison message must be programmatically rerouted by a custom style sheet in the request rule. Typically. no heartbeat flow is exchanged when waiting for a message on the channel. Click Objects → Network → MQ Queue Manager. Optional: In the User Name field. If 0. Specify the name of the backout queue in the Backout Queue Name field. In the Channel Heartbeat field. which accounts for the initial processing attempt. enter a descriptive summary. Messages that have exceeded the backout threshold are rerouted to this queue. Set Administrative State to identify the administrative state of the configuration. Configuring Queue Manager objects To configure queue managers that makes the DataPower appliance aware of the location of remote queue managers: 1. The greater of the two values is used. click disabled.If not enable. v To make inactive. Optional: In the Channel Name field. In the Name field. 4. v To make active. The backout queue contains messages that cannot be processed or delivered. the backout count continues to increase. undeliverable messages are discarded. enter the name for the object. Optional: In the Comments field. Higher level protocols are responsible for detecting and for retransmitting any undeliverable message within the transaction. Specify the number of reprocessing attempt per message in the Backout Threshold field. This setting negotiates the heartbeat value with the channel. This setting does not set the heartbeat on the channel. 6. specify the name of the channel. 8. 3. which leaves the message on the input queue. If not enabled.LETTER. Usually an application rolls back the GET of this message. Optional: In the Queue Manager Name field. Use when the name of a nondefault queue manager is assigned to this queue manager.SVRCONN. Use an integer greater than 1 to specify the maximum number of reprocessing attempts per message. If not specified. Click Add. Set Automatic Backout to on. specify a plaintext string that identifies this client to the MQ server. 10. The count starts at 0. In the Host Name field.DEF. 5. 7. the name of the queue is SYSTEM. Appendix. the MQ Queue Manager object moves the message to the backout queue. 9. specify the host name or IP address and port of the MQ server. However.Backoutcount) is increased. 4. the default port is 1414. The default value specifies two attempts: the initial attempt and a single reprocessing attempt. specify the approximate time in seconds between heartbeat flows on a channel when waiting for a message on a queue. 2. the backout count (MQMD. The default is 1. 3. select the instance. Determine whether to support secure communication with the remote queue manager. you can use the shared conversations feature to control the number of connections between the DataPower appliance and the MQ server. In the Total Connection Limit field. For more information about sharing conversations. 17. b. In the Backout Queue Name field. specify the size in bytes of the largest message to process.boulder.htm. 16. Optional: In the Maximum Message Size field. The output CCSID is specified on the MQ Front Side Handler.com/infocenter/wmqv7/v7r0/index. In the Cache Timeout field. 18. | | | | | | | | | | 70 DataPower SOA Appliances: Integrating with WebSphere MQ .jsp?topic=/ com. From the SSL Cipher Specification list. b. Use a value that is equal to or greater than the MaxMsgLength attribute of the channel and of the queue on the MQ server. the number of times to attempt to connect at the short interval. specify the number of seconds that the appliance retains a dynamic connection in the connection cache. b. specify a value that is greater than 1. select the cipher suite.doc/cs13220_. 14. d. Optional: In the Sharing Conversations field. c. Optional: Define open connection behavior.mq.csqzaf. Setting a short retry interval. specify the number of reprocessing attempt per message. In WebSphere MQ Version 7 or later. Define the retry behavior. select the location of the key database file. 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. In the Backout Threshold field. In the Initial Connections field. This conversion is done by the remote queue manager. a.ibm. Set Automatic Backout to indicate whether to enable the automatic backout of poison messages. v To secure with an SSL Proxy Profile: From the SSL Proxy Profile list. specify the total number of open connections to allow. disable this setting. The retry behavior controls the connection behavior of the MQ Queue Manager object when it initially tries to connect to the queue manager.ibm. 13. With the SSL Key Repository controls. v To secure with artifacts from GSKit: a. see the following web site: http://publib. a. In the Units of Work field. 15. Determine whether to support transactions (units of work) with roll back support. 12. If MQ error 2110 is encountered. specify the name of the backout queue. not the DataPower appliance. specify the number of connections to open immediately when the queue manager starts. To enable conversation sharing. Set Convert Input to indicate whether the queue manager can convert input messages to a different CCSID than the one in the original message. indicate whether to support transactions.11. define the sharing conversation behavior by specifying the maximum number of conversations to share a single TCP/IP connection. Use a value that is greater than the negotiated heartbeat interval but less than the keep alive interval. Supported formats are 1.10). In the MQCSP User ID field. 1) In the Retry Interval field. 20.1(1) or (1) to tell TCP to bind to port 1 and for a range of ports use (1. b.jsp 23. See the WebSphere MQ Information Center for more information. 2) In the Retry Attempts field. Take the following actions to define your MQCSP configuration in the MQ Queue Manager: a. After the reaching this number of attempts. This setting filters the generation of identical error messages to MQ logging target.1.ibm. the range must be greater than the total number of allowed connections.1.1. 3) In the Long Retry Interval field. When enabled. b. specify the local address for outbound connections. specify the CCSID to present to the queue manager when the DataPower appliance connects to it. For a list of CCSID. This setting does not affect attempts to PUT or GET messages over established. specify the user ID value of the MQCSP connection security parameter. Set Automatic Retry to define whether to attempt to reconnect to the remote queue manager at every defined interval. select an XML Manager. The MQCSP support enables the authorization service to authenticate a user ID and password.AlternateUserId or MQMD. If the port is set. This value (long retry interval) must be greater than the value of the short interval. Optional: Define the CCSID to present to the remote queue manager on connection. Optional: Define the MQCSP configuration. 19. Referenced objects 71 . specify the number of seconds between the creation of error messages when failed connections are retried.1.1 or 1. In the Local Address field. the queue manager repeatedly attempts to reconnect using the retry interval setting. change the retry attempts setting to 0. active connections. To disable.a. see the following web site: http://www. 4) In the Reporting Interval field. | | | | | | | | | | | | | | | | Appendix. define the behavior for retrying failed connections. you need to define a security exit in the MQ Queue Manager on the MQ server. Click the Advanced tab.1. Set Alternate User to determine whether to use MQOD. You can specify the MQCSP connection security parameters structure on an MQCONNX call. 22.1(1. b. Either an inconsistent MQCSP user ID or an inconsistent password causes a failure of connection between the DataPower appliance and the MQ server. 21. Click the Advanced tab.com/software/globalization/ccsid/ccsid_registered.1.10) or 1. use the long retry interval. From the XML Manager list.UserIdentifier during MQOPEN and MQPUT operations. Before using the MQCSP support. specify the number of seconds between automatic retry attempts. specify the number of seconds between retrying the failed connections after the number of retry attempts is reached. In the Character Code Set ID field. If the long retry interval is disabled. 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. specify the number of attempts to retry the failed connection. This setting has the same effect as setting the MQCCSID environment variable for an MQ client. a. amqzag. you can configure multi-instance queue managers for the failover in the WebSphere MQ server. the standby instance automatically takes over the data and logs from the active instance.ibm. Click Apply to save the changes to the running configuration. Optional: Click Save Config to save the changes to the startup configuration. An MQ Queue Manager Group object defines one primary queue manager and one or more backup queue managers. Notes: a. see “MQ Queue Manager” on page 66. and the backup queue manager to the other instance. | | | | | | | | | | | | | | | | | | | | Working with the multi-instance feature in the WebSphere MQ server In WebSphere MQ server Version 7.1 or later. Connect the primary queue manager to one of the instances of a queue manager in the MQ server. and this queue manager automatically takes over all the data and logs from the queue manager connected to the original active instance. The active instance and the standby instance of a queue manager reference the same queue manager data and logs in shared network storage.0. see http://publib.boulder.doc/fa70150_.jsp?topic=/ com.| | | | | | | | | c. b. The appliance periodically monitors the status of the primary queue manager. the appliance reassigns this queue manager to its former role.com/infocenter/wmqv7/v7r0/index.mq. 72 DataPower SOA Appliances: Integrating with WebSphere MQ . the connection fails and the MQ Queue Manager object is not up. For information about creating MQ Queue Manager objects. In the MQCSP Password field. MQ Queue Manager Group An instance of the MQ Queue Manager Group object implements a failover configuration.htm. c. 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. 24. 25. When the active instance fails. In the event of failure. If the active instance in the MQ server fails. a warning occurs and the MQ Queue Manager object is not up. To work with the multi-instance feature in the WebSphere MQ server for the failover in the DataPower appliance. If neither the MQCSP user ID or the password is defined. If both are defined but one is not consistent with that defined on the MQ server. If only one is defined. For more information about multi-instance queue managers. When the original primary queue manager returns to service. the DataPower appliance selects the queue manager connected to the standby instance. and accepts re-connections from clients and channels. the DataPower appliance connects to the MQ server without MQCSP settings. the appliance selects a backup queue manager to assume the role of the primary queue manager.ibm. specify the password value of the MQCSP connection security parameter. you need to configure your MQ Queue Manager Group object with the multi-instance queue managers in the WebSphere MQ server. 4. Optional: Click Save Config to save the changes to the startup configuration. Appendix. see the online help. Define the configuration. 2.Configuring MQ Queue Manager Group objects To configure an MQ Queue Manager Group object: 1. Click Add to display the configuration screen. 5. Referenced objects 73 . 3. For information about the values to specify in the available fields. Click Apply to save the changes to the running configuration. Select Objects → Network Settings → MQ Queue Manager Group to display the catalog. 74 DataPower SOA Appliances: Integrating with WebSphere MQ . or service is not intended to state or imply that only that IBM product. DataPower. these symbols indicate U. program. these changes will be incorporated in new editions of the publication. registered or common law trademarks owned by IBM at the time this information was published. © Copyright IBM Corp. and/or other countries. and WebSphere are registered trademarks of the International Business Machines Corporation in the United States or other countries.shtml. IBM may have patents or pending patent applications covering subject matter described in this document. INCLUDING. BUT NOT LIMITED TO. This information could include technical inaccuracies or typographical errors. Adobe is either a registered trademark or trademark of Adobe Systems Incorporated in the United States. this statement may not apply to you. Such trademarks may also be registered or common law trademarks in other countries. Consult your local IBM representative for information about the products and services currently available in your area. in writing. it is the user's responsibility to evaluate and verify the operation of any non-IBM product.S. You can send license inquiries.ibm. Any functionally equivalent product. IBM may make improvements or changes in the product(s) or the program(s) described in this publication at any time without notice. Any reference to an IBM product. EITHER EXPRESS OR IMPLIED.S. A current list of IBM trademarks is available on the Web at “Copyright and trademark information” at www. services.Notices and trademarks This information was developed for products and services offered in the U. THE IMPLIED WARRANTIES OF NON-INFRINGEMENT. program. MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.A. the IBM logo. 2006. or features discussed in this document in other countries. program. Trademarks IBM. IBM may not offer the products. NY 10504-1785 U. Changes are periodically made to the information herein.S. 2010 75 . to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk. therefore.A. Some states do not allow disclaimer of express or implied warranties in certain transactions.com/legal/ copytrade. The furnishing of this document does not grant you any license to these patents. program. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol (® or ™). or service that does not infringe any IBM intellectual property right may be used instead. or service may be used. or service. However. 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. Inc. or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems. in the United States and other countries. other countries.Microsoft and Windows are trademarks of Microsoft Corporation in the United States. Other product and service names might be trademarks of IBM or other companies. 76 DataPower SOA Appliances: Integrating with WebSphere MQ . AlternateUserId 71 MQRC_SUBSCRIPTION_IN_USE 58 MQSO_NEW_PUBLICATIONS_ONLY option 58 K KAINT attribute. 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. 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. MQ 72 basic configuration MQ Front Side Handler 63 bold typeface vi M messages poison.UserIdentifier 71 MQOD. 2006. MQ 68 backup queue managers. typefaces durable subscriptions 58 vi E error 2010.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. 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 70 error 2110. 2010 77 . MQ server key database file MQ 67 68 L licensing sending inquiries 75 B backout queue. QUEUE 68 T topic strings subscribing 58 wildcards 59 trademarks 75 transactions MQ automatic backout 68 MQMD.LETTER.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 DataPower SOA Appliances: Integrating with WebSphere MQ . MQ 68 SYSTEM.DEAD.P patents 75 poison messages. 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 primary queue manager. . Printed in USA .

Comments

Description