using ibm websphere mq adapters with ensemble - intersystems

Using IBM WebSphere MQAdapters with Ensemble

Version 2012.231 August 2012

InterSystems Corporation 1 Memorial Drive Cambridge MA 02142 www.intersystems.com

Using IBM WebSphere MQ Adapters with EnsembleEnsemble Version 2012.2 31 August 2012 Copyright © 2012 InterSystems CorporationAll rights reserved.

This book was assembled and formatted in Adobe Page Description Format (PDF) using tools and information from the following sources:Sun Microsystems, RenderX, Inc., Adobe Systems, and the World Wide Web Consortium at www.w3c.org.The primary document developmenttools were special-purpose XML-processing applications built by InterSystems using Caché and Java.

, ,

Caché WEBLINK, Distributed Cache Protocol, M/SQL, M/NET, and M/PACT are registered trademarks of InterSystems Corporation.

, , , ,

InterSystems Jalapeño Technology, Enterprise Cache Protocol, ECP, and InterSystems Zen are trademarks of InterSystems Corporation.

All other brand or product names used herein are trademarks or registered trademarks of their respective companies or organizations.

This document contains trade secret and confidential information which is the property of InterSystems Corporation, One Memorial Drive,Cambridge, MA 02142, or its affiliates, and is furnished for the sole purpose of the operation and maintenance of the products of InterSystemsCorporation. No part of this publication is to be used for any other purpose, and this publication is not to be reproduced, copied, disclosed,transmitted, stored in a retrieval system or translated into any human or computer language, in any form, by any means, in whole or in part,without the express prior written consent of InterSystems Corporation.

The copying, use and disposition of this document and the software programs described herein is prohibited except to the limited extentset forth in the standard software license agreement(s) of InterSystems Corporation covering such programs and related documentation.InterSystems Corporation makes no representations and warranties concerning such software programs other than those set forth in suchstandard software license agreement(s). In addition, the liability of InterSystems Corporation for any losses or damages relating to or arisingout of the use of such software programs is limited in the manner set forth in such standard software license agreement(s).

THE FOREGOING IS A GENERAL SUMMARY OF THE RESTRICTIONS AND LIMITATIONS IMPOSED BY INTERSYSTEMSCORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTER SOFTWARE. FOR COMPLETE INFORMATIONREFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARE LICENSE AGREEMENT(S) OF INTERSYSTEMS CORPORATION,COPIES OF WHICH WILL BE MADE AVAILABLE UPON REQUEST.

InterSystems Corporation disclaims responsibility for errors which may appear in this document, and it reserves the right, in its sole discretionand without notice, to make substitutions and modifications in the products and practices described in this document.

For Support questions about any InterSystems products, contact:

InterSystems Worldwide Customer Support+1 617 621-0700Tel:+1 617 374-9391Fax:[email protected]:

Table of Contents

About This Book .................................................................................................................................... 1

1 About the Ensemble IBM WebSphere MQ Adapters ...................................................................... 31.1 Prerequisites ............................................................................................................................... 31.2 The IBM WebSphere MQ Inbound Adapter ............................................................................... 31.3 The IBM WebSphere MQ Outbound Adapter ............................................................................ 41.4 General Use ................................................................................................................................ 41.5 The MQ Adapters and the Event Log ......................................................................................... 4

2 Using the IBM WebSphere MQ Inbound Adapter .......................................................................... 52.1 Overall Behavior ........................................................................................................................ 52.2 Creating a Business Service to Use the Inbound Adapter .......................................................... 6

2.2.1 Development Tasks .......................................................................................................... 62.2.2 Configuration Tasks ......................................................................................................... 7

2.3 Implementing the OnProcessInput() Method ............................................................................. 72.3.1 Creating Request and Response Classes .......................................................................... 82.3.2 Using the SendRequestSync() Method ............................................................................ 82.3.3 Using the SendRequestAsync() Method .......................................................................... 9

2.4 Using the Received Message ...................................................................................................... 92.5 Example ...................................................................................................................................... 9

