Skip to content

WebSphere MQSeries Adapter

Overview

The Neuron WebSphere MQSeries adapter allows Neuron ESB to interact with IBM WebSphere MQSeries in a variety ways, from monitoring MQSeries Queues to placing data into MQSeries Queues, either through local or remote Queue Managers. The adapter allows Neuron ESB to manage and expose an IBM WebSphere MQSeries Queue as another messaging endpoint that any client on the bus can communicate with, without knowledge of IBM WebSphere MQSeries technology. The adapter supports a number of message exchange patterns (MEPS), exposing them as Modes of the adapter.

Once the Neuron WebSphere MQSeries adapter is registered and an Adapter Endpoint is created, all configuration is managed through the property grid of the Adapter located on the properties tab of the Adapter Endpoint’s Details Pane as shown in Figure 1.

Neuron WebSphere Adapter – Property Grid
Figure 1: Neuron WebSphere Adapter – Property Grid – All configurations for adapter is managed through the property grid. Properties are divided into 4 sections, General, Publish Properties, Response Properties and Subscribe Properties.

Features

The Neuron WebSphere MQSeries adapter supports a number of IBM MQSeries features, including the following:

  • Client side API Support
  • Server side API Support
  • Extended Transactional Client
  • Correlation Options
  • XA Transactions
  • EBCDIC translations
  • Support for MQMD, MQRFH2, MQDLH, MQCNO, MQCIH (CICS) and MQIIH (IMS) headers

Requirements

The Neuron WebSphere MQSeries adapter is installed as part of the core Neuron ESB installation. The adapter is represented by 3 assemblies that are located within the \Adapters folder under the root of the default Neuron ESB installation directory:

  • Neuron.Esb.Adapters.WebSphereMQ.dll
  • Neuron.Esb.Adapters.WebSphereMQHeaderRW.dll
  • Neuron.Esb.Adapters.WebSphereMQHeaders.dll

To use the adapter, it must be registered within the Neuron ESB Explorer Adapter Management Window. Within the Management Window, the adapter will appear with the name “WebSphere MQ Adapter”. Once registered, a new Adapter Endpoint can be created and configured.

The Neuron WebSphere MQSeries adapter supports connectivity to the following versions of IBM WebSphere MQSeries

  • 6.0.2.6 and higher

If using the Client side API, the WebSphere MQSeries client must be installed on the Neuron server.

If using the Server side API, the WebSphere MQSeries server must be installed on the Neuron server.

If using Transactions with the Client side API option, then the IBM WebSphere Extended Transactional Client must be installed on the Neuron server.

Supported Modes

The Neuron WebSphere MQSeries adapter supports 4 modes of communication (MEPS) with IBM WebSphere MQSeries.

Publish

Publish mode allows Neuron ESB to monitor an IBM MQSeries Queue by regularly polling, de-queuing all the messages, and publishing those messages to a Neuron ESB Topic. Messages can be read either transactionally or non-transactionally and can be batched for performance.  This is a one way MEP.

Configuration

Configuring the Publish mode of the Neuron WebSphere MQSeries adapter requires that minimally, the following properties are set:

General Properties
  • Queue Machine Name – Netbios name of MQSeries Server
  • Queue Manager – Queue Manager for Request Queue
  • Queue Name – Request Queue
  • Transactional – True or False
  • WMQ Binding – Determines client or server side API
  • WMQ Binding Channel – Usually accept default.
Publish Properties
  • Polling Interval – Number of seconds between Request Queue reads
  • Publish Topic – Neuron ESB Topic to publish the MQSeries Request Message on. Corresponding Reply message will be received from this Topic and written to the ReplyTo Queue.

The defaults can be accepted for most other properties.

None of the properties within the “Subscribe Properties” or “Response Properties” section of the property page need to be set.

Subscribe

Subscribe mode allows Neuron ESB to write published messages to an IBM MQSeries Queue. Neuron ESB takes received ESB messages and will write them either transactionally or non-transactionally.  This is a one way MEP.

