Using the IBM WebSphere MQ Outbound Adapter

Overall Behavior

Within a production, an outbound adapter is associated with a business operation that you create and configure. The business operation receives a message from within the production, looks up the message type, and executes the appropriate method. This method usually executes methods of the associated adapter.

The IBM WebSphere MQ outbound adapter (EnsLib.MQSeries.OutboundAdapterOpens in a new tab) provides settings that you use to specify the following:

Creating a Business Operation to Use the Adapter

To create a business operation to use the EnsLib.MQSeries.OutBoundAdapter, you create a new business operation class. 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 operation class:

• Your business operation class should extend Ens.BusinessOperationOpens in a new tab.

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

• In your class, the INVOCATION parameter should specify the invocation style you want to use, which must be one of the following.

  • Queue means the message is created within one background job and placed on a queue, at which time the original job is released. Later, when the message is processed, a different background job will be allocated for the task. This is the most common setting.

  • InProc means the message will be formulated, sent, and delivered in the same job in which it was created. The job will not be released to the sender’s pool until the message is delivered to the target. This is only suitable for special cases.

• Your class should define a message map that includes at least one entry. A message map is an XData block entry that has the following structure:

  XData MessageMap
  {
  <MapItems>
    <MapItem MessageType="messageclass">
      <Method>methodname</Method>
    </MapItem>
    ...
  </MapItems>
  }
  
  

  

• Your class should define all the methods named in the message map. These methods are known as message handlers. Each message handler should have the following signature:

  Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status
  

  

  Here Sample is the name of the method, RequestClass is the name of a request message class, and ResponseClass is the name of a response message class. In general, these methods will refer to properties and methods of the Adapter property of your business operation.

• For other options and general information, see Defining a Business Operation Class.

The following example shows the general structure that you need:

Class EMQS.NewOperation1 Extends Ens.BusinessOperation 
{
Parameter ADAPTER = "EnsLib.MQSeries.OutboundAdapter";

Parameter INVOCATION = "Queue";

Method SampleCall(pRequest As Ens.Request,
                  Output pResponse As Ens.Response) As %Status
{
  Quit $$$ERROR($$$NotImplemented)
}

XData MessageMap
{
<MapItems>
  <MapItem MessageType="Ens.Request">
    <Method>SampleCall</Method>
  </MapItem>
</MapItems>
}
}

Creating Message Handler Methods

When you create a business operation class for use with EnsLib.MQSeries.OutboundAdapterOpens in a new tab, typically your main task is writing message handlers for use with this adapter, that is, methods that receive production messages and then send messages to an IBM WebSphere MQ server.

Each message handler method should have the following signature:

Method Sample(pReq As RequestClass, Output pResp As ResponseClass) As %Status

Here Sample is the name of the method, RequestClass is the name of a request message class, and ResponseClass is the name of a response message class.

In general, the method should do the following:

1. Examine the inbound request message.

2. Call the SendMessage() method of the adapter to send a message to the configured queue of IBM WebSphere MQ.

3. Examine the response.

4. Use information in the response to create a response message (an instance of Ens.ResponseOpens in a new tab or a subclass), which the method returns as output.

   For information on defining message classes, see Defining Messages.

5. Make sure that you set the output argument (pOutput). Typically you set this equal to the response message. This step is required.

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

Available Methods

The adapter provides the following method:

SendMessage()

Method SendMessage(pBody) As %Status

Sends a message to the configured queue of IBM WebSphere MQ message. Note that pBody can be either a datatype or a character stream, but cannot be binary data or an object.

Example

The following business operation sends a message to IBM WebSphere MQ:

Class EMQS.Operation Extends Ens.BusinessOperation 
{

Parameter ADAPTER = "EnsLib.MQSeries.OutboundAdapter";

Parameter INVOCATION = "Queue";

Method Send(pRequest As OutboundMsg, Output pResponse As OutboundMsgResponse) As %Status
{
    Set string=pRequest.Body

    //Get part of the message so that we can provide
    //some information in the response message
    Set snippet=$Extract(string,1,50)

    //send the message to the configured queue
    Set status=..Adapter.SendMessage(string)
    If $$$ISERR(status) {
        Do $System.Status.DisplayError(status)
        Quit $$$ERROR($$$GeneralError,"Error sending message")
    }

    //create the response message
    Set pResponse=##class(EMQS.OutboundMsgResponse).%New()
    Set pResponse.Body="Message sent: "_snippet

    Quit status
}

XData MessageMap
{
<MapItems>
    <MapItem MessageType="EMQS.OutboundMsg">
        <Method>Send</Method>
    </MapItem>
</MapItems>
}

}

Adding and Configuring the Business Operation

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

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

2. Enable the business operation.

3. Configure the adapter to access an IBM WebSphere MQ queue and send 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.

   • Indicate the character set that the messages are in.

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

4. Run the production.