Readme for IBM Branch Transformation Toolkit for WebSphere Studio v5.2.0.2

About this fix pack
Support for more software products
Support for Local CHA
Support for MQ Connector
Product fix history
Installation information
System requirements
Hardware requirements
Software requirements
Installation instructions
Installation package structure
Installing the Branch Transformation Toolkit on a development workstation
Migration information
Known limitations, problems, and workarounds
Appendix: MQ Connector
MQ Connector example
Dynamic queues
Customizing event management
Using an MQ Connector from an application
Creating and closing a dynamic queue
Configuring an MQ Connector
Configuring an MQ server
Configuring an MQ host
Starting the MQ runtime environment
Migrating MQ Connector
MQ Connector event notification
MQ Connector exception
MQ Connector external definitions
Notices
Trademarks

About this fix pack

Support for more software products

Branch Transformation Toolkit Version 5.2.0.2 supports the following software products:

• WebSphere Application Server 6.1 for runtime environment and Rational^(R) Application Developer 7.0 for development environment
• WebSphere Application Server 6.0 for runtime environment and Rational Application Developer 6.0 for development environment
• WebSphere Process Server 6.0 for runtime environment and WebSphere Integration Developer 6.0 for development environment

Support for Local CHA

Branch Transformation Toolkit Version 5.2.0.2 supports Local CHA.

Local CHA does not need EJB and Database support and its implementation is purely memory based. It provides the same APIs as other modes of CHA and it has better performance for applications that do not require failover support.

Support for MQ Connector

Branch Transformation Toolkit Version 5.2.0.2 supports MQ Connector.

BTT MQ Connector Service is a legacy service from BTT. In BTT Version 5.2.0.2, MQ Connector service is certified on the latest versions of WebSphere Application Server and WebSphere MQ. The MQ Connector service enables the communication between BTT and WebSphere MQ servers. For more information about MQ Connector, see Appendix: MQ Connector.

Product fix history

The following APARs are addressed by this fix pack:

APAR	Description
Table 1. Closed APARs
JR27142	String leaks in CHA EJB's cache.
JR27127	In general, there are two ways to manage the conversation for sending continuous messages. One is to establish new conversation for every message. The other is to reuse the same conversation that is established in the first sending. The second way has better performance. This APAR provides the support for the first conversation mode: host closes the conversation for each unsolicited message.
JR27170	This APAR provides two configurable parameters to configure the length of TID/thread name in trace.
JR27198	In the performance environment, there are thousands of threads pending, which causes the out of memory crash of WebSphere Application Server. Each thread is waitOn Semaphore in the receive() method. When the connection is terminated, the waiting thread of the connection cannot be notified on Semaphore. As a result, it cannot exit. This APAR changes the event notification way to avoid creating too many threads.
JR27406	BTT does not support Opera Browser.
JR27597	BTT provides an extension for WTS to implement the BTTRequestProcessorUtil.getProcessId (HttpServletRequest request) method. But when processing a transaction request, the createProcessorId() is invoked unexpectedly, which causes the BTT module to replace the original processor id with the new one. As a result, a new context is created. This causes the memory leak.
JR27322	Referenced objects are reserved after the conversation/Lu62ManageConnection is terminated. The objects should be deleted. This causes the memory leak.
JR27685	BTT LU62 JCA parameter "establishConversationRetries" does not work if it is more than 0.
JR27702	When forward action is set to null, instead of throwing forwardException, a warning will be shown.
JR27954	When BTT JCA deallocates LU conversation, a conversation object needs to be printed in trace. But before printing, the conversation object has been set to null. And after BTT JCA deallocates LU conversation, the object in the conversation is accessed. This APAR fixed these two problems.
JR28052	Every time BTT JCA creates a conversation, it loads a library, which is time-consuming.
JR28061	When implementing an invoker class which extends com.ibm.btt.cs.invoker.base.BeanInvokerImpl, the reference to the CHA Instance Id from the HttpSession will be removed and the HttpSession will be invalidated. So when the BTT client application calls the logoff operation (BTTServerOperation) on the server, the IllegalStateException from http session will be thrown.

Installation information

This section provides information about system requirements, product installation information for IBM Branch Transformation Toolkit version 5.2.0 fix pack 2.

System requirements
Hardware requirements

Hardware requirements for Server

Note:
These memory and disk requirements listed below are for the IBM WebSphere Application Server.

For Microsoft^(R) Windows^(R) 2003

• Intel^(R) Pentium^(R) III processor at 2GHz, or faster
• Minimum 2GB RAM
• Minimum 1 GB of free disk space for installation (includes SDK)

For Linux ^(R) (Intel)