Configuration

Configuring the Subscribe mode of the Neuron WebSphere MQSeries adapter requires that minimally, the following properties are set:

General Properties
  • Queue Machine Name – Netbios name of MQSeries Server
  • Queue Manager – Queue Manager for Request Queue
  • Queue Name – Request Queue
  • Transactional – True or False
  • WMQ Binding – Determines client or server side API
  • WMQ Binding Channel – Usually accept default.

The defaults can be accepted for most other properties.

None of the properties within the “Publish Properties” or “Response Properties” section of the property page need to be set.

Request/Reply

Request/Reply mode allows applications (examples of which are z/OS CICS COBOL programs, AS/400 based programs, and other MQSeries host applications) to act as Neuron ESB service consumers with a synchronous request-response MEP using the IBM WebSphere MQSeries transport. Using this mode, an MQSeries based application could call any service provider application through Neuron ESB.

When acting as service consumer, the MQSeries application will put a message (MQ type REQUEST) on a request queue (MYREQ). The request message will specify (in MQ field ReplyToQ and ReplyToQMgr) where the application expects the response e.g. MYRESP queue and how (in MQ field Report) it wants to correlate the response. The MQ adapter will pick up the request message from the request queue (MYREQ) and publish it to the Neuron ESB bus as an ESB message with Request semantic. The adapter will wait for the response message on the bus, and when it arrives, it will put a message (MQ type REPLY) on the specified destination (ReplyToQ/ReplyToQMgr) e.g. MYRESP queue. The response message will be correlated as specified in the request. See Figure 2.

Service Consumer – Request/Response mode of the Neuron ESB WebSphere MQSeries Adapter
Figure 2: Service Consumer – Request/Response mode of the Neuron ESB WebSphere MQSeries Adapter – Allows IBM based applications to act as service consumers to Neuron ESB.
Configuration

Configuring the Request/Response mode of the Neuron WebSphere MQSeries adapter requires that minimally, the following properties are set:

General Properties
  • Queue Machine Name – Netbios name of MQSeries Server
  • Queue Manager – Queue Manager for Request Queue
  • Queue Name – Request Queue
  • Transactional – True or False
  • WMQ Binding – Determines client or server side API
  • WMQ Binding Channel – Usually accept default.
Publish Properties
  • Polling Interval – Number of seconds between Request Queue reads
  • Publish Topic – Neuron ESB Topic to publish the MQSeries Request Message on. Corresponding Reply message will be received from this Topic and written to the ReplyTo Queue.
Response Properties
  • Correlation Options
  • ReplyTo Queue Manager Name
  • ReplyTo Queue Name

The defaults can be accepted for most other properties.

Additionally, the ReplyTo Queue Manager and Queue Name can be overwritten at runtime by setting the following Neuron ESB custom adapter context properties:

  • wmq.MQMD.ReplyToQ
  • wmq.MQMD.ReplyToQMgr

Solicit/Response

Solicit/Response mode allows applications (examples of which are z/OS CICS COBOL programs, AS/400 based programs, and other MQSeries host applications) to act as Neuron ESB service providers with a synchronous request-response MEP using the IBM WebSphere MQSeries transport. Using this mode, an MQSeries based application could provide services to any client on the bus through Neuron ESB.

When acting as service provider, the MQSeries application will accept service requests on a queue (SREQ). It will process the request and put the response on a queue. The response queue might be fixed and defined by the application, but it can be specified in the MQ service request message, or specified as a property of the adapter.

In this mode, the Neuron WebSphere MQSeries adapter will subscribe to request messages on the bus. When it receives a message it will put a message (MQ type REQUEST) on the request queue (SREQ). The adapter will specify (in MQ field ReplyToQ and ReplyToQMgr) where it expects the response e.g. SRESP queue and how (in MQ field Report) it wants to correlate the response. These values can be set as adapter properties and should be able to match the capabilities of the actual MQ application.

