Skip to main content

Using the IBM WebSphere MQ Inbound Adapter

This chapter describes the default behavior of the Ensemble IBM WebSphere MQ inbound adapter (EnsLib.MQSeries.InboundAdapterOpens in a new tab) and describes how to use this adapter in your productions. It discusses the following topics:

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:

generated description: inbound

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.

    Note:

    The message must be less than 32 KB in length unless long strings are enabled in Ensemble.

  4. The internal ProcessInput() method of the business service class executes. This method performs basic Ensemble 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 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 Ensemble Messages” in Developing Ensemble Productions.

The following list describes the basic requirements of the 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
}
}
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.MessageOpens in a new tab.

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 in this chapter.

  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 Ensemble Messages” in Developing Ensemble 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” in Developing Ensemble Productions

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

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.

Note:

The message retrieved from the queue must be less than 32 KB in length unless long strings are enabled in Ensemble.

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 Ensemble 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 an Ensemble production, use the Management Portal to do the following:

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

  2. Enable the business service.

  3. Configure the adapter to access an IBM WebSphere MQ queue and retrieve messages. Specifically:

    These topics are discussed in the section “Settings for the IBM WebSphere MQ Adapters.”

  4. Run the production.

FeedbackOpens in a new tab