IBM^(R) WebSphere^(R) Business Integration Message Brokers Toolkit Version 5.1

Change history:
GA: 23 July 2004
Updated: 20 August 2004
Updated: 20 October 2004
Updated: 17 December 2004
Fix Pack 5: 09 February 2005

(C) Copyright IBM Corporation 2004, 2005. All rights reserved.

Welcome to IBM WebSphere Business Integration Message Brokers Toolkit Version 5.1.

This readme file applies only to the installation of Message Brokers Toolkit Version 5.1 on Microsoft^(R) Windows^(R), and its use with WebSphere Business Integration Message Broker and WebSphere Business Integration Event Broker Version 5.0. It describes known problems, and contains documentation updates that were not available in time to be included in the online information center. You must also read the IBM WebSphere Business Integration Message Brokers Version 5.0 readme file for further information about the product.

WARNING!
Install Message Brokers Toolkit Version 5.1 only if you have installed WebSphere Application Development Integration Edition Version 5.1. Do not install Version 5.1 if you have a previous level of WebSphere Studio Application Developer Integration Edition; for this you must use Message Brokers Toolkit Version 5.0, which is supplied with WebSphere Business Integration Message Broker and WebSphere Business Integration Event Broker Version 5.0. Message Brokers Toolkit Version 5.1 has identical function to Message Brokers Toolkit Version 5.0.

Installing Message Brokers Toolkit Version 5.1 in a team environment
WebSphere Studio Application Developer Integration Edition Version 5.1 is not a prerequisite for every installation of the Message Brokers Toolkit Version 5.1. However, if at least one of your Message Broker Toolkit installations integrates with WebSphere Studio Application Developer Integration Edition Version 5.1, all your Message Broker Toolkit installations must be at Version 5.1 to ensure data sharing and integrity.

If you are not using WebSphere Studio Application Developer Integration Edition Version 5.1 on any system, or you are using WebSphere Studio Application Developer Integration Edition Version 5.0, you must install Message Brokers Toolkit Version 5.0.

CVS compatibility
The Message Brokers Toolkit Version 5.1 is based on Eclipse 2.1.2, and uses CVS client plugin version 2.1.1. For this version, your CVS server must be at version 1.11.6 or earlier (Linux and UNIX only, CVSNT is not supported).

Essential information for all users

Translated versions of the readme file and the install.html file are available from: ftp://ftp.software.ibm.com/software/integration/wbibrokers/docs/V5.1_Tooling

Translated versions of the information center are not included in this package. All national language fragments in the information center are empty and all information is displayed in English. If you want to display the information center in a supported language other than US English, you must download the appropriate Eclipse feature after you have installed the fix pack. Translations are made available at or soon after fix pack availability. For instructions about how to download these updates, see Feature updates.

Essential information if you are migrating

If you are migrating, refer to the install.html file for details of the actions that you must take before you install.

If you want to install Message Brokers Toolkit Version 5.1 on a system on which you have already installed Message Brokers Toolkit Version 5.0, you must uninstall the Version 5.0 Toolkit first; the two versions cannot coexist.

The information center provides further information about migration; to view this before you install, download a stand-alone version of the information center (see Documentation for instructions).

You must be aware of these migration and deployment concerns:

• When you create or modify message flows, message sets, and message mappings in the Version 5.1 toolkit, you can no longer access those resources in a Version 5.0 toolkit. Ensure that all users who share projects in a team environment are aware of this restriction and make backup copies if necessary.
• You must obtain a migrated version of all user-defined node plug-ins from the supplier before you can successfully deploy the message flows that contain them.

You can share resources between versions on different systems:

• You can deploy any projects developed in Version 5.0 without the need to change them.
• You can import broker archive files created in this version into a Version 5.0 workspace and deploy them successfully.

Documentation

Support

Feature updates

1. From the toolkit, select Help > Software Updates > New Updates. Eclipse then searches for available updates.
2. Eclipse displays which updates are available. Select the updates that you want to install.
3. When you have selected the updates to install, you receive a warning that the features have not been digitally signed. You can ignore this warning.
4. After you have installed the features, Eclipse prompts you to restart the workbench.
5. When you have restarted the workbench, the new features are installed and ready to use.

Contents

Restrictions and limitations:

• WebSphere Studio Application Developer Integration Edition
• Coexistence
• Installation
• After installation

Notices and trademarks

Useful Web pages

Restrictions and limitations

This section outlines the restrictions and limitations of WebSphere Business Integration Message Broker and WebSphere Business Integration Event Broker, by component.

WebSphere Studio Application Developer Integration Edition