Service Provider – Solicit/Response mode of the Neuron ESB WebSphere MQSeries Adapter
Figure 3: Service Provider – Solicit/Response mode of the Neuron ESB WebSphere MQSeries Adapter – Allows IBM based applications to act as service providers to Neuron ESB.
Configuration

Configuring the Solicit/Response mode of the Neuron WebSphere MQSeries adapter requires that minimally, the following properties are set:

General Properties
  • Queue Machine Name – Netbios name of MQSeries Server
  • Queue Manager – Queue Manager for Request Queue
  • Queue Name – Request Queue
  • Transactional – True or False
  • WMQ Binding – Determines client or server side API
  • WMQ Binding Channel – Usually accept default.
Response Properties
  • Correlation Options
  • ReplyTo Queue Manager Name
  • ReplyTo Queue Name

The defaults can be accepted for most other properties.

Additionally, the ReplyTo Queue Manager and Queue Name can be overwritten at runtime by setting the following Neuron ESB custom adapter context properties:

  • wmq.MQMD.ReplyToQ
  • wmq.MQMD.ReplyToQMgr

None of the properties within the “Publish Properties” section of the property page need to be set.

Property Table

Section NameProperty NameRequiredDescription
General  These properties are used for all modes of the adapter
 MQ Translation OptionsYesDefault is None. Options are None, UTF8 and Unicode. Used at runtime when reading messages from a queue using either Publish mode, Solicit/Response or Request/Response mode. If either UTF8 or Unicode are selected, message body translation will be  attempted by using the ReadUTF or ReadString methods of the MQ Message. If None is selected, then the encoder will be determined by the MQ Message CharacterSet property.
 Queue MachineYesNetbios name of the IBM WebSphere MQSeries Server
 Queue ManagerYesName of the IBM WebSphere MQSeries Queue Manager
 Queue NameYesName of the IBM WebSphere MQSeries Queue
 TransactionalYesDefault is False.  True to use transactions.
 WMQ BindingYesDefault is Server.  Options are Server or Client. This determines which API the adapter will use. If Server, then the IBM WebSphere MQSeries server MUST be installed on the Neuron ESB server.
 WMQ Binding ChannelYesDefault is SYSTEM.DEF.SVRCONN. Options are SYSTEM.DEF.SVRCONN and SYSTEM.ADMIN.SVRCONN. Custom channel may be manually entered.
Publish Properties  These properties are only used when the adapter is in either Request/Response or Publish mode.
 Batch SizeYesDefault is 100. Determines number of messages within a transaction scope published from the Queue to the Neuron ESB Topic.
 Maximum Get Retry FailuresYesDefault is 10.  Defines the maximum number of attempts to read the queue, when an error occurs during the read. Once the limit is reached, the Publish Adapter Endpoint will be disconnected.
 Polling IntervalYesDefault is 5 seconds. The amount of time to wait to regularly poll the Queue for messages to publish to the Neuron ESB Topic.
 Publish TopicYesNeuron ESB Topic to publish the MQ Message to.
 Wait IntervalYesDefault is 500 milliseconds. Amount of time to wait for a message to arrive in the Queue being monitored (Polled). If no message is found, the queue is closed, and then checked during the next Polling Interval. If a message is found, the queue is immediately checked for another message, until no more messages are found.
Response Properties  These properties are only used when the adapter is in either Solicit/Response or Request/Response mode.
 Correlation OptionsYesDefault is MQRO_COPY_MSG_ID_TO_CORREL_ID. Options are MQRO_PASS_CORREL_ID, MQRO_USE_DEFAULT and MQRO_COPY_MSG_ID_TO_CORREL_ID. This property controls how the response message is correlated with the original request message and determines what value is written to the CorrelationID property of the Request message.
 Maximum Wait TimeYesDefault is 5 minutes (300,000 milliseconds).  Maximum amount of time to wait for a response message to be received.  Minimum allowed value is 1000. Unlimited wait is not supported. If the Expiry property of the MQ Message is set (to not unlimited), that value * 10 will be used instead.
 ReplyTo Queue Manager NameNoOptional. Only required if the ReplyTo Queue Manager Name is different from Request Queue Manager Name specified in the Queue Manager Name property of the General section. Corresponds to the IBM MQMD.ReplyToQMgr header property.
 ReplyTo Queue NameNoOptional. Only required if the ReplyTo Queue Name is different from Request Queue Name specified in the Queue Name property of the General section. Corresponds to the IBM MQMD.ReplyToQ header property.