• Intel Pentium processor at 2 MHz, or faster
• Minimum 2 GB RAM
• Minimum 1 GB of free disk space for installation (includes SDK)

For AIX

• IBM pSeries^(R) or iSeries^(R) system at 1400 MHz, or faster
• Minimum 2 GB RAM
• Minimum 1 GB of free disk space for installation (includes SDK)

For Solaris

• SPARC workstation at 440 MHz, or faster
• Minimum 2 GB RAM
• Minimum 1 GB of free disk space for installation (includes SDK)

For additional software products, for example DB2 ^(R) or IBM Communications Server, refer to the respective product documentation.

Hardware requirements for Client

For Windows XP

• Intel Pentium III processor at 800 MHz, or faster
• Minimum 1 GB RAM
• Minimum 160 MB of free disk space for installation
• Minimum display 1024 x 768

For Linux (Intel)

• Intel Pentium III processor at 800 MHz, or faster
• Minimum 1 GB RAM
• Minimum 160 MB of free disk space for installation
• Minimum display 1024 x 768

Hardware requirements for development environment

Note:
These memory and disk requirements listed below are for the IBM Rational Application Developer.

For Windows XP

• Intel Pentium III processor at 2 G MHz, or faster
• Minimum 2 GB RAM
• Minimum 3.7 GB of free disk space for installation
• Minimum display 1024 x 768

For Linux (Intel)

• Intel Pentium III processor at 2 G MHz
• Minimum 2 GB RAM
• Minimum 3.7 GB of free disk space for installation
• Minimum display 1024 x 768

If the development environment requires additional software products, for example DB2 or IBM Communications Server, refer to the specific product documentation.

Software requirements

Supported operating systems for development and runtime

• AIX^(R) V5.3 with Recommended Maintenance Package 5300-05
• Windows Server 2003, Enterprise and Standard
• Windows XP Professional with Service Pack 2 (Client and Development)
• Red Hat Enterprise Linux WS 4.0 Update 3 (Client and Development)
• Red Hat Enterprise Linux ES/AS 3.0 Update 8
• Red Hat Enterprise Linux ES/AS 4.0 Update 3
• Solaris 10 with the latest Patch Cluster

Supported application servers

For Windows 2003, Solaris, Linux (Intel) and AIX

• WebSphere Application Server, V6.1.0.11 and V6.0.2.23
• WebSphere Application Server Network Deployment V6.1.0.5
• WebSphere Process Server V6.0.2.2

Supported development environment

• IBM Rational Application Developer V7.0.0.4 and V6.0.1.2
• IBM WebSphere Integration Developer V6.0.2.2 IFix 1

Supported browsers

• Internet Explorer 6.0 SP2

Supported database

• IBM DB2 UDB Enterprise Server Edition V8.2.7 and V9.1
• Oracle 10g Standard/Enterprise Release 2 - 10.2.0.1 and 10.2.0.2
• Microsoft SQL Server 2000 Enterprise SP3a and 2005

Optional software

• WebSphere MQ V6.0.2.1
• IBM Communications Server for AIX V6.3.0.1
• IBM Communications Server for Linux V6.2.2.1
• IBM Communications Server for Windows XP and Windows 2003 V6.1.2
• IBM 32-bit SDK, Java^(TM) 2 Technology Edition, V5.0 SR2 for WebSphere Application Server 6.1
• IBM 32-bit SDK, Java 2 Technology Edition, V1.4.2 SR2 for WebSphere Application Server 6.0 and WebSphere Process Server 6.0

Installation instructions
Note:
This fix pack can coexist with IBM Branch Transformation Toolkit version 4.3 and 5.1. But if your current version of IBM Branch Transformation Toolkit is version 5.2.0 or version 5.2.0.1, you need to uninstall it before you install this fix pack.
Note:
The Branch Transformation Toolkit desktop component delivers an online help function that requires the Java Help (that is, jh.jar). Previously, the jh.jar can be found in the WebSphere Application Server V6.0. However, the WebSphere Application Server V6.1 does not ship the jh.jar anymore. Therefore, if you use the WebSphere Application Server V6.1 as your runtime environment, you need to download this jar file from the Java Help open source website. Only then can you use the online help function provided by the Branch Transformation Toolkit. Note that IBM is not a party to the terms and conditions governing the jh.jar nor a distributor of it, and IBM makes no representations or warranties, either express or implied, with respect to the jh.jar and offers no support specifically for the jh.jar. As is the case with any other non-IBM software you obtain from other parties and use in conjunction with IBM products, you are responsible for abiding by the terms of the license under which you obtain the jh.jar.

Installation package structure

