Using IBM WebSphere MQ Adapters with Ensemble
Using the IBM WebSphere MQ Outbound Adapter
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter describes the behavior of the Ensemble IBM WebSphere MQ outbound adapter (EnsLib.MQSeries.OutboundAdapter) and describes how to use this adapter in your productions. It discusses the following topics:

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.OutboundAdapter) 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 Ensemble Messages in Developing Ensemble Productions.
The following list describes the basic requirements of the 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>
}
}
Note:
Studio provides a wizard that you can use to create a business operation stub similar to the preceding. To access this wizard, click File —> New and then click the Production tab. Then click Business Operation and click OK.
Creating Message Handler Methods
When you create a business operation class for use with EnsLib.MQSeries.OutboundAdapter, typically your main task is writing message handlers for use with this adapter, that is, methods that receive Ensemble 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 an Ensemble request message class, and ResponseClass is the name of an Ensemble 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.
    Note:
    The message must be less than 32 KB in length unless long strings are enabled in Ensemble.
  3. Examine the response.
  4. Use information in the response to create an Ensemble response message (an instance of Ens.Response or a subclass), which the method returns as output.
    For information on defining message classes, see Defining Ensemble Messages in Developing Ensemble Productions.
  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()
        }

    //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 an Ensemble production, use the Management Portal to do the following:
  1. Add an instance of your custom business operation class to the Ensemble production.
  2. Enable the business operation.
  3. Configure the adapter to access an IBM WebSphere MQ queue and send messages. Specifically:
    These topics are discussed in the section “Settings for the IBM WebSphere MQ Adapters.”
  4. Run the production.