Subscribe Properties  These properties are used with all modes of the adapter EXCEPT Publish.
 MQ FormatYesDefault is the MQ equivalent to NONE (padded empty string). Options are the MQ values of empty string (NONE) and MQSTR. This is used to set the MQ Message Format property.
 PersistenceYesDefault is DefinedByQueue. Options are None, Persistent and DefinedByQueue . Used to set the persistence property of the Queue before the MQ Message is written to it.

Many of the values within the Properties Table above can be configured and overridden by setting the appropriate IBM property or header value exposed through Neuron ESB custom properties. Please review the Metadata section below for more information.

Metadata

The Neuron ESB WebSphere MQSeries adapter exposes many of the IBM Properties and Header values as accessible Neuron ESB custom properties. The IBM Properties and Header values allow developers to provide a complete end-to-end solution that retains all message headers and properties from receipt to delivery; full fidelity of message-handling with no content or meta-data loss from end to end.

WebSphere MQ messages use a chained header of metadata that describes numerous types of information about the message including, but not limited to, metadata for JMS Queues, CICS Transactions, and Dead Letter queue data.

Each header contains the header data and data about the following header. The data about the following header includes the header name (for example, “RHF2 “), the CodedCharacterSetID, the Integer Encoding type (big endian or little endian), and the floating point encoding type.

When the Header name in the current header is blank “    “, then there is no header after the current one, and you have reached the last header before the message content.

Each header is defined in an IBM-provided C Header file named cmqc.h available with the WebSphere MQ SDK from IBM. The structure and field values are defined in the C Header file, which is used by the Adapter to decode and encode the headers on receipt and transmit.

These message properties affect the encoding and decoding of the actual message as it is transmitted.

Each header property is promoted to a Neuron ESB Custom property in the ESB message in the following format:

  • PropertyName = wmq.Header. Property
  • PropertyValue = String-encoded value of the property; that is, integers are converted to their string equivalents.

For example, the property name for the MQRFH2 StrucID would be “wmq.MQRFH2.StrucID” on an inbound message and the value would be “RHF2”.

Not all headers are currently supported. The supported headers include:

  • MQMD
  • MQRFH2
  • MQDLH
  • MQCNO
  • MQCIH (CICS)
  • MQIIH (IMS)

Refer to the IBM documentation for a list of all headers and properties associated with a WebSphere MQ Message.

NOTE:  All message properties are assumed to have the default IBM values unless specifically overridden by the developer.

IBM WebSphere MQSeries Header properties