To extend a WebSphere Studio Application Developer Integration Edition workbench with this product, you must upgrade WebSphere Studio Application Developer Integration Edition to the appropriate supported level. The version of the WebSphere Studio Application Developer Integration Edition workbench that can be extended is WebSphere Studio Application Developer Integration Edition Version 5.1 GA with "Interim Fix 002 - General Fixes 2.0.0". Previous versions of WebSphere Studio Application Developer Integration Edition 5.1 are not supported.

You must also apply the fix "WebSphere Business Integration Message Broker v5.1.5 Interim Fix 001 - Prerequisite Fixes 1.0.0.1" after you have installed WebSphere Business Integration Message Broker or WebSphere Business Integration Event Broker.

For detailed instructions, refer to the install.html file.

Coexistence

• You can deploy any projects developed in Version 5.0 without the need to change them.
• You can import broker archive files created in this version into a Version 5.0 workspace and deploy them successfully.

Installation

1. Defect 34320
   During the installation, if you choose NOT to accept the License agreement a pop-up appears with YES and NO buttons. Regardless of which button you select, you are returned to the License agreement page. Clicking YES should have caused the installation to be cancelled and the Launchpad to be closed.

   Also, if during the installation you click BACK on the License agreement page, several Java^TM Virtual Machine (JVM) error messages occur and the Launchpad hangs.

   Solution: Accept the License agreement if you want to successfully install the product.

2. Defect 37122
   A bug in Installshield causes the response files used in a silent installation to be interpreted incorrectly. To avoid this problem, complete the following actions:
   • Create a response file, as shown below.
   • Set installLocation to your chosen installation directory.
   • Set the component to be installed to true, as described in the comment line.

   The example below installs the tooling into the location C:\Program Files\IBM\WBIMB.

   ---start of response file---------
   
   -P installLocation="C:\Program Files\IBM\WBIMB"
   -W setupTypes.selectedSetupTypeId=custom
   
   ###############################################################################
   #
   # User Input Field - suiteFeatures
   #
   #
   
   #Do not change this - it sets the installer to ignore the standard custom setup route
   -W featureSelectionIB.active=false
   
   #Set a value to true to install that component
   # If any of the Broker, UNS or Config Manager parameters are set to true, 
   # the core value must also be set to true.  
   # Otherwise set this should be set to false to avoid installing most of the product.
   
   -W enableCore.value=true
   -W setCustomSuiteBrokerFeatureTrue.propertyValue=false
   -W setCustomSuiteUNSFeatureTrue.propertyValue=false
   -W setCustomSuiteConfigMgrFeatureTrue.propertyValue=false
   
   #Set to true if the Message Broker extension features are required.
   #The broker and core features must also be set to true to install this
   
   -W setCustomMessageTrue.value=false
   
   #Set to true if the tooling is required
   -W setCustomToolingTrue.value=true
   
   ------ end of response file----------
   

After installation

1. If you have installed the Message Brokers Toolkit Version 5.1 and replaced Version 5.0:
   1. Defect 34555
      You must rebuild all the projects that are defined in your workspace.
   2. Defect 34930
      If INSTALL_PATH\eclipse\workspace\.metadata exists, you might find that when you open the Message Brokers Toolkit, the Update Manager is launched correctly, but any updates to your plug-ins fail. Because of this, the Message Brokers Toolkit does not open with the correct plug-in levels, and failures of the toolkit might occur.
      
      For example, when you are in the Broker Application Development Perspective, you might find that the Message Definition File menu item is missing from the list produced by File > New Menu. This is an indication that your installation does not contain the correct level or version of plug-ins for the Message Brokers Toolkit.
      
      You can check that the levels of plug-ins that you are using is correct by clicking Help > About Message Brokers Toolkit for WebSphere Studio - Message Broker in the Message Brokers Toolkit for WebSphere Studio window. Under the heading "Message Brokers Toolkit for WebSphere Studio", a version number is displayed. If the correct versions of the plug-ins are being used after you have installed Version 5.1, the version that is displayed is 5.1.0. If the version that is displayed is less than this:
      1. Delete the .metadata directory.
      2. Reopen the Message Brokers Toolkit.
      3. Re-import your existing projects into the workspace by doing the following for each project:
         1. Click File > Import.
         2. When the Import wizard appears, select Existing Project into Workspace and click Next.
         3. Click Browse and define the location of the project in your workspace.
         4. Click Finish.