3 Using the IBM WebSphere MQ Outbound Adapter ..................................................................... 113.1 Overall Behavior ...................................................................................................................... 113.2 Creating a Business Operation to Use the Adapter .................................................................. 11

3.2.1 Development Tasks ........................................................................................................ 113.2.2 Configuration Tasks ....................................................................................................... 13

3.3 Creating Message Handler Methods ........................................................................................ 133.3.1 Available Methods .......................................................................................................... 14

3.4 Example .................................................................................................................................... 14

4 Configuring the Connection Details ................................................................................................ 154.1 Specifying the Queue Manager, Channel, and Queue .............................................................. 154.2 Specifying the Log File to Use ................................................................................................. 164.3 Specifying the Character Set of the Messages ......................................................................... 164.4 Specifying How Often to Check for Messages ........................................................................ 174.5 Example .................................................................................................................................... 17

5 Troubleshooting ................................................................................................................................ 19

Appendix A:Common Tasks in the Management Portal .................................................................. 21A.1 Accessing a Production ........................................................................................................... 21A.2 Adding a Business Host to a Production ................................................................................. 21A.3 Editing Runtime Settings of a Business Host .......................................................................... 22A.4 Creating Ensemble Credentials ............................................................................................... 22

Index ..................................................................................................................................................... 25

Using IBM WebSphere MQ Adapters with Ensemble iii

About This Book

This book describes how an Ensemble programmer can add IBM WebSphere MQ adapters to an Ensemble production, sothat the production can send messages to and retrieve messages from IBM WebSphere MQ. It does not contain details onthe IBM WebSphere MQ product.

This book contains the following sections:

• About the Ensemble IBM WebSphere MQ Adapters

• Using the IBM WebSphere MQ Inbound Adapter

• Using the IBM WebSphere MQ Outbound Adapter

• Configuring the Connection Details

• Troubleshooting

• Common Tasks in the Management Portal

For a detailed outline, see the table of contents.

For more information, try the following sources:

• Developing Ensemble Productions describes how to create Ensemble productions in general.

• Configuring Ensemble Productions describes how to configure the settings for Ensemble productions, business hosts,and adapters. It provides details on settings not discussed in this book.

• Managing Ensemble Productions includes information on monitoring and correcting the status of Ensemble adapters.It also includes information on common settings used in all business hosts.

Using IBM WebSphere MQ Adapters with Ensemble 1

1About the Ensemble IBM WebSphere MQAdapters

The Ensemble IBM WebSphere MQ inbound and outbound adapters enable your Ensemble productions to retrieve messagesfrom and send messages to message queues of Ensemble IBM WebSphere MQ. This chapter provides a brief introductionto these adapters.

It is assumed that you are reasonably familiar with the IBM WebSphere MQ product and have access to its formal docu-mentation.

1.1 PrerequisitesIn order to use Ensemble IBM WebSphere MQ inbound and outbound adapters, make sure that you have access to IBMWebSphere MQ v5.2 or higher. Specifically:

• The IBM WebSphere MQ client must be installed on the same machine as Caché.

• Make sure that you have rebooted the machine after installing the client, so that Caché is aware of the client.

• The client must have access to an IBM WebSphere MQ server.

• The username under which you run Ensemble must have permission to use the queue managers and the queues thatyou plan to use.

The adapters use a dynamic-link library that is automatically installed by Caché on all suitable platforms. (This isMQInterface.dll on Windows; the file extension is different for other platforms.) In turn, the Caché dynamic-link libraryrequires IBM WebSphere MQ dynamic-link libraries (the IBM WebSphere MQ client).

1.2 The IBM WebSphere MQ Inbound AdapterIn general, the inbound IBM WebSphere MQ adapter (EnsLib.MQSeries.InboundAdapter) accesses a given queue manager,using a given channel, retrieves messages from a given queue, and sends those messages (as instances ofEnsLib.MQSeries.Message) to the associated business service.

The adapter 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 thechannel, 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.

Note: Each retrieved message must be less than 32kB in length unless long strings are enabled in Ensemble.

1.3 The IBM WebSphere MQ Outbound AdapterThe IBM WebSphere MQ outbound adapter (EnsLib.MQSeries.OutboundAdapter) provides settings that you use to specifythe following:



• The message queue to send messages to.

It provides a method to send a message to the given queue.

Note: The message sent must be less than 32kB in length unless long strings are enabled in Ensemble.

1.4 General UseAt a high level, to include an adapter in a production, you do the following:

• Create a business host (specifically a business service or business operation) class that uses the adapter. You use theADAPTER parameter of the business host class to specify the adapter to use.

• Within that class, implement the methods you need. Your methods will typically use the properties and methods ofthe associated adapter, via the Adapter property of your business host.

• Add the business service or business operation to your production and provide values for any runtime settings.

In most cases, your custom code resides within your business host class. You do not typically need to customize the adaptersdirectly.

1.5 The MQ Adapters and the Event LogUnlike many other Ensemble adapters, the IBM WebSphere MQ inbound and outbound adapters do not write to the eventlog when they process messages sent to or received from outside Ensemble. To see the inbound and outbound traffic, youcan, however, use the message browser as usual.

4 Using IBM WebSphere MQ Adapters with Ensemble

About the Ensemble IBM WebSphere MQ Adapters

2Using the IBM WebSphere MQ InboundAdapter

This chapter describes the default behavior of the Ensemble IBM WebSphere MQ inbound adapter(EnsLib.MQSeries.InboundAdapter) and describes how to use this adapter in your productions. It discusses the followingtopics:

• Overall behavior that occurs if your production includes the EnsLib.MQSeries.InboundAdapter.

• How to create and configure a business service that uses this inbound adapter, in order to include theEnsLib.MQSeries.InboundAdapter in your production.

• Details on how to implement the OnProcessInput() method within that business service, including basic requirementsof that method.

• Details on the helper class that contains the message.

• An example.

2.1 Overall BehaviorFirst, it is useful to understand the details that you specify for the adapter. The EnsLib.MQSeries.InboundAdapter classprovides runtime settings that you use to specify items like the following:



• 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 givenqueue, retrieves any messages, and sends the messages (as instances of EnsLib.MQSeries.Message) to the associated businessservice. The business service, which you create and configure, uses these messages and communicates with the rest of theproduction. 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 isavailable). The polling interval is determined by the CallInterval setting.

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

a. The adapter creates an instance of the EnsLib.MQSeries.Message class and puts the message data into it.

b. The adapter calls the internal ProcessInput method of the associated business service class, passing theEnsLib.MQSeries.Message instance as input.

Note: The message must be less than 32kB 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 taskssuch as maintaining internal information as needed by all business services. You do not customize or override thismethod, which your business service class inherits.

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

2.2 Creating a Business Service to Use the InboundAdapterTo create a business service to use the EnsLib.MQSeries.InboundAdapter, you create a new business service class, add it toyour production, and configure it.

2.2.1 Development Tasks

In Studio, write and compile a new business service class. The following list describes the basic requirements:

• Your business service class should extend Ens.BusinessService.


Using the IBM WebSphere MQ Inbound Adapter

• In your class, the ADAPTER parameter should equal EnsLib.MQSeries.InboundAdapter.

• Your class should implement the OnProcessInput() method, as described in “ Implementing the OnProcessInputMethod.”

• Your class can optionally implement any or all of the startup and teardown methods: OnInit, OnTearDown,OnProductionStart, and OnProductionStop.

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 thiswizard, click File —> New and then click the Production tab. Then click Business Service and click OK. Note thatthe wizard provides a generic input argument. If you use the wizard, InterSystems recommends that you edit themethod signature to use the specific input argument needed with this adapter; the input argument type should beEnsLib.MQSeries.Message.

2.2.2 Configuration Tasks

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

1. Add an instance of your custom 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:

• Specify the queue manager, channel, and queue to access. The channel specification includes the name of thechannel to use, the transport used by the channel, the server name (or IP address) that is running the IBM WebSphereMQ 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 chapter “Configuring the Connection Details.”

4. Run the production.

2.3 Implementing the OnProcessInput() MethodWithin 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


Implementing the OnProcessInput() Method

Here pInput is the message object that the adapter will send to this business service; this is an instance ofEnsLib.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:

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