Header Property Names
wmq.MQCIH.ADSDescriptor
wmq.MQCIH.AbendCode
wmq.MQCIH.AttentionId
wmq.MQCIH.Authenticator
wmq.MQCIH.CancelCode
wmq.MQCIH.CodedCharSetId
wmq.MQCIH.CompCode
wmq.MQCIH.ConversationalTask
wmq.MQCIH.CursorPosition
wmq.MQCIH.Encoding
wmq.MQCIH.ErrorOffset
wmq.MQCIH.Facility
wmq.MQCIH.FacilityKeepTime
wmq.MQCIH.FacilityLike
wmq.MQCIH.Flags
wmq.MQCIH.Format
wmq.MQCIH.Function
wmq.MQCIH.GetWaitInterval
wmq.MQCIH.InputItem
wmq.MQCIH.LinkType
wmq.MQCIH.NextTransactionId
wmq.MQCIH.OutputDataLength
wmq.MQCIH.Reason
wmq.MQCIH.RemoteSysId
wmq.MQCIH.RemoteTransId
wmq.MQCIH.ReplyToFormat
wmq.MQCIH.Reserved1
wmq.MQCIH.Reserved2
wmq.MQCIH.Reserved3
wmq.MQCIH.Reserved4
wmq.MQCIH.ReturnCode
wmq.MQCIH.StartCode
wmq.MQCIH.StrucId
wmq.MQCIH.StrucLength
wmq.MQCIH.TaskEndStatus
wmq.MQCIH.TransactionId
wmq.MQCIH.UOWControl
wmq.MQCIH.Version
wmq.MQCNO.ClientConnOffset
wmq.MQCNO.ClientConnPtr
wmq.MQCNO.ConnTag
wmq.MQCNO.Options
wmq.MQCNO.SSLConfigOffset
wmq.MQCNO.SSLConfigPtr
wmq.MQCNO.Version
wmq.MQCNO.strucId
wmq.MQDLH.CodedCharSetId
wmq.MQDLH.DestQMgrName
wmq.MQDLH.DestQName
wmq.MQDLH.Encoding
wmq.MQDLH.Format
wmq.MQDLH.PutApplName
wmq.MQDLH.PutApplType
wmq.MQDLH.PutDate
wmq.MQDLH.PutTime
wmq.MQDLH.Reason
wmq.MQDLH.StrucId
wmq.MQDLH.Version
wmq.MQIIH.Authenticator
wmq.MQIIH.CodedCharSetId
wmq.MQIIH.CommitMode
wmq.MQIIH.Encoding
wmq.MQIIH.Flags
wmq.MQIIH.Format
wmq.MQIIH.LTermOverride
wmq.MQIIH.MFSMapName
wmq.MQIIH.ReplyToFormat
wmq.MQIIH.Reserved
wmq.MQIIH.SecurityScope
wmq.MQIIH.StrucId
wmq.MQIIH.StrucLength
wmq.MQIIH.TranInstanceId
wmq.MQIIH.TranState
wmq.MQIIH.Version
wmq.MQRFH2.CodedCharSetId
wmq.MQRFH2.Encoding
wmq.MQRFH2.Flags
wmq.MQRFH2.Format
wmq.MQRFH2.NameValueCCSID
wmq.MQRFH2.NameValueData
wmq.MQRFH2.StrucId
wmq.MQRFH2.StrucLength
wmq.MQRFH2.Version
wmq.MQMD.StrucId
wmq.MQMD.Version
wmq.MQMD.Report
wmq.MQMD.MsgType
wmq.MQMD.Expiry
wmq.MQMD.Feedback
wmq.MQMD.Encoding
wmq.MQMD.CodedCharacterSetId
wmq.MQMD.Format
wmq.MQMD.Priority
wmq.MQMD.Persistence
wmq.MQMD.MsgId
wmq.MQMD.CorrelId
wmq.MQMD.BackoutCount
wmq.MQMD.ReplyToQ
wmq.MQMD.ReplyToQMgr
wmq.MQMD.UserId
wmq.MQMD.AccountingToken
wmq.MQMD.ApplIdentityData
wmq.MQMD.ApplOriginData
wmq.MQMD.GroupId
wmq.MQMD.MsgSequenceNumber
wmq.MQMD.Offset
wmq.MQMD.MsgFlags
wmq.MQMD.PutApplType
wmq.MQMD.PutApplName
wmq.MQMD.PutDate
wmq.MQMD.PutTime
wmq.MQMD.OriginalLength

In addition to the Header properties, there are also Connection Properties that are accessible only programmatically. There are two components to an MQ connection—the Queue Manager connection and the Queue connection. Setting these Connection Properties at runtime can control how Neuron ESB manages the connections to these resources.

The Queue Manager connection includes some simple properties, such as the Queue Manager Name, and also includes properties like the MQOO_ property set.