2. Defect 32898
   If your LAN settings are not correctly configured for local host access, perhaps because of the settings in your automatic configuration script, one of the following might occur:
   • Your help browser opens to a blank page.
   • Your help browser displays an HTTP error instead of a help page.
   • There are long delays when the information center is loaded.
   
   Solution: Your system administrator can configure your LAN settings so that help documents can be successfully accessed from the local help server by doing the following:
   1. In the Control Panel, open Internet Options, select the Connections tab, and choose LAN Settings.
   2. If your host is configured to use DHCP for IP assignment, make sure that the Automatically detect settings check box is cleared.
   3. If you use proxy server, make sure that Bypass proxy server for local addresses is selected.
   4. In Advanced settings for proxies, add '127.0.0.1;localhost' to the Exceptions if this address is not listed.
   5. If you are using an automatic configuration script for proxy settings, and you are not sure whether the script is correct, clear the Use automatic configuration script check box.
   
   If the above steps do not fix your problem, try changing the port and host properties in org.eclipse.tomcat\preferences.ini. Setting host=localhost or host=127.0.0.1 should work. If you are running a firewall, you might also need to set port=80 (or some other firewall-friendly value).
3. Defect T32243
   The mxsd file extension is not associated correctly with the Message Definition Editor. To ensure that mxsd files are opened in the Message Definition Editor as the default action, select Window > Preferences > Workbench > File Associations. Scroll down the list of file types and select *.mxsd. Then select Message Definition Editor in the list of Associated editors. Click Default then OK.
4. Defect 36638
   The Message Set Editor Preferences topic (ad15810_) describes only the options available in the Version 5.0 toolkit. The Version 5.0 options are not available for Version 5.1. In the Version 5.1 toolkit, the options are:
   • Message set editor settings, Outline view settings. These options are displayed but are not operational:
     • Group by namespace and then by collections
     • Group by collections and then by namespace
   • Message definition editor settings:
     • Show base complex types
       If you have defined one or more complex types based on other complex types, select this option if you want the content of those base complex types to be displayed in the message definition editor overview and outline views (this is selected by default).
       If you do not want them displayed, clear the check box.
5. Defect 36655
   If you uninstall the toolkit by invoking uninstaller.exe with the -silent option, the uninstall program returns control immediately and runs as a background task. If you do not want the uninstall program to return until it has completed, you must invoke the uninstaller within java using this command:
   java -cp <install_dir>\_uninst\studio\uninstall.jar run -silent
   where <install_dir> is the directory in which you installed the product.
   If you do not have a jvm configured (Version 1.3.1 or above), you can use the jvm within the installed product in directory <install_dir>\_sjvm\bin\. If you do this, you might have to delete this directory manually when uninstallation is complete.
6. Defect 37671
   Importing COBOL copybooks: when you import a COBOL copybook to populate a message set definition file, check that the copybook contains at least one 01 level structure. If there is no 01 level structure, no objects (elements, groups, types) are imported.
7. Database Views definitions are not supported in the ESQL editor. References to database views in the ESQL code (instead of to schemas or tables) are flagged as warnings (unresolved reference) in the ESQL editor. These warnings do not prevent you from deploying the corresponding ESQL.
   These unresolved reference warnings might also appear when you have migrated a Version 2.1 message flow, because the 5.0 ESQL editor validates database references.
   References to database tables and schemas only are supported.
8. ESQL compilation restriction: if you create a subflow, and choose to distribute this as a plug-in project, calls to ESQL global routines within the subflow might not be generated correctly when you add a message flow that contains the subflow to a BAR file. When you deploy the BAR file, it will fail.
   Workaround: Implement one of the following options:
   • Include all routines at module-level within the subflow.
   • Add the subflows to your workspace, and update the project that contains the calling message flow to reference the subflow project (or projects).

Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this information in other 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 information. The furnishing of this information 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 information. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this information 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:

• IBM United Kingdom Laboratories,
• Mail Point 151,
• Hursley Park,
• Winchester,
• Hampshire,
• England
• SO21 2JN

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 information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Programming License Agreement, or any equivalent agreement between us.

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 includes examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples 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.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate 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

The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both:

IBM WebSphere.

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

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

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

Useful Web pages

WebSphere Business Integration Message Broker and WebSphere Business Integration Event Broker fix packs
http://www.ibm.com/software/integration/mqfamily/support/summary/wbib.html

WebSphere Business Integration Message Broker Requirements
http://www.ibm.com/software/integration/wbimessagebroker/requirements/

WebSphere Business Integration Event Broker Requirements
http://www.ibm.com/software/integration/wbieventbroker/requirements/

WebSphere Business Integration Message Broker and WebSphere Business Integration Event Broker Install.html
ftp://ftp.software.ibm.com/software/integration/wbibrokers/docs/V5.1_Tooling/

WebSphere Business Integration Message Broker and WebSphere Business Integration Event Broker Readme files
http://www.ibm.com/software/integration/mqfamily/support/readme/

WebSphere Business Integration Message Broker Stand-alone Information Center
http://www.ibm.com/software/integration/wbimessagebroker/library/

WebSphere Business Integration Event Broker Stand-alone Information Center
http://www.ibm.com/software/integration/wbieventbroker/library/