Using the IBM WebSphere MQ Inbound Adapter

Overall Behavior

First, it is useful to understand the details that you specify for the adapter. The EnsLib.MQSeries.InboundAdapterOpens in a new tab 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.InboundAdapterOpens in a new tab) periodically checks the given queue, retrieves any messages, and sends the messages (as instances of EnsLib.MQSeries.MessageOpens in a new tab) 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:

More specifically:

1. When the adapter is initialized, it connects to the given queue manager and queue, using the given channel.

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

3. When the adapter retrieves a message, it does the following:

   1. The adapter creates an instance of the EnsLib.MQSeries.MessageOpens in a new tab 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.MessageOpens in a new tab instance as input.

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

5. The ProcessInput() method then calls your custom OnProcessInput() method, passing the EnsLib.MQSeries.MessageOpens in a new tab instance as input. The requirements for this method are described 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.

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

• Your business service class should extend Ens.BusinessServiceOpens in a new tab.

• In your class, the ADAPTER parameter should equal EnsLib.MQSeries.InboundAdapterOpens in a new tab.

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

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
}
}

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.MessageOpens in a new tab. Also, pOutput is the generic output argument required in the method signature.

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

1. Examine the MQ message (EnsLib.MQSeries.MessageOpens in a new tab) and decide how to use it. See “Using the Received Message,” later.

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

3. For the request message, set its properties as appropriate, using values in the MQ message.

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

   Each of these methods returns a status (specifically, an instance of %StatusOpens in a new tab).

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

6. Return an appropriate status. This step is required.

See the example at the end of this topic.

Using the Received Message

The adapter sends an instance of EnsLib.MQSeries.MessageOpens in a new tab 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:

1. Add an instance of your business service class to the production.

2. Enable the business service.

3. 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 Settings for the IBM WebSphere MQ Adapters.

4. Run the production.