2. Create a request message (an instance of Ens.Request or a subclass), which will be the message that your businessservice sends.

For information on creating messages, see the subsection “Creating Request and Response Classes.”

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

4. Call a suitable business service method to send the request to some destination within the production. Specifically,call one of the following inherited methods, as appropriate for your needs:

• SendRequestSync() sends a message synchronously (waits for a response). For details, see the subsection “Usingthe SendRequestSync Method.”

• SendRequestAsync() sends a message asynchronously (does not wait for a response). For details, see the subsection“Using the SendRequestAsync Method.”

• SendDeferredResponse() sends a response that was previously deferred. This method is less commonly used.For details, see Developing Ensemble Productions.

Each of these methods returns a status (specifically, an instance of %Status).

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

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

See the example at the end of this chapter.

2.3.1 Creating Request and Response Classes

As noted earlier, your custom OnProcessInput() method typically constructs a request message and sends it.

• A request message is an instance of a subclass of Ens.Request and has properties to contain the data of your request.

• A response message is an instance of a subclass of Ens.Response and has properties to contain the data of the response.

You will need to define each of these subclasses, as appropriate for your needs.

2.3.2 Using the SendRequestSync() Method

To send a synchronous request, use the SendRequestSync() method as follows:

Set tSC = ..SendRequestSync(pTargetDispatchName, tRequest, .tResponse)

This method takes the following arguments:

• pTargetDispatchName — The configuration name of the business process or business operation to which the requestis sent.

• pRequest — Any persistent object, but typically a subclass of Ens.Request. This object contains the data to send withthe request.



• pResponse — (By reference) Any persistent object, but typically a subclass of Ens.Response. This object receives thedata returned by the response.

• pTimeout — (Optional) The number of seconds to wait for a response. The default is –1 (wait forever).

This method returns a status (an instance of %Status).

If no response is expected, you can use SendRequestAsync instead of SendRequestSync.

2.3.3 Using the SendRequestAsync() Method

To send an asynchronous request, use the SendRequestAsync() method as follows:

Set tSC = ..SendRequestAsync(pTargetDispatchName, tRequest)

This method takes the following arguments:

• pTargetDispatchName — The configuration name of the business process or business operation to which the requestis sent.

• tRequest — Any persistent object, but typically a subclass of Ens.Request. This object contains the data to send withthe request.

This method returns a status (an instance of %Status).

2.4 Using the Received MessageThe adapter sends an instance of EnsLib.MQSeries.Message to your business service. This object contains the messageretrieved 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 32kB in length unless long strings are enabled inEnsemble.

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


Using the Received Message

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);

}



3Using the IBM WebSphere MQ OutboundAdapter

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 followingtopics:

• Overall behavior that occurs if your production includes the EnsLib.MQSeries.OutboundAdapter

• How to create and configure a business operation that uses this outbound adapter, so that you can include the adapterin your production

• Details on how to create methods within that business operation

• An example of a business operation that can send messages to IBM WebSphere MQ

3.1 Overall BehaviorWithin a production, an outbound adapter is associated with a business operation that you create and configure. The businessoperation 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 specifythe following:

3.2 Creating a Business Operation to Use the AdapterTo create a business operation to use the EnsLib.MQSeries.OutBoundAdapter, you create a new business operation class,add it to your production, and configure it.

3.2.1 Development Tasks

In Studio, write and compile a new business operation class. The following list describes the basic requirements:

• Your business operation class should extend Ens.BusinessOperation.


• In your class, the ADAPTER parameter should equal EnsLib.MQSeries.OutboundAdapter.

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

– Queue means the message is created within one background job and placed on a queue, at which time the originaljob 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 jobwill not be released to the sender’s pool until the message is delivered to the target. This is only suitable for specialcases.

• Your class should define a message map that includes at least one entry. A message map is an XData block entry thathas 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 an Ensemble request message class, andResponseClass is the name of an Ensemble response message class. In general, these methods will refer to propertiesand methods of the Adapter property of your business operation.