The Branch Transformation Toolkit installation package mainly contains two groups of components - components for the development environment and components for the runtime environment.

Development environment

For the development environment, Branch Transformation Toolkit supports IBM Rational Application Developer 6.0.1.2 and IBM Rational Application Developer 7.0.0.4 and IBM WebSphere Integration Developer 6.0.2.2.

For the development environment, there are three sets of plug-ins including different files:

• Plug-ins for IBM Rational Application Developer 6.0.1.2

These plug-ins include components that have dependencies on features provided by IBM Rational Application Developer 6.0.1.2.

• Plug-ins for IBM Rational Application Developer 7.0.0.4

These plug-ins include components that have dependencies on features provided by IBM Rational Application Developer 7.0.0.4.

• Plug-ins for IBM WebSphere Integration Developer 6.0.2.2

These plug-ins include components that have dependencies on features provided by IBM WebSphere Integration Developer 6.0.2.2, such as plug-ins for the Business Process BTT Wizard.

If you have IBM WebSphere Integration Developer 6.0.2.2 installed on your system, the toolkit installation wizard will take IBM WebSphere Integration Developer as your development environment, regardless of whether you have IBM Rational Application Developer installed as well. After the installation wizard decides that IBM WebSphere Integration Developer is your development environment, it copies the plug-ins for IBM WebSphere Integration Developer to the wstools/eclipse/plugins directory of your IBM WebSphere Integration Developer automatically during the installation.

If you have IBM Rational Application Developer 6.0.1.2 or 7.0.0.4 installed on your system, the toolkit installation wizard will take IBM Rational Application Developer 7.0.0.4 as your development environment if you choose WebSphere Application Server V6.1 Support in Step 4 in Installing the Branch Transformation Toolkit on a development workstation, which means the Branch Transformation Toolkit will be installed to support JDK 1.5, and run on WebSphere Application Server V6.1. If you choose WebSphere Application Server V6.0 Support in Step 4 in Installing the Branch Transformation Toolkit on a development workstation, the toolkit install wizard will take IBM Rational Application Developer 6.0.1.2 as your development environment, which means the Branch Transformation Toolkit will be installed to support JDK 1.4, and run on WebSphere Application Server V6.0. After the installation wizard decides which version of IBM Rational Application Developer is your development environment, it copies the plug-ins for IBM Rational Application Developer 6.0.1.2 or 7.0.0.4 to the eclipse/plugins directory of your IBM Rational Application Developer 6.0.1.2 or 7.0.0.4 automatically during the installation.

If neither IBM Rational Application Developer nor IBM WebSphere Integration Developer is installed on your system, you will need to copy the plug-ins to the $D(RAD)/eclipse/plugins or $D(WID)/wstools/eclipse/plugins directory manually after you have IBM Rational Application Developer or IBM WebSphere Integration Developer installed later. Plug-ins for IBM Rational Application Developer or IBM WebSphere Integration Developer can be found in the <tooklit_root>/plugins directory.

Runtime environment

For the runtime environment, Branch Transformation Toolkit supports WebSphere Application Server 6.0.2.23 (which is based on JDK1.4), WebSphere Application Server 6.1.0.11 (which is based on JDK1.5), and WebSphere Process Server 6.0.2.2 (which is based on JDK1.4).

Installing the Branch Transformation Toolkit on a development workstation

To install the Branch Transformation Toolkit version 5.2.0.2 on a development workstation, do the following:
1. Insert the Branch Transformation Toolkit CD into the CD-ROM and browse the CD.

• If you want to install Branch Transformation Toolkit for Windows, locate and double-click the setupwin32.exe in the Windows platform.
• If you want to install Branch Transformation Toolkit for Linux, locate and invoke the setupLinux.bin in the Linux platform.

This starts the Installation Wizard for Branch Transformation Toolkit. The initial InstallShield window opens.
2. Click Next, the product license agreement window opens. Check the I accept the terms in the license agreement checkbox and click Next.
3. You are prompted to choose the destination directory for the installation files. If you want to choose a location other than the default location (C:\IBM\WebSphere Studio\Branch Transformation Toolkit 5.2.0.2 for Windows, and /opt/IBM/WebSphere Studio/Branch Transformation Toolkit 5.2.0.2 for Linux), click Browse, and select that folder you want to use.
4. Click Next. You are prompted to choose the setup type that best suites your needs.

• If you have installed WebSphere Application Server V6.1 as your runtime environment, check the WebSphere Application Server V6.1 Support checkbox. The program will be installed to support JDK 1.5, and run on WebSphere Application Server V6.1.
• If you have installed WebSphere Application Server V6.0 as your runtime environment, check the WebSphere Application Server V6.0 Support checkbox. The program will be installed to support JDK 1.4, and run on WebSphere Application Server V6.0.