The Queue connection includes the MQGMO_ and MQPMO_ (MQ Get Options and MQ Put Options).

The above properties are exposed by the following property-naming conventions:

  • wmq.MQGMO.PropertyName
  • wmq.MQOO.PropertyName
  • wmq.MQPMO.PropertyName

IBM WebSphere MQSeries Connection properties

Message Settings
Get Message Options (GMO)
wmq.MQGMO.ACCEPT_TRUNCATED_MSG
wmq.MQGMO.ALL_MSGS_AVAILABLE
wmq.MQGMO.ALL_SEGMENTS_AVAILABLE
wmq.MQGMO.BROWSE_FIRST
wmq.MQGMO.BROWSE_MSG_UNDER_CURSOR
wmq.MQGMO.BROWSE_NEXT
wmq.MQGMO.COMPLETE_MSG
wmq.MQGMO.CONVERT
wmq.MQGMO.FAIL_IF_QUIESCING
wmq.MQGMO.LOCK
wmq.MQGMO.LOGICAL_ORDER
wmq.MQGMO.MARK_SKIP_BACKOUT
wmq.MQGMO.MSG_UNDER_CURSOR
wmq.MQGMO.NO_SYNCPOINT
wmq.MQGMO.NO_WAIT
wmq.MQGMO.SET_SIGNAL
wmq.MQGMO.SYNCPOINT
wmq.MQGMO.SYNCPOINT_IF_PERSISTENT
wmq.MQGMO.UNLOCK
wmq.MQGMO.VERSION
wmq.MQGMO.WAIT
 
Get Match Type Options
wmq.MQMO.MATCH_CORREL_ID
wmq.MQMO.MATCH_GROUP_ID
wmq.MQMO.MATCH_MSG_ID
wmq.MQMO.MATCH_MSG_SEQ_NUMBER
wmq.MQMO.MATCH_MSG_TOKEN
wmq.MQMO.MATCH_OFFSET
 
Message Types
wmq.MQMT.APPL
wmq.MQMT.DATAGRAM
wmq.MQMT.REPLY
wmq.MQMT.REPORT
wmq.MQMT.REQUEST
 
Queue Option Options
wmq.MQOO.ALTERNATE_USER_AUTHORITY
wmq.MQOO.BIND_AS_Q_DEF
wmq.MQOO.BIND_NOT_FIXED
wmq.MQOO.BIND_ON_OPEN
wmq.MQOO.BROWSE
wmq.MQOO.FAIL_IF_QUIESCING
wmq.MQOO.INPUT_AS_Q_DEF
wmq.MQOO.INPUT_EXCLUSIVE
wmq.MQOO.INPUT_SHARED
wmq.MQOO.INQUIRE
wmq.MQOO.OUTPUT
wmq.MQOO.PASS_ALL_CONTEXT
wmq.MQOO.PASS_IDENTITY_CONTEXT
wmq.MQOO.SAVE_ALL_CONTEXT
wmq.MQOO.SET
wmq.MQOO.SET_ALL_CONTEXT
wmq.MQOO.SET_IDENTITY_CONTEXT
 
Message Put Option (PMO)
wmq.MQPMO.ALTERNATE_USER_AUTHORITY
wmq.MQPMO.CONTEXT
wmq.MQPMO.FAIL_IF_QUIESCING
wmq.MQPMO.LOGICAL_ORDER
wmq.MQPMO.NEW_CORREL_ID
wmq.MQPMO.NEW_MSG_ID
wmq.MQPMO.NO_SYNCPOINT
wmq.MQPMO.SYNCPOINT
 
Message Reporting Options (PMRF)
wmq.MQPMRF.ACCOUNTING_TOKEN
wmq.MQPMRF.CORREL_ID
wmq.MQPMRF.FEEDBACK
wmq.MQPMRF.GROUP_ID
wmq.MQPMRF.MSG_ID

Messages

Defined messages are not required.

Was this article helpful?
Dislike 0
Previous: Create a Domain User
Next: Twilio Adapter