• Your class can optionally implement any or all of the startup and teardown methods: OnInit, OnTearDown,OnProductionStart, and OnProductionStop.

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 accessthis wizard, click File —> New and then click the Production tab. Then click Business Operation and click OK.


Using the IBM WebSphere MQ Outbound Adapter

3.2.2 Configuration Tasks

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:

• Specify the queue manager, channel, and queue to access. The channel specification includes the name of thechannel to use, the transport used by the channel, the server name (or IP address) that is running the IBM WebSphereMQ server, and the port.

• Specify the error log to use.

• Indicate the character set that the messages are in.

These topics are discussed in the chapter “Configuring the Connection Details.”

4. Run the production.

3.3 Creating Message Handler MethodsWhen you create a business operation class for use with EnsLib.MQSeries.OutboundAdapter, typically your main task iswriting message handlers for use with this adapter, that is, methods that receive Ensemble messages and then send messagesto 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 ResponseClassis 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 32kB 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 “Creating Request and Response Classes,” earlier in this book.

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

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


Creating Message Handler Methods

3.3.1 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 adatatype or a character stream, but cannot be binary data or an object.

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

}


Using the IBM WebSphere MQ Outbound Adapter

4Configuring the Connection Details

For both the inbound and outbound adapters to IBM WebSphere MQ, you specify settings that describe the connection toa given queue. The details are nearly identical for both adapters; this chapter discusses the settings. It includes the followingtopics:

• How to specify the queue manager, channel, and queue to access.

• How to specify the error log to use.

• How to specify the character set to use for message conversion. For the inbound adapter, this is the character set toconvert the messages to. For the outbound adapter, this setting specifies the character set that the messages are alreadyin; no conversion is done.

• How to specify how often the adapter looks for messages. This applies only to the inbound adapter.

• An example of the settings

For any settings not listed here, see Configuring Ensemble Productions.

Also see “Prerequisites” in the first chapter of this book.

4.1 Specifying the Queue Manager, Channel, and QueueSpecify values for the following settings in order to specify the message queue of interest, the queue manager to use, andthe channel to use:

QueueName

%String

(Required) Specifies the queue name; this should be a valid queue for the specified queue manager. Also, youmust have permission to use this queue.

QueueManager

%String

Specifies the queue manager; this should be a valid queue manager on the IBM WebSphere MQ server and youmust have permission to use it.


If you omit this setting, the system uses the default queue manager, as configured in IBM WebSphere MQ. Or, ifIBM WebSphere MQ has been the configured so that the queue manager is determined by the queue name, thesystem uses the queue manager that is appropriate for the given queue name.

Channel

%String

The specification for the channel, in the following form:

"channel_name/transport/host_name(port)"

Here channel_name is the name of the channel to use, transport is the transport used by the channel, host_nameis the server name (or IP address) that is running the IBM WebSphere MQ server, and port is the port that thischannel should use.

Transport can be one of the following: TCP, LU62, NETBIOS, SPX

For example:

"CHAN_1/TCP/rodan(1401)"

"CHAN_1/TCP/127.0.0.1(1401)"

If you omit this setting, the system uses the default channel specification, as configured in IBM WebSphere MQ.Or, if the system has been the configured so that the channel is determined by the queue name, the system usesthe channel that is appropriate for the given queue name.

4.2 Specifying the Log File to UseUse the following setting to specify the log file to write to.

ErrorFile

%String

Specifies the log file to write error messages to. If you omit this setting, no logging occurs.

4.3 Specifying the Character Set of the MessagesYou can specify the character set to use for message conversion.

CharSet

%Integer

Specifies an integer Coded Character Set ID (CCSID) as used in IBM WebSphere MQ.

• For the inbound adapter, this is the character set to convert the messages to. If you do not specify a characterset, the MQ system assumes the messages use the default character set specified for the MQ client.

• For the outbound adapter, this setting specifies the character set that the messages are already in; no conversionis done.


Configuring the Connection Details

4.4 Specifying How Often to Check for MessagesThis applies only to the inbound adapter. To specify how often to check for messages, use the following setting:

CallInterval

%Numeric

Number of seconds that the adapter will wait before checking again for new messages, before checking for ashutdown signal from the Ensemble framework.

If the adapter finds input, it acquires the data and passes it to the business service. The business service processesthe data, and then the adapter immediately begins waiting for new input. This cycle continues whenever the pro-duction is running and the business service is enabled and scheduled to be active.

The default CallInterval is 5 seconds. The minimum is 0.1 seconds.

For any settings not listed here, see Configuring Ensemble Productions.

4.5 ExampleThe examples in this book used an IBM WebSphere MQ server running on a machine named antigua, using the port1414. The user ID under which the examples were run was authorized to use the queue manager QM_antigua and a queuenamed cachetest. Ensemble used a TCP channel named S_antigua to communicate with the server. The followingtable lists the settings:

ValueSetting

QM_antiguaQueue Manager

S_antigua/TCP/antigua(1414)Channel

cachetestQueue Name

c:\mq-log.txtError File


Specifying How Often to Check for Messages

5Troubleshooting

If you encounter problems when using the Ensemble adapters to IBM WebSphere MQ, you should first determine whetherthe client is correctly installed and can communicate with the server. To perform such a test, you can use sample programsthat are provided by IBM WebSphere MQ. The executables are in the bin directory of the IBM WebSphere MQ client.

The following steps describe how to use these sample programs on Windows. The details may be different on other operatingsystems; consult the IBM documentation and check the names of the files present in your client.

1. Create an environment variable called MQSERVER. Its value should be of the form channel_name/transport/server,where channel_name is the name of the channel to use, transport is a string that indicates the transport to use, andserver is the name of the server. For example: S_antigua/TCP/antigua

2. At the command line, enter the following command:

amqsputc queue_name queue_manager_name

where queue_name is the name of the queue to use and queue_manager_name is the name of the queue manager. Forexample:

amqsputc cachetest QM_antigua

If the amqsputc command is unrecognized, make sure that the PATH environment variable has been updated toinclude the bin directory of the IBM WebSphere MQ client.

In case of other errors, consult the IBM documentation.

3. You should see a couple of lines like the following:

Sample AMQSPUT0 starttarget queue is cachetest

4. Now you can send messages. Simply type each message and press Enter after each message. For example:

sample message 1sample message 2

5. When you are done sending messages, press Enter twice. You will then see a line like the following:

Sample AMQSPUT0 end

6. To complete this test, we will retrieve the messages you sent to the queue. Type the following command at the commandline:

amqsgetc queue_name queue_manager_name

where queue_name is the name of the queue to use and queue_manager_name is the name of the queue manager. Forexample:


7. You should then see a start line, followed by the messages that you sent previously, as follows:

Sample AMQSGET0 startmessage <sample message 1>message <sample message 2>

8. This sample program waits briefly to receive any other messages and then displays the following:

no more messagesSample AMQSGET0 end

If the test fails, consult the IBM documentation. Possible causes of problems include the following:

• Security issues

• Queue is not defined correctly

• Queue manager is not started


Troubleshooting

ACommon Tasks in the Management Portal

This appendix describes common tasks that you perform in the Management Portal. These tasks are needed to configureadapters as described in this book:

• How to access a production

• Adding a business host to a production

• Editing runtime settings

• Creating Ensemble credentials

A.1 Accessing a ProductionTo access a production, do the following:

1. In the Management Portal, switch to the appropriate namespace.

To do so, click Switch in the title bar, click the namespace, and click OK.

2. Click Ensemble.

3. Click Configure.

4. Click Production and then click Go.

Ensemble then displays the last production you accessed, within the [Ensemble] > [Production Configuration] page.

5. To display a different production:

a. Click Actions.

b. Click Open.

c. Click the name of the production and then click OK.

A.2 Adding a Business Host to a ProductionTo add a business service, process, or operation to a production, do the following:

1. Access the production, as described earlier in this appendix.


2.In the Services, Processes, or Operations column, as appropriate, click the Add button .

Ensemble displays a dialog box.

3. In the first drop-down list, choose the class on which to base the new business host.

4. Optionally specify the other items as follows:

• Service Name (or Business Process Name or Operation Name) — Type the name of this business host. The nameshould be unique within this category of business host. Do not use periods or spaces.

The default is the name of the class on which the host is based.

• Display Category — Choose or type the name of the display category to which this business host belongs. Youcan use this to display different sets of business hosts in the Production Configuration page. If a production has alarge number of business hosts, it can be helpful to display only a subset. This setting does not affect how theproduction works.

Display Category names are case-sensitive, and space characters are allowed. To place an item in multiple categories,list them in the Display Category field separated by commas (do not allow spaces around these commas).

• Comment — Type a comment.

• Enable Now — Select this to enable the host immediately.

5. Click OK.

A.3 Editing Runtime Settings of a Business HostTo edit the settings of a business service, process, or operation, use the following general process:

1. Access the production in which this host is defined, as described earlier in this appendix.

2. Click the business service, process, or operation in the main area of the page.

3. Click the Settings tab in the right area.

This tab displays settings in groups, which you can display or hide separately.

The setting names that appear in the right pane are, in many cases, localized descriptions of the class property names.You can hover the cursor over any setting name to display its help text as it appears in the Class Reference or click thesetting name to display the help text in a separate pop-up window.

4. Make edits as needed.

5. Click Apply to save changes or click Cancel to discard them.

When you click Apply, all changes immediately take effect, even if the production is currently running.

A.4 Creating Ensemble CredentialsSome remote systems require a username and password to log into that system. Ensemble permits you to store username-password pairs in a centralized, secure table that can be viewed and edited only by users with access to the ManagementPortal.


Common Tasks in the Management Portal

You define Ensemble credentials, which consist of an ID and the username-password pair. Then you use the ID as the valueof the Credentials setting of your adapter.

To create Ensemble credentials, log into the Management Portal and do the following:

1. Click Ensemble.

2. Click Configure.

3. Click Credentials and then click Go.

Ensemble displays the [Ensemble] > [Credentials] page.

4. On this page, specify the following information:

• ID — Enter a unique string that identifies this username-password pair. This is the identifier that you will useelsewhere within your production.

• User Name — Enter the username that you will use to log on to the remote system.

• Password — Enter the corresponding password.

• BusinessPartner — Optionally enter the name of the business partner profile associated with this business host.This setting is purely informational and does not affect how the production works. A business partner profilecontains information about an organization or application connected to your Ensemble system.

5. Click Save.

In some cases, it is not practical or possible to store the login data within Ensemble. You can write code to get this dataand pass it to Ensemble automatically. For details, see Developing Ensemble Productions.


Creating Ensemble Credentials

IndexA

adaptersadding to production, inbound, 6adding to production, outbound, 11behavior, inbound, 5behavior, outbound, 11general use, 4introduction, 3

authenticationcreating credentials, 22general information, 4

B

business operationsand IBM WebSphere MQ outbound adapter, 11creating to use IBM WebSphere MQ outboundadapter, 11login credentials, 22

business servicesand inbound IBM WebSphere MQ adapter, 5creating to use IBM WebSphere MQ inboundadapter, 6login credentials, 22

C

CallInterval setting, 17Channel setting, 15CharSet setting, 16configuration tasks

inbound adapter, 7outbound adapter, 13

connectionscreating login credentials, 22

Credentials setting, 22

E

Ensemble credentials, 22EnsLib.MQSeries.InboundAdapter

introduction, 3using, 5

EnsLib.MQSeries.OutboundAdapterintroduction, 4using, 11

ErrorFile setting, 16examples

OnProcessInput, 7request class, 8

I

IBM WebSphere MQ operations, 13inbound IBM WebSphere MQ adapter

introduction, 3

overall behavior, 5

M

Management Portal, common tasks, 21message handlers, 11

steps in, 13message map, 11

O

OnProcessInput method, 7outbound IBM WebSphere MQ adapter

default behavior, 11introduction, 4using, 11

Q

QueueManager setting, 15QueueName setting, 15

R

runtime settings, inboundother, 17

S

securitycreating credentials, 22

SendRequestAsync method, 9SendRequestSync method, 8


using ibm websphere mq adapters with ensemble - intersystems

Documents