Using the IBM WebSphere MQ Inbound Adapter

This chapter describes the default behavior of the InterSystems IRIS® IBM WebSphere MQ inbound adapter (EnsLib.MQSeries.InboundAdapter) and describes how to use this adapter in your productions.

Overall Behavior

First, it is useful to understand the details that you specify for the adapter. The EnsLib.MQSeries.InboundAdapter class provides runtime settings that you use to specify items like the following:

The queue manager to use.
The channel specification to use. This specification includes the name of the channel to use, the transport used by the channel, the server name (or IP address) that is running the IBM WebSphere MQ server, and the port.
The message queue to check.
A polling interval, which controls how frequently the adapter checks for new input.

In general, the inbound IBM WebSphere MQ adapter (EnsLib.MQSeries.InboundAdapter) periodically checks the given queue, retrieves any messages, and sends the messages (as instances of EnsLib.MQSeries.Message) to the associated business service. The business service, which you create and configure, uses these messages and communicates with the rest of the production. The following figure shows the overall flow:

Diagram showing an MQ Series message entering a production and flowing through and IBM Web Sphere MQ inbound adapter

More specifically:

When the adapter is initialized, it connects to the given queue manager and queue, using the given channel.
The adapter regularly executes its OnTask() method, which retrieves a message from the queue (if a message is available). The polling interval is determined by the CallInterval setting.
When the adapter retrieves a message, it does the following:
1. The adapter creates an instance of the EnsLib.MQSeries.Message class and puts the message data into it.
2. The adapter calls the internal ProcessInput method of the associated business service class, passing the EnsLib.MQSeries.Message instance as input.
The internal ProcessInput() method of the business service class executes. This method performs basic production tasks such as maintaining internal information as needed by all business services. You do not customize or override this method, which your business service class inherits.
The ProcessInput() method then calls your custom OnProcessInput() method, passing the EnsLib.MQSeries.Message instance as input. The requirements for this method are described later in “Implementing the OnProcessInput Method.”

The response message follows the same path, in reverse.

Creating a Business Service to Use the Inbound Adapter

To use this adapter in your production, create a new business service class as described here. Later, add it to your production and configure it. You must also create appropriate message classes, if none yet exist. See “Defining Messages” in Developing Productions.

The following list describes the basic requirements of the business service class:

Your business service class should extend Ens.BusinessService.
In your class, the ADAPTER parameter should equal EnsLib.MQSeries.InboundAdapter.
Your class should implement the OnProcessInput() method, as described in “Implementing the OnProcessInput Method.”
For other options and general information, see “Defining a Business Service Class” in Developing Productions.

The following example shows the general structure that you need:

Class EMQS.Service Extends Ens.BusinessService 
{
Parameter ADAPTER = "EnsLib.MQSeries.InboundAdapter";

Method OnProcessInput(pInput As EnsLib.MQSeries.Message,
                      pOutput As %RegisteredObject) As %Status
{
   set tsc=$$$OK
   //your code here
   Quit tsc
}
}

Note:

Studio provides a wizard that you can use to create a business service stub similar to the preceding. To access this wizard, click File —> New and then click the Production tab. Then click Business Service and click OK. Note that the wizard provides a generic input argument. If you use the wizard, InterSystems recommends that you edit the method signature to use the specific input argument needed with this adapter; the input argument type should be EnsLib.MQSeries.Message.

Implementing the OnProcessInput() Method

Within your custom business service class, your OnProcessInput() method should have the following signature:

Method OnProcessInput(pInput As EnsLib.MQSeries.Message,
                      pOutput As %RegisteredObject) As %Status

Here pInput is the message object that the adapter will send to this business service; this is an instance of EnsLib.MQSeries.Message. Also, pOutput is the generic output argument required in the method signature.

The OnProcessInput() method should do some or all of the following:

Examine the MQ message (EnsLib.MQSeries.Message) and decide how to use it. See “Using the Received Message,” later in this chapter.
Create an instance of the request message, which will be the message that your business service sends.
For information on creating message classes, see “Defining Messages” in Developing Productions.
For the request message, set its properties as appropriate, using values in the MQ message.
Call a suitable method of the business service to send the request to some destination within the production. Specifically, call SendRequestSync(), SendRequestAsync(), or (less common) SendDeferredResponse(). For details, see “Sending Request Messages” in Developing Productions
Each of these methods returns a status (specifically, an instance of %Status).
Make sure that you set the output argument (pOutput). Typically you set this equal to the response message that you have received. This step is required.
Return an appropriate status. This step is required.

See the example at the end of this chapter.

Using the Received Message

The adapter sends an instance of EnsLib.MQSeries.Message to your business service. This object contains the message retrieved from the queue. It has three properties:

Body — The body of the message.
MessageID — The message ID.
BodySize — An integer that indicates the length of the message.

Example

The following business service retrieves messages and forwards them to a business host named EMQS.MessageProcessor.

Class EMQS.Service Extends Ens.BusinessService 
{

Parameter ADAPTER = "EnsLib.MQSeries.InboundAdapter";

Method OnProcessInput(pInput As EnsLib.MQSeries.Message,
pOutput As EMQS.InboundMsg) As %Status
{
    //create production message to carry the retrieved MQ message
    Set inbound=##class(EMQS.InboundMsg).%New()
    Set inbound.Body=pInput.Body
    Set inbound.MessageId=pInput.MessageId

    //forward this to the message processor
    Set tsc=..SendRequestSync("EMQS.MessageProcessor",inbound,.response)
    Set pOutout=response
    Quit tsc
}

}

The message class EMQS.InboundMsg is as follows:

Class EMQS.InboundMsg Extends Ens.Request
{

Property Body As %String (MAXLEN="");

Property MessageId As %String(MAXLEN = 128);

}

Adding and Configuring the Business Service

To add your business service to a production, use the Management Portal to do the following:

Add an instance of your business service class to the production.
Enable the business service.
Configure the adapter to access an IBM WebSphere MQ queue and retrieve messages. Specifically:
- Specify the queue manager, channel, and queue to access. The channel specification includes the name of the channel to use, the transport used by the channel, the server name (or IP address) that is running the IBM WebSphere MQ server, and the port.
- Specify the error log to use.
- Specify the character set to convert the messages to.
- Specify how often the adapter looks for messages.
These topics are discussed in the section “Settings for the IBM WebSphere MQ Adapters.”
Run the production.