5. Click Next.

• If you selected WebSphere Application Server V6.1 Support, the programme checks if Rational Application Developer 7.0 is installed. If not, the prerequisite window pops up informing you that the Rational Application Developer 7.0.0 is a prerequisite. You can either click Cancel to exit and run this installation program again after you install Rational Application Developer 7.0.0, or you can click Next to continue with the installation and copy the plug-ins to the $D(RAD)/eclipse/plugins directory manually after you have IBM Rational Application Developer 7.0.0 installed later.
• If you selected WebSphere Application Server V6.0 Support, the programme checks if Rational Application Developer 6.0.1 or WebSphere Integration Developer 6.0.2 is installed. If not, the prerequisite window pops up informing you that the Rational Application Developer 6.0.1 or WebSphere Integration Developer 6.0.2 is a prerequisite. You can either click Cancel to exit and run this installation program again after you install Rational Application Developer 6.0.1 or WebSphere Integration Developer 6.0.2, or you can click Next to continue with the installation and copy the plug-ins to the $D(RAD)/eclipse/plugins or $D(WID)/wstools/eclipse/plugins directory manually after you have IBM Rational Application Developer 6.0.1 or IBM WebSphere Integration Developer 6.0.2 installed later.

6. Click Next, and the installation preview window opens. It displays the destination directory and the disk space that the installation takes. Click Next.
7. The Installation Wizard will install toolkit components designed for IBM Rational Application Developer or WebSphere Integration Developer and those for WebSphere Application Server or WebSphere Process Server.

The Branch Transformation Toolkit installation program creates the following set of directories on the target machine.

Directory name	Description of contents
Table 2. Directories created by installation
dbtools	Scripts to manage database tables for the CHA component
desktop	Desktop DTD file
doc	The Branch Transformation Toolkit documentation plug-ins to IBM Rational Application Developer
plugins	Visual beans plug-in to IBM WebSphere Integration Developer Eclipse Modeling Framework (EMF) plug-in Graphical Builder plug-in Struts Tools BTT Extensions plug-in CHA Editor plug-in Format Editor plug-in Business Process BTT Wizard plug-in to IBM WebSphere Integration Developer Migration Tool plug-in Definition File Merging Tool plug-in
ear	EAR file to provide the infrastructure for the CHA component of the toolkit. You can use the EAR to build applications on the Branch Transformation Toolkit
jars	The Branch Transformation Toolkit code separated into various JARs according to the functional unit to which the code belongs. A solution built on the Branch Transformation Toolkit can use the JARs for the functional units that it is using. See Functional units, packages, and dependencies for a listing of the JARs and their contents and corequisites
samples	EAR files to run the sample applications provided by the Branch Transformation Toolkit in the IBM Rational Application Developer workbench. This directory also contains the source code of the samples
services	Runtime files that are needed by some of the services of the framework, for example, WOSA service.
javadoc	The Javadoc for BTT.

8. After the installation completes, the summary window opens displaying that the InstallShield Wizard has successfully installed the product.
9. Click Next, you will see the IBM Branch Transformation Toolkit for WebSphere Studio Version 5.2.0.2 README.
10. Click Finish to close the installer.
Migration information

Once you start to migrate your BTT applications with BTT migration tool, you cannot stop partway through the migration process.

Known limitations, problems, and workarounds

The following limitations have been identified:

• Operation Step cannot unformat remote context.
• BTT Struts Channel does not work with the Local CHA.
• Local CHA does not support the getContextByInstnaceId() API. Therefore:
• You cannot set runInSession to true while using Stateful Single Action EJB (SAE).
• You cannot pass context instance ID to BPEL while using Local CHA. Instead, you need to pass context instance itself.

Appendix: MQ Connector

The MQ Connector service enables a local application to communicate with a partner application through WebSphere MQ. It handles communication between the server and the host. The service uses WebSphere MQ for Java (package name com.ibm.mq). The particular WebSphere MQ classes used by the toolkit depend on the type of connection mode that you want to use, client connections mode or bindings mode, as follows:

• Client connections mode: When the WebSphere MQ classes are used as a client (when the external definition tag clientorServer="client"), the client has the following restrictions and behavior:
• It supports only TCP/IP.
• It stores information that would be stored in a channel definition and in environment variables in a class called MQEnvironment. It can pass this information to the channel definition and environment variables as parameters when it makes the connection.
• It writes error and exception conditions to a log specified in the MQException class. The default error destination is the Java console.
• It does not support connection tables.
• It does not read any WebSphere MQ environment variables at startup.
• It does not support the MQBEGIN verb or fast bindings.
• Bindings mode: When the WebSphere MQ classes are used in bindings mode (when the external definition tag clientorServer="server"), most of the parameters provided by the MQEnvironment class are ignored and the MQBEGIN verb and fast bindings into the WebSphere MQ queue manager are supported.

The main class of the MQ Connector service is MQConnection. Each instance of this class maps to an WebSphere MQ queue manager, an WebSphere MQ send queue, and an WebSphere MQ reply queue. The MQConnection class inherits from Service and implements the MQConnectionService interface, which in turn extends the CommonCommunicationsService interface.

This service, like all communication services, can work in either synchronous or asynchronous mode, which work as follows:

• In synchronous mode, the receive(correlationId, timeout) method is used to read a message response for the specified correlation id or message id. This method waits until the timeout is reached.
• For asynchronous behavior, an event is signaled when data arrives. The event contains the MQMessage received.

MQ Connector example

The following is an example of how MQ Connector might work. MQ Connector adapts its behavior to the existing WebSphere MQ definition that will be different for each environment. For instance, it is not mandatory to have two channels defined as in this example. They are only needed if two queue managers are used.

The MQ Connector service puts messages in a local queue to be sent to a remote queue manager. The local queue manager has definitions for a transmission queue and a channel.

To send and receive messages, the queue manager has two channels defined, as shown in the following figure (where they are identified as SERVER.TO.HOST and HOST.TO.SERVER):

The HOST.TO.SERVER channel is of type server-requested, because the MQ Connector service starts the channel and the sender terminates the call. The local queue in the MQ Connector service, shown here as replyToQ, receives responses from the host.

An application can send data using WebSphere MQ in the following two ways:

• The application can create the MQMessage to be sent
• The application can let the service create the MQMessage with a sequence number assigned by the sending channel (MQConnection)

To receive data, the application has the following two options:

• The application wants to send a message and receive only the response to this message. In this case, the sequence number is used as a reference to get the response. It is regarded as a permanent attribute of the message, and is consequently retained by the receiving channel to identify the replies. (External definition tag synchronousMode="enabled")
• The application wants to receive all the messages coming from the receive queue assigned to MQConnection. In this case, the message sequence numbering can be removed by the receiving channel. The application must also send the message. The difference between this and the previous implementation is that here the response corresponding to a request is identified by another method; for example, by the message itself. (External definition tag synchronousMode="disabled")

Dynamic queues

A dynamic queue is a local WebSphere MQ queue that is created when an application opens a model queue object. A model queue is a queue definition template that sets the attributes of the queue such as the name of the queue and whether it is temporary or permanent.

The MQ Connector component uses dynamic queues in the same way it uses static queues. An application should use a dynamic queue when the following are true:

• There is no need to retain the queue after the application terminates.
• The responses to the application's messages must be processed by a different application. In this case, the first application creates a reply-to queue that points to the second application.
• There is a need to reduce the system administration required for queue configuration and operational management of these queues.

WebSphere MQ automatically deletes a temporary dynamic queue when the application sends a closeConnection call.

The MQ Connector requires the Communications Pool to support dynamic queues. The names of the queues must be unique within the pool.

Customizing event management

To customize MQ Connector event management, extend the ConnectionHandler class and override the following methods:

• message(MQConnectionService). MQ Connection signals this event when it receives a message from the WebSphere MQ reply queue. The event contains the MQMessage received. The default behavior is to read the message.
• error(MQConnectionService). The default behavior is to do nothing.
• closed(MQConnectionService). The default behavior is to do nothing.
• opened(MQConnectionService). The default behavior is to do nothing.

See Event notification for the list of events triggered by this service.

Using an MQ Connector from an application

This example describes the process that could be followed for an operation on the server side that sends a message to a partner MQManager and waits for the response. Note that this is only an example of using an MQ Connector from an application, and only some of the methods of the MQ Connector public API are represented.
1. If the operation runs with a local MQ server, use the mq package:
import com.ibm.mq.*;
2. Instantiate an MQMessage for the received message:
MQMessage retrievedMessage = new MQMessage();
3. Get the service from the context:
MQConnectionService service = (MQConnectionService) getService("conversation");
4. Establish the connection with MQManager. Open the queues:
service.establishConnection();
5. Format the message to be sent to the partner:
String messageToSend = ((FormatElement) getHostSendFormat()).format(getContext());
6. Send the message to the partner, and store the correlationId to identify the response:
byte [] id = service.send(messageToSend);
7. Wait for the response:
retrievedMessage=(MQMessage)service.receive(id,30000);
8. Read the response:
String msgText = retrievedMessage.readUTF();
9. Close the connection:
service.closeConnection();
Creating and closing a dynamic queue

To create a dynamic queue instead of a static queue, set the following in the external definition for the MQConnection instance that you want to use:

• For dynamic queues used to send MQ messages:
• Specify the model queue for the send queue in the sendModelQ tag attribute. Note that the model queue name must be defined using WebSphere MQ.
• Set the sendToQType tag attribute to "model"
• For dynamic queues used to receive MQ messages:
• Specify the model queue for the reply queue in the replyModelQ tag attribute. Note that the model queue name must be defined using WebSphere MQ.
• Set the replyToQType tag attribute to "model"
• By default, the name of the dynamic send queue is the name of the MQConnection instance appended with sendQ. For example, if the MQConnection is called MQC, the name of the send queue is MQCsendQ. To specify a different name for the send queue, use the sendDynamicQTemplate tag attribute. The name of the reply queue follows the same rules as the send queue name except that its default name ends with replyQ instead of sendQ and you use the replyDynamicQTemplate attribute to set a different name for the reply queue.
• To close a dynamic queue, send it the closeConnection message. If the queue is temporary, WebSphere MQ deletes it.

Configuring an MQ Connector

This is an example of how you might configure an MQ Connector, based on the configuration described in MQ Connector example. To configure MQ Connector as in the example, you would complete the following steps:

• Configure an MQ server
• Configure an MQ host (This step is to simulate a partner, and is unnecessary if you are working with a real host.)
• Start the MQ runtime environment

Configuring an MQ server

Put your short description here; used for first paragraph and abstract.

Complete the following steps on the server:
1. Create a queue manager by typing the following at the command prompt:
crtmqm -q -d SERVER.TO.HOST -u SYSTEM.DEAD.LETTER.QUEUE QMS

where SERVER.TO.HOST is the default transmission queue, and QMS is the name of the queue manager (which must be the same as the QMgrName parameter in the service definition).
2. Start the queue manager by typing the following at the command prompt:
strmqm QMS
3. Determine if commands must be sent to the host. If yes, you will have to start the command server. The default system queue used to process commands is SYSTEM.ADMIN.COMMAND.QUEUE. To start the command server, type the following at the command prompt:
strmqcsv QMS
4. Create the required MQ objects for QMS by typing the following at the command prompt:
Runmqsc< c:\mqm\setup\server.tst >c:\mqm\setup\server.out

The file c:\mqm\setup\server.tst must contain the information shown as follows.

To send messages to the host:

DEFINE QREMOTE('QS1') REPLACE +
RNAME('QH1') +
RQMNAME(QMH) +
XMITQ(SERVER.TO.HOST) +

DESCR('Messages for host')
DEFINE QLOCAL(SERVER.TO.HOST) REPLACE +
USAGE(xmitq) +
DESCR('Xmit queue to host')

DEFINE CHANNEL(SERVER.TO.HOST) +
CHLTYPE(sdr) REPLACE +
TRPTYPE(tcp) CONNAME(your IP address) +
XMITQ(SERVER.TO.HOST) +
DESCR('Sender channel from server to host')

To receive messages from the host:

DEFINE QLOCAL('QS2') REPLACE +
DESCR('Messages from host')

DEFINE CHANNEL(HOST.TO.SERVER) +
CHLTYPE(rqstr) REPLACE +
CONNAME(your IP address) +
TRPTYPE(tcp) +
DESCR('Receiver channel from host to server')

where QS1 is the service definition parameter sendToQ, and QS2 is the service definition parameter replyToQ.

If commands such as channel inquiries are to be sent to the host, then an additional queue to hold replies from the host is required. To receive replies from the host:

DEFINE QLOCAL('CHANNELQ') REPLACE +
DESCR('Replies from host')

where CHANNELQ is the queue added to receive replies from the host that are related to channel queries.

The definition includes a channel to manage clients when working as an WebSphere MQ client. The definition is set on the server side. To define the server-to-client connection:

DEFINE CHANNEL(CLIENT.TO.SERVER.CH) +
CHLTYPE(svrconn) REPLACE +
TRPTYPE(tcp) +
DESCR('Server connection to client')
Configuring an MQ host

To simulate a partner, if you are not working with an existing host, complete the following steps on the host:
1. Create the queue manager by typing the following at the command prompt:
Crtmqm -q -d HOST.TO.SERVER -u SYSTEM.DEAD.LETTER.QUEUE QMH
2. Start the queue manager by typing the following at the command prompt:
strmqm QMH
3. Create all required MQ objects for QMH:
Runmqsc<host.tst>host.out

The file host.tst must contain the following information:

To receive messages from the server:

DEFINE QLOCAL('QH1') REPLACE +
DESCR('Messages from the server')

DEFINE CHANNEL(SERVER.TO.HOST) +
CHLTYPE(rcvr) REPLACE +
TRPTYPE(tcp) +
DESCR('Receiver channel from server to host')

To send messages to the server:

DEFINE QREMOTE('QH2') REPLACE +
RNAME('QS2') +
RQMNAME(QMS) +
XMITQ(HOST.TO.SERVER) +
DESCR('Messages for the server')

DEFINE QLOCAL(HOST.TO.SERVER) REPLACE +
USAGE(xmitq) +
DESCR('Xmit queue to server')

DEFINE CHANNEL(HOST.TO.SERVER) +
CHLTYPE(svr) REPLACE +
TRPTYPE(tcp) +
XMITQ(HOST.TO.SERVER) +
DESCR('Sender channel from host to server')
Starting the MQ runtime environment

To start the runtime environment, complete the following steps on the host machine:
1. Start the listener by typing the following at the command prompt:
runmqlsr -t tcp -m QMH

When also working as a client, start the listener at server(QMS) by entering the following at the command prompt:

runmqlsr -t tcp -p 1415 -m QMS

Note that a port must be specified, because the default port (1414) is used by QMH.
2. Start the MQ program.
3. Start the channels by typing the following at the command prompt:
runmqsc QMS
start channel(SERVER.TO.HOST)
start channel(HOST.TO.SERVER)

When also working as a client, start the client connection channel by typing the following at the command prompt:

start channel(CLIENT.TO.SERVER)
Migrating MQ Connector

The internal MQ Service implementation is modified based on the Branch Transformation Toolkit Version 5.2 architecture.

To migrate your BTT Version 4.3 MQ Connector to BTT Version 5.2.0.2, do the following:
1. Change the following package names of referenced MQ classes:

• change com.ibm.dse.services.mq to com.ibm.btt.services.mq
• change com.ibm.dse.services.comms to com.ibm.btt.services.comms

2. Search the BTT definition files (such as dse.ini, dsesvrce.xml) to find com.ibm.dse.services.mq and com.ibm.dse.services.comms, and then replace them with com.ibm.btt.services.mq and com.ibm.btt.services.comms.
MQ Connector event notification

MQConnection signals the following events, all of which are handled by the ConnectionManager class:

• message, when data arrives. The event contains a hash table with the following two elements:
• message: The MQMessage received
• queue: The name of the queue that contains the received message, including the deadletter queue
• opened, when the connection is opened
• closed, when the connection is closed
• errorReceived, when an error is produced in the asynchronous receive process

See Customizing event management for information on the default behavior of the handler for these events.

MQ Connector exception

The MQ Connector service throws the following exception:

Exception	Reasons/Actions
Table 3. MQ Connector exceptions
MQException	MQException due to mq native services. Action: Check actions for com.ibm.mq.MQException.

MQ Connector external definitions

The MQ Connector service is defined by the following data in the toolkit services definition file:

Attribute	Description
Table 4. MQConnection tag attributes
id	Service name
QMgrName	Name of the queue manager. Mandatory.
AliasQMgrNameSend	Name of the queue manager on which the send queue is defined. This queue manager is different from QMgrName above.
deadLetterQ	Name of the deadletter queue. Optional.
sendToQ	Name of the send queue. Mandatory for static queues. If the MQ Connector is using dynamic queues to send messages, this tag must not have a value.
replyToQ	Name of the reply queue. Mandatory for static queues. If the MQ Connector is using dynamic queues to receive messages, this tag must not have a value.
putMessageOptions	Options that control the behavior of sendToQ. The default is MQPMO_NEW_MSG_ID|.
getMessageOptions	Options that control the behavior of replyToQ. The default is MQGMO_WAIT| MQGMO_FAIL_IF_QUIESCING| MQGMO_COMPLETE_MSG.
sendToQOpenOptions	Options that control the opening of the send queue. The default is MQOO_OUTPUT.
replyToQOpenOptions	Options that control the opening of the reply queue. The default is MQOO_INPUT_AS_Q_DEF
persistence	Message persistence in the queue. Optional. The default is MQPER_PERSISTENCE_AS_Q_DEF
charSet	Character set relating to application message data. Optional. The default is MQCCSI_Q_MGR
messageType	Message type. Optional. The default is MQMT_DATAGRAM
messageOrCorrelation	Message search criteria. Following are the possible values: message. The message ID in the reply message has to match the request messageId. correlation. The correlation ID in the reply message has to match the request messageId. This is the default value.
encoding	Message numeric data representation. Optional. The default is MQENC_NATIVE
format	Format name employed by the sender to inform the receiver of the message format. Optional. The default is MQFMT_NONE
userId	Name of the message originator. Optional.
replyToQmgr	Name of the destination QueueManager for reply messages. Optional.
applicationName	Name of the application employed to send messages. Optional.
timeout	Timeout employed in the receive method. Optional.
serverOrClient	Whether the service is to work with Java Bindings or with Client for Java. Following are the possible values: server (default) client
synchronousMode	Whether the service is to work in synchronous mode. Following are the possible values: enabled disabled (default)
hostName	Name of the host with which the client is to connect when the service works as MQClient. This attribute is mandatory in this case.
channel	Name of the channel that the client is to use when the service works as MQClient. This attribute is mandatory in this case.
port	Port number for the client to use when the service works as MQClient. The default value is 1414. This attribute is mandatory if hostName or channel has not been specified.
expiry	How long WebSphere MQ retains (in tenths of a second) an unretrieved message before discarding it. The default value is MQC.MQEI_UNLIMITED.
automaticConnection Establishment	Whether the connection is to be established automatically. Following are the possible values: enabled disabled (default)
sendModelQ	Name of the send model queue. Mandatory for dynamic queues.
sendDynamicQTemplate	Name of the dynamic send queue. This replaces the default name.
replyModelQ	Name of the reply model queue. Mandatory for dynamic queues.
replyDynamicQTemplate	Name of the dynamic send queue. This replaces the default name.
sendToQType	Whether a model queue is used to define the send queue. For dynamic queues, the value is "model"
replyToQType	Whether a model queue is used to define the reply queue. For dynamic queues, the value is "model"

Note:
The following parameter values can be specified with either an integer value or the corresponding constant defined in the com.ibm.mq.MQC interface:

• putMessageOptions
• getMessageOptions
• replyToQOpenOptions
• sendToQOpenOptions
• persistence
• charSet
• messageType
• encoding

The "format" parameter can be specified using a string value or its equivalent constant defined in the com.ibm.mq.MQC interface.

The following example defines a connection using static queues:

<MQConnection id="CNV1" QMgrName="QMS" sendToQ="QS1" replyToQ="QS2"
putMessageOptions="4" getMessageOptions="17" synchronousMode="disabled"
serverOrClient="server" replyToQOpenOptions="MQOO_OUTPUT|MQOO_INPUT_AS_Q_DEF"
persistence="MQPER_PERSISTENT" charSet="MQCCSI_DEFAULT" messageType="MQMT_REQUEST"
encoding="MQENC_NATIVE" format="MQFMT_STRING" timeout="100" />

The following examples define connections using dynamic queues:

<MQConnection id="MQC" QMgrName="QMS" replyToQType="model" sendToQ="QS1"
replyDynamicQTemplate="DYN_Q_*" replyModelQ="RECEIVE.MODEL.QUEUE.PER"
sendModelQName="QS1" replyToQ="QS2" synchronousMode="enabled"
serverOrClient="client" hostName="dsccrisc1" channel="CLIENT.TO.SERVER"
port="1414" automaticConnectionEstablishment="enabled"/>

<MQConnection id="MQC" QMgrName="QMS" sendToQType="model" replyToQ="QS1"
sendDynamicQTemplate="DYN1_Q_*" sendModelQ="SEND.MODEL.QUEUE.PER" sendToQ="QS1"
replyModelQ="RECEIVE.MODEL.QUEUE.PER" synchronousMode="enabled"
serverOrClient="server" automaticConnectionEstablishment="disabled" >
Notices

IBM may not offer the products, services, or features discussed in this document in all countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

Lab Director
IBM China Software Development Lab
Diamond Building, ZhongGuanCun Software Park, Dongbeiwang West Road No.8,
ShangDi, Haidian District, Beijing 100094 P. R. China

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples may include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM's application programming interfaces.

Trademarks

AIX, CICS, DB2, eServer, i5/OS, IBM, IMS, iSeries, Lotus, Passport Advantage, pSeries, RACF, Rational, Redbooks, Tivoli, Tivoli Enterprise, Tivoli Enterprise Console, WebSphere, Workplace, z/OS, zSeries are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both.

Cell Broadband Engine and Cell/B.E. are trademarks of Sony Computer Entertainment, Inc. in the United States, other countries, or both and is used under license therefrom.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.

ITIL is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is registered in the U.S. Patent and Trademark Office.

IT Infrastructure Library is a registered trademark of the Central Computer and Telecommunications Agency which is now part of the Office of Government Commerce.

Other company, product, and service names may be trademarks or service marks of others.