Release Notes for WebSphere Transformation Extender V8.2.0.2

Content

IBM WebSphere Transformation Extender, version 8.2.0.2
release notes (rev. 10)

© Copyright IBM Corporation 2006, 2008. All Rights Reserved.


=====================================================================
CONTENTS
=====================================================================

1. About this release
2. Installation and configuration information
3. Upgrade and migration information
4. Known limitations, problems, and workarounds
5. New and changed behavior
6. Resolved Authorized Program Analysis Reports (APARs)
7. Command Server Notes
   For the following products:
• IBM WebSphere Transformation Extender with Command Server
• IBM WebSphere Transformation Extender with Launcher
• IBM WebSphere Transformation Extender Design Studio
8. Software Development Kit Notes
   For the following products:
• IBM WebSphere Transformation Extender for Application Programming
• IBM WebSphere Transformation Extender SDK
9. Launcher Studio Notes
   For the following product:
• IBM WebSphere Transformation Extender Launcher Studio
10. Web Services Notes
    For the following products:
• IBM WebSphere Transformation Extender with Command Server
• IBM WebSphere Transformation Extender with Launcher
• IBM WebSphere Transformation Extender for Application Programming
• IBM WebSphere Transformation Extender for Integration Servers
11. Contacting customer support
12. Notices and trademarks

=====================================================================
1. ABOUT THIS RELEASE
=====================================================================

This 8.2.0.2 release is a full version of the product. Release 8.2.0.2 can coexist on the same computer as prior point releases. For example 7.5, 8.0, and 8.1 can coexist on the same computer.

Where to find the software to download
The software for the WebSphere Transformation Extender 8.2.0.2 release is available for you to download from Passport Advantage Online, which is located at the following IBM Web site: http://www.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm


Interim Fix release
After you install this 8.2.0.2 release, be sure to download and install the 8.2.0.2 Interim Fix release.

The Interim Fix can be downloaded here:

Windows Interim Fix 1 for v.8.2.0.2

32 bit

AIX 32 bit Interim Fix 1 for v.8.2.0.2

HP-UX 32 bit Interim Fix 1 for v.8.2.0.2

Solaris 32 bit Interim Fix 1 for v.8.2.0.2

Linux 32 bit Interim Fix 1 for v.8.2.0.2

Itanium 32 bit Interim Fix 1 for v.8.2.0.2

64 bit

AIX 64 bit Interim Fix 1 for v.8.2.0.2

HP-UX 64 bit Interim Fix 1 for v.8.2.0.2

Solaris 64 bit Interim Fix 1 for v.8.2.0.2

Linux 64 bit Interim Fix 1 for v.8.2.0.2

Itanium 64 bit Interim Fix 1 for v.8.2.0.2

zLinux 64 bit Interim Fix 1 for v.8.2.0.2

Also, see the 8.2.0.2 Interim Fix Release Notes located on the IBM WebSphere Transformation Extender
Support Web site: http://www.ibm.com/support/docview.wss?rs=2320&uid=swg27008337.

For additional information such as answers to frequently asked questions, and solutions to workarounds for problems that have been documented for this release, view the Technotes that are on the IBM Support Web site:
http://www.ibm.com/support/search.wss?rs=2320&lang=all&loc=en_US
&r=10&cs=utf-8&rankfile=0&cc=us&spc=&stc=&apar=include&q1=8.2.0.2
&q2=technotes&sort=rk&tc=&ibm-search.x=16&ibm-search.y=11&dc=&dtm.

The new features in this release are listed in the documentation under "What's New". For information about the documentation and how to access it, see the IBM WebSphere Transformation Extender Support Web site: http://www.ibm.com/support/docview.wss?rs=2320&uid=swg27008337.

The sections in this file provide release notes for the IBM WebSphere Transformation Extender products listed below. There are also sections for notes that apply to specific products.

- IBM WebSphere Transformation Extender with Command Server
- IBM WebSphere Transformation Extender with Launcher
- IBM WebSphere Transformation Extender with Launcher Studio
- IBM WebSphere Transformation Extender Design Studio
- IBM WebSphere Transformation Extender for Application Programming
- IBM WebSphere Transformation Extender SDK


Java™ Runtime Environment (JRE)
WebSphere Transformation Extender 8.2.0.2 is installed with and supports the IBM version of Java™ 2 Runtime Environment, Standard Edition, Version 1.5.b03.

Use the included JRE. If you configure your WebSphere Transformation Extender product installation to a different JRE, it must be the same level as the included version.

The JRE is not included with the WebSphere Transformation Extender for z/OS product, version 8.2.0.2.


To Dos before opening the Design Studio

Certain circumstances combined with the default behavior of Eclipse applications, which is that it caches plug-ins, might cause problems when you use the Design Studio. They might cause the open Design Studio process to fail, the Design Studio to be unstable or to exhibit the behavior of an earlier release, or the run map process to fail.

You can avoid these problems by doing some steps before you open the Design Studio application. In some cases, you should first run the cleanextenderstudio.bat batch file that is included in the installation at the root of install_dir, and is used to clear the cached version of the Design Studio plug-ins. In other cases, you should first delete the .metadata folder that is in your workspace, and then reimport the workspace, or switch to a different workspace.

Run the cleanextenderstudio.bat batch file under the following circumstances:

• Your workspace got corrupted.
  
  In this case, when Eclipse attempts to open the Design Studio, the open process fails.

• You installed a patch that the WebSphere Transformation Extender customer support team provided you, which copied files to the wtxstudio directory.
  
  In this case, when Eclipse attempts to open the Design Studio, it uses the cached versions of the Design Studio plug-ins from the prior release on which this patch was installed, which causes the open Design Studio process to fail.

• You installed a Fix Pack release on top of a WebSphere Transformation Extender 8.2.x release.
  
  In this case, when Eclipse attempts to open the Design Studio, it uses the cached versions of the Design Studio plug-ins from the prior release on which this Fix Pack was installed, which causes the open Design Studio process to fail.

Delete the .metadata folder and reimport the workspace, or switch to a different workspace under the following circumstance:

• You ran a map that could not be loaded into memory, which caused the map to fail and the Design Studio application to terminate abnormally.
  
  When you tried to reopen the application, the open process failed.

=====================================================================
2. INSTALLATION AND CONFIGURATION INFORMATION
=====================================================================


Default installation location
[PK55720] The default location in which the WebSphere Transformation Extender products are installed is:
c:\IBM\WebSphere Transformation Extender 8.2

If you already have references to the default installation location from previous release installations, which was c:\Program Files\IBM\WebSphere Transformation Extender 8.1, during the product installations for this release, change the target installation location to match the path you are already referencing.



Installing on your Windows Vista operating system
If you are installing the WebSphere Transformation Extender products on your Windows Vista operating system, do not specify c:\Program Files in your target installation location because of compatibility issues.



Installing and configuring IBM-branded ODBC drivers on UNIX
Select WebSphere Transformation Extender product installations include IBM-branded ODBC drivers for the following operating systems:

UNIX 32-bit:
AIX
Linux
Solaris
HP-UX (Itanium)
HP-UX (PA-RISC)

UNIX 64-bit:
AIX
Linux
Solaris
HP-UX (Itanium)

WebSphere Transformation Extender supports DataDirect ODBC drivers.

The IBM-branded ODBC drivers are installed on the UNIX operating systems listed above under the odbc_drivers subdirectory. A readme.txt file is included in the odbc_drivers subdirectory and contains details about the contents of the subdirectory, such as the release notes, configuration information, and instructions about how you can access the ODBC driver help system.

After the WebSphere Transformation Extender installation runs the ./setup script, all the ODBC library paths will be automatically configured. Then you must deploy the appropriate ODBC-based map and make sure that the odbc.ini file, which is located under the odbc_drivers subdirectory, has all of the appropriate database connection information. For additional instructions for configuring the odbc.ini file, see the ODBC user guide that is installed under the odbc_drivers/help subdirectory for the html version, or the odbc_drivers/book subdirectory for the PDF book version.



Installation error: uncompress not found
The WebSphere Transformation Extender installation programs for UNIX operating systems rely on the UNIX "uncompress" program. In some Linux installations, the "uncompress" program might not be available. If you encounter an installation error that reports "uncompress: not found", the workaround is to either install the appropriate package or create an "uncompress" symbolic link that links to gzip, which should exist on the system.



Path location for the response files
When you are using the Installer user interface (UI) to do a silent installation of the products on UNIX environments and you have selected Generate Response files, at the Response file directory prompt, you must enter the same directory path location for the preconfigured response files as you previously entered for the directory path location that appears on the second screen of the UI. If you do not enter the same path, the "Installation failed" error message will appear although the products have successfully been installed.



InstallShield language selection dialog
When you use the Installer graphical user interface (GUI) to install the IBM WebSphere Transformation Extender products on Windows environments, do not cancel the InstallShield dialog that prompts you to select the language in which you want the installation dialogs to be presented. If you do click Cancel before you select the language, the Installer GUI will stop responding or "hang." After you select a language, you can then click Cancel during the InstallShield installation at any point, which will end the installation process and return you to the Installer GUI properly.

If you cancelled the dialog before you made your language selection and the Installer GUI has stopped responding, exit the Installer GUI and then restart it.


Product requirement for exporting type trees as schema

The Export as Schema utility that you can use to export a type tree either through the Design Studio by selecting Tree > Export as Schema, or the texport utility command in the command line outside the Design Studio GUI, requires Microsoft .NET framework version 1.0, or 1.1.


Configuring UNIX environment variables
The environment variables required to execute an WebSphere Transformation Extender map or system must be set prior to execution.

You can set the environment variables (PATH, DTX_TMP_DIR, DTX_HOME_DIR, and the appropriate library path variable for your platform) by running the setup program.

After you log on to your computer, execute the setup program in the WebSphere Transformation Extender installation directory before executing a map or system file (using the Launcher). This sets the required environment variables for this session only. Modify the .profile script to set the environment variables for all sessions.

Note: The following command procedure assumes that your UNIX command line environment is the Korn (ksh) shell.

Execute the command as follows:

. /install_dir/setup

where install_dir represents the directory in which you have installed your WebSphere Transformation Extender products.

Note: There must be a space between the initial period (.) and the command path.


Soft DATA Segment or Heap Size on UNIX systems
Using the default setting for the Soft DATA segment or heap size parameter can cause problems on UNIX platforms. This Soft DATA Segment value should be reset to a value larger than the default by the root user.

Note: On AIX platforms, use IBM's Smit (System Management Interface Tool) utility to reset the Soft DATA Segment value.

Set this value one time for each user (not for each session).
Choosing the correct value depends on the following factors:
- amount of memory available on the machine
- size of data being processed
- type of processing occurring on the respective data
- other major applications that might be running on the machine

If memory permits, start with the default value and increase it as needed. Use the following command to set the value within your own environment temporarily for testing the value setting:

ulimit -d <value>

Note: When setting the Soft DATA Segment value, the change takes effect only for the current session.


Required IBM XL C/C++ Run-Time Package Maintenance Level
To use the WebSphere Transformation Extender software on AIX operating systems, you must install the required IBM XL C/C++ run-time package maintenance level 9.0.0.5 or higher. Download the PTF from the following location: http://www.ibm.com/support/docview.wss?uid=swg24018248


Running the maxdata script on AIX platforms
The maxdata script is provided to increase the maximum values for memory availability on your AIX system. Run the maxdata script prior to executing any WebSphere Transformation Extender maps. The script requires a 777 permission level. Run the script only once for each respective executable and run it on the respective executable(s) whenever the executable gets updated or replaced during the installation of a patch or update.


HP-UX product requirements
The following are the recommended settings for max_thread_proc and maxdsiz when running the Launcher on HP-UX platforms:

Kernel Parameters Default Recommended
max_thread_proc 64 512
maxdsiz 64 MBytes <user dependent>

The max_thread_proc default of 64 processes is typically not enough and should be increased to 512. For maxdsiz, the value is dependent upon the amount of available memory and the size of the data used in the maps being run. The default of 64 MBytes is typically not enough. With large data sizes and if memory permits, 512 MBytes is recommended for maxdsiz.


Recommended patches

To use any of the following Java-based adapters, install the patches recommended for your HP-UX version:

CORBA Adapter
Java Class Adapter
Java Message Service (JMS) Adapter
JNDI Adapter

The URL for these patches on the Hewlett-Packard Web site is:

http://www.hp.com/products1/unix/java/java2/sdkrte14/downloads/index_pa-risc.html

If you are using HP-UX version 11.11, the following patch is required to run any of the above-mentioned, Java-based adapters:

PHSS_28871


Configuring Java-based adapters
The instructions below require you to modify the CLASSPATH environment variable. This can be done directly, or by adding the JAR files to the dtx.ini file. To do so, add entries to the [External Jar Files] section.

For example:

[External Jar Files]
jarN=c:\mypath\myjar.jar

Note: N represents the next available number if multiple jar entries exist.


For example:

[External Jar Files]
jar1=c:\J2EE\lib\j2ee.jar
jar2=c:\mypath\myjar.jar

Note: Environment variables can not be used in these entries.

1. (This step is not necessary for AIX and HP-UX platforms.)
   Install Java™ 2 SDK, Enterprise Edition (J2EE™) v1.5.b03 and set environmental variable J2EE_HOME to point to the installed directory. Update the CLASSPATH environment variable as described below.
   
   For Windows: %J2EE_HOME%\lib\j2ee.jar
   
   For Sun Solaris: $J2EE_HOME/lib/j2ee.jar
   
2. The IBM version of Java™ 2 Runtime Environment, Standard Edition v1.5.b03 is provided with this release. Make sure the environment variable JAVAHOME points to the installed location of this version of the JRE, and that the CLASSPATH environment variable includes:
   
   %JAVAHOME%\lib
   
3. For Windows platforms only: Set the PATH environment variable to include the following:
   
   install_dir\java\bin
   
   where install_dir represents the directory in which you have installed your WebSphere Transformation Extender products.
   
4. For UNIX systems only: Ensure that the client-side LIBPATH environment variable contains a reference to the directory in which Java 2 JRE is installed. Specifically, this is the directory in which the libjvm.s* and libjava.* files are located.
   
   For example:
   
   $(JAVAHOME)/jre/bin/classic:$(JAVAHOME)/bin
   
   Library path environment variables:
   
   HP-UX: SHLIB_PATH (SHLIB_PATH should point to the hotspot subdirectory instead of classic.)
   
   Sun Solaris: LD_LIBRARY_PATH
   
   AIX: LIBPATH
   
   Follow any provider-specific installation and setup instructions.

CICS Adapter
The CICS adapter requires the cicssrvr.loadlib file that is shipped with WebSphere Transformation Extender and is located in the installation directory. The cicssrvr.loadlib file includes server-side components required to use the CICS adapter to connect to CICS.

To install it, follow these instructions:

1. Transfer the cicssrvr.loadlib file in binary mode from the installation directory on your computer to a z/OS data set with 80 byte fixed-length records (RECFM=FB, LRECL=80, system-determined blksize).
   
   This means no ASCII-to-EBCDIC translation and no elimination of carriage-return or line-feed characters.
   
2. After you have installed the file on z/OS, issue the TSO RECEIVE command to create a load library from it. At the "READY" prompt, type the following:
   
   receive inda(‘my.upload’)
   
   The following messages are displayed:
   
   INMR901I Dataset MY.UPLOAD from USER on NODENAME
   INMR906A Enter restore parameters or 'DELETE' or 'END' +
   
3. Type the name of the load library to be created as follows:
   
   da('my.loadlib')
   
   Messages are displayed, indicating that the load library is being created.
   
4. Define the programs to the CICS region that will be running the CICS Adapter server-side components.
   
   The programs can be defined to CICS by adding the following statements to the CICS CSD definitions. To update the CSD, use either the DFHCSDUP CICS batch utility program or use the CEDA transaction and use the following statements as an example:
   
   DEFINE PROGRAM(DTXC3270)
   GROUP(DTXCICS)
   DESCRIPTION(3270 BRIDGE EXIT)
   LANGUAGE(LE)
   DATA(ANY)
   
   DEFINE PROGRAM(DTXCDRIV)
   GROUP(DTXCICS)
   DESCRIPTION(ADAPTER DRIVER)
   LANGUAGE(LE)
   DATA(ANY)
   
5. Add the cicssrvr load library to the DFHRPL concatenation for the CICS region that will be running the CICS adapter server-side components.

Java Class Adapter
To run the Java Class Adapter example when you are using a JRE other than the one supplied with the product, xerces.jar must be in the class path. You can obtain xerces.jar from the Apache Web site.


JCA Gateway Adapter
This version of the J2EE Connector Architecture (JCA) Gateway adapter consists of two installation components: client-side and server-side. The client-side is the machine upon which the WebSphere Transformation Extender product is installed and running. The server-side is the application server.

CLIENT-SIDE
WebSphere Transformation Extender must be installed before installing the JCA Gateway adapter on the client-side machine.

SERVER-SIDE
A J2EE-compliant application server that supports the EJB 2.0 and JCA 1.0 specifications is required.


JNDI Adapter
The following indicates the supported JNDI drivers for use with the JNDI Adapter:

- COS Naming service provider, 1.2.1 release
- DNS Service Provider, 1.2 release
- File system service provider, 1.2 beta 3 release
- LDAP service provider, 1.2.4 release
- RMI registry service provider, 1.2.1 release


MIME Adapter
The MIME adapter requires the j2ee.jar and mail.jar files, or equivalent jar files that contain the J2EE and "javax.mail" classes. These modules are not shipped with WebSphere Transformation Extender, but are still required by the MIME adapter to properly process MIME data. After the jar files are installed from an appropriate j2ee installation, modify the CLASSPATH to include those modules.


Oracle and Oracle AQ Adapters
Only Oracle database and Oracle AQ versions 9i and 10g are supported in this release. Oracle database and Oracle AQ adapter library files for version 9i are installed by default and are referred to as the "base" product. However, both 9i and 10g libraries are provided in the product installation directory.

To use 10g, rename the 10g library file (for example, m4ora10g.dll) to the "base" library file name (for example, m4ora.dll).

Oracle database adapter "base" library files:
- m4ora.dll (Windows)
- libm4ora.so(.sl) (UNIX)

Oracle AQ adapter "base" library files:
- m4aq.dll (Windows)
- libm4aq.so(.sl) (UNIX)

After the installation process completes, use the following platform-specific instructions to rename a versioned library file (10g in this case) to the base library file.

UNIX

1. Change the directory to install_dir/libs.
2. Copy the applicable Oracle library file for "backup" purposes:
• For the Oracle database adapter, make a copy of libm4ora.so(.sl).
• For the Oracle AQ adapter, make a copy of libm4aq.so(.sl).
3. In the installation directory, locate the 10g library file and rename it to be the base library file:
• For the Oracle database adapter, rename libm4ora10g.so(.sl) to libm4ora.so(.sl).
• For the Oracle AQ adapter, rename libm4aq10g.so(.sl) to libm4aq.so(.sl).
4. Move the renamed library file to libs directory.

To revert back to 9i, you can repeat the same process using the additional 9i libraries that were installed
with the product. For example, rename libm4aq9i.so(.sl) to libm4aq.so(.sl).

Windows

1. Go to the product installation directory.
2. Copy the applicable Oracle library file for "backup" purposes:
• For the Oracle database adapter, make a copy of m4ora.dll.
• For the Oracle AQ adapter, make a copy of m4aq.dll.
3. In the installation directory, locate the 10g library file and rename it to be the base library file:
• For the Oracle database Adapter, rename m4ora10g.dll to m4ora.dll.
• For the Oracle AQ adapter, rename m4aq10g.dll to m4aq.dll.

To revert back to 9i, you can repeat the same process using the additional 9i libraries that were installed with the product. For example, rename m4ora9i.dll to m4ora.dll.

When you use Oracle database and AQ adapters together in the same system, their Oracle client versions (9i or 10g) must match and also be for the same version of Oracle that is installed on the server.

For example, if Oracle 10g is installed on your server, and you want to use both the Oracle database adapter and the Oracle AQ Adapter in the maps in your system, you must use the 10g version for both adapters. You cannot use a 9i Oracle database adapter with a 10g Oracle AQ adapter in this case. They must both be the 10g version.


VAN Adapter
Scripts for the VAN adapter are located in:

install_dir\examples\adapters\van\scripts

The VAN adapter installation requires that a current version of Cleo A+ must already be installed. The adapter has been successfully tested with Cleo A+ Version v2.36.03 on the Windows platform and v3.17.20 on the UNIX platform.

Customers installing the VAN Adapter for the first time should contact CLEO Communications and order Cleo A+ for Windows.

CLEO Communications
Sales Department
4203 Galleria Drive
Loves Park, IL 61111
Phone: 800.233.2536, x 2693
Fax: 815.654.8294
Email: SalesIL@cleo.com
Web Site: http://www.cleo.com/

Customers upgrading from an earlier version of the VAN adapter should also contact CLEO directly, according to the contact information above, to order an upgrade from the earlier version of Cleo A+ provided with the VAN adapter. When ordering your upgrade, you must provide the serial number from your original Cleo A+ software.


Custom functions

To create custom functions in Design Studio, you must install IBM WebSphere Transformation Extender SDK.



=====================================================================
3. UPGRADE AND MIGRATION INFORMATION
=====================================================================

• Maps, type trees, and systems from versions 5.0 and later can be used with 8.2.0.2. You must regenerate systems, and although it is not always required for running maps from an earlier version, you should reanalyze and save the type trees, and save and recompile the maps; otherwise, the processes must convert the files each time they load the files.

• If you are migrating from 8.0 to 8.2.0.x, you must run your database triggering scripts in order to successfully run source-triggered database systems. After version 8.2.0.x is installed on the supported Oracle or SQL Server databases, no earlier release of WebSphere Transformation Extender can use triggering on that database because the client and source would reference different names and result in failure.

• To use the new code page functionality, you must make new selections for the Data Language and National Language type properties in your type trees.

• If you previously used a non-international version of WebSphere Transformation Extender (formerly DataStage TX or Mercator), Native has been redefined to be Latin1 instead of ASCII.

• During installation, if you are prompted to register this version as the default program for opening WebSphere Transformation Extender file types and you choose "Yes", all WebSphere Transformation Extender files, such as *.mtt or *.mms, will open with this version (8.2.0.x).

• [PK55722] When you use the dsmapconv command (Map Migration utility) to convert a map from WebSphere Transformation Extender version 6.7.1 to WebSphere Transformation Extender version 8.2.x, after the type tree has converted successfully, some of the input map rules might not be able to be converted, and will cause the dsmapconv map conversion process to fail. You can view the results in the dsmapconv log file.

If the dsmapconv map conversion process fails because some map rules were unable to be converted, do the following procedures in Map Designer to complete the conversion process:

1. Open the map.
2. Delete the unresolved rules.
3. Compile and rerun the map.

String Literals
All string literals held in rules are now encoded in UTF-16 (Unicode) rather than the Native formats used previously. The strings will be converted to the target code page before being used in the rule. However, when a map writes a string literal to a binary character field, the data will be written as UTF-16 because binary objects have no code page encoding assigned to them.


Opening Files from an earlier version
When a source file from an earlier version of a WebSphere Transformation Extender product component is saved in the current version, the content and structure of that file is automatically converted to the format for the current version.

After conversion to the current version formats, do not open these files in earlier versions of a WebSphere Transformation Extender product component because the format of the map source has changed and there are additional added features that are not supported in the earlier versions.

A behavior change should be noted regarding how files are converted prior to the v6.7 release. Previous versions would convert *.mtt files on disk; v6.7 and this version allows *.mtt files to be converted in memory when the file is opened. The backup *.omt file is not created until the file is saved.

For other files:
- *.mms files do not need to be converted for the current version.
- A map created in an earlier version opens in the current version.
- *.msl files do not need to be regenerated. They are converted on-the-fly.
- *.mmc files do not need to be recompiled.
- *.msd files still work the same way, creating an *.osd when the file is opened.
- *.mdq files should still open in the current version.


Recommendations for preparing maps to run in this version

• Analyze each type tree file for logic and structure and then save it in the current version of the Type Designer.
• Regenerate type trees for queries, tables, and stored procedures.
• For maps that will be executed using a current version of the Command Server or Launcher, build all maps using the equivalent (current) version of the Map Designer.
• Build and generate the Launcher system (.msl) file or the command file for all systems defined in the current version of the Integration Flow Designer.
• If you are upgrading from an earlier version of the UNIX Launcher (formerly known as the Event Server) in which you used a script file containing the unsupported "lci -start" and "lci -stop" features to start and stop your UNIX Launchers, note that these commands have been replaced by a fully supported and documented feature of the Management Console. You must change your existing scripts using lci as follows:

To start the Launcher:
From:
lci -start
To:
launcher.sh -start

To stop the Launcher:
From:
lci -stop
To:
launcher.sh -stop <listen_port>

where:
<listen_port> is the number of the first designated listening port in the range specified in the LauncherAdmin.bin file. The default value is "5015" and it is not required for the -start option. However, if it is provided, it should match the first listening port specified in the LauncherAdmin.bin file.

• If you have designed maps that could produce 0 bytes of data to an adapter (this is especially critical for R/3 adapters), you must change the OnSuccess setting to CreateOnContent or use the -XO adapter option.
• When opening a map in this version that was created in an earlier version that still references a custom adapter or an adapter that is no longer supported, the Source or Target in the Edit Card dialog will be blank. The map will still build successfully, but will result in a "Source not available" or "Target not available" message when executed. The solution is to select an adapter from the list in the Edit Card dialog.

Converting type trees generated in earlier versions
You can use the dsxmlconv utility command by starting it from the command line, to convert type trees that were generated in WebSphere Transformation Extender versions 6.7, SP1, SP2, and 7.0.



=====================================================================
4. KNOWN LIMITATIONS, PROBLEMS, AND WORKAROUNDS
=====================================================================


Launcher

If you install the WebSphere Transformation Extender 64-bit Launcher on AIX version 5300-06, and the Launcher will not start, modify the environment with the AIXTHREAD_SCOPE=S environment variable. To do this, enter the following command on the command line after running the setup script in the WebSphere Transformation Extender installation directory:

export AIXTHREAD_SCOPE=S

You can also add this command to the setup script to be run automatically.



SAP R/3 configuration issue

QISS on HP 11i operating environments will not work without setting the EPackage.Registry. When using a mixed Java environment on HPUX 11i, in "JVM Options" of the dtx.ini file, add the following code:

option1=-Dorg.eclipse.emf.ecore.EPackage.Registry.INSTANCE=
org.eclipse.emf.ecore.impl.EPackageRegistryImpl



XML Native Schema

Native schema-enabled maps do not support the REJECT function because restart attributes cannot be set in native schema type trees.


Native schema-enabled maps do not support CDATA.


WebSphere adapters

[PK58507]

• When you run WebSphere Transformation Extender maps on a Solaris platform that use the WebSphere Adapter for Email, the following errors might result:
• During outbound processing, the operation might throw a null pointer exception and cause the core engine to end abnormally.
• During inbound processing, the operation might throw the following exception:
• ResourceException: Failed to establish event manager resulting in wrong output data

• When you run a WebSphere Transformation Extender map on a Windows platform that simultaneously uses two inbound input cards that specify the WebSphere Adapter for FTP as the source setting, and one outbound output card that specifies the WebSphere Adapter for Email as the target setting, the mapping process will throw a null pointer error.

• Unsupported types for the WebSphere Email importer On the "Generic e-mail business object" option in the WebSphere Email importer wizard, the Operation properties in the Email adapter importer produces schemas with "anyType" for the Email and Attachment fields. Currently j2ca bridge does not support this type.

About third-party software

Before using third-party software with WebSphere Transformation Extender installed on your Windows Vista operating system, check with your vendor to ensure that it is compatible with the Windows Vista operating system.



Importing type tree script (.mts) files
When you import type tree script (.mts) files (right-click the Type Trees folder of a project in the Extender Navigator for the Eclipse Design Studio and select Import > Type Tree Maker), the imported type tree (.mtt) file is not added to the project automatically. It remains in the location specified in the .mts file.



Synchronizing type trees
The Eclipse Type Designer graphical user interface (GUI) does not support the XML Type Tree/Schema Synchronization utility wizard, which is used to synchronize type trees with the originating DTDs or schemas. To synchronize type trees with the originating DTDs or schemas, import the type tree from the changed schema again.



Converting type trees generated in earlier versions
The Eclipse Type Designer graphical user interface (GUI) does not support the XML Type Tree Compatibility utility wizard. You can, however, use the dsxmlconv utility command by starting it from the command line, to convert type trees that were generated in WebSphere Transformation Extender versions 6.7, SP1, SP2, and 7.0.



Number elements with length
There is a known issue with number elements that can occur after importing an XML Schema that contains a nillable element. When using the generated XML type tree, the validation map might run successfully, however, the generated XML output is invalid for the Schema.

To work around this issue, modify the generated XML type tree by changing the element type (Item Subclass property) from Number to Text for the elements that contain a nillable element.


BEA Tuxedo Adapter temporarily unavailable
Due to BEA licensing issues, the BEA Tuxedo Adapter is not available in this release of WebSphere Transformation Extender.


Map Designer
The use of IN on a single object in the DataAudit settings causes the Map Designer to stop responding.


Due to a problem with 3rd party software, the "Other" selection button for creating custom breakpoint colors for the Map Debugger is not keyboard accessible.


Resource Registry
When using the resource registry for database aliases defined in the database/query file (.mdq) or command line, you should define the alias in the Global section of the resource registry for both Command Server and Launcher.


Building maps for z/OS
When a map is built for the z/OS platform, type and map names are converted to EBCDIC. When a type or map name has characters that cannot be converted to EBCDIC, a series of question marks (??) will be substituted. This scenario might occur as a result of importing an XML Schema that contained non-EBCDIC encoding.



Known issue with Oracle when DB2 and Oracle Client libraries loaded
There is a known issue with the Oracle 9i Client and Oracle 10g Client libraries that occurs when both an Oracle Client Library and a DB2 Client library are present.

Because of the Oracle Client library issue, the following problems could occur with your WebSphere Transformation Extender maps:

• When both the DB2 Adapter and Oracle Adapter are used in a map, the map fails (crashes).
• When both the DB2 Client and Oracle Client libraries are loaded, a failure (crash) occurs when the map attempts to connect to the Oracle database.

To work around this issue, you can regenerate the Oracle Client library using the -Bsymbolic link option or contact Oracle for fix information.


IMS TM Resource adapter documentation
The IMS TM Resource adapter is new for this release. The documentation is in the following locations:

• The help plug-in is under the main navigation pane in the WebSphere Transformation Extender information center.
• The PDF manual, 1152.pdf, is in: <install_dir>\docs\en\adapters\ims\1152.pdf

=====================================================================
5. NEW AND CHANGED BEHAVIOR
=====================================================================

Deprecated QualityStage adapter and importer

The QualityStage adapter and importer are deprecated and not included in the 8.2.x.x product distribution. However, they are still currently available by requesting them from IBM Customer Support if you need to use them. For information about how to contact Customer Support, see Contacting Customer Support.


New Eclipse Design Studio

Mapping data objects from one output card to another

In previous versions of the WebSphere Transformation Extender Map Designer, to map data objects from one output card to another output card, you could press the ALT key and drag the object into the new destination. The WebSphere Transformation Extender 8.2.0.1 Design Studio supports the drag-and-drop method of mapping objects from one output card to another. When mapping between very large output cards, an alternate method can be more effective. Select the source field and copy the data using the Copy menu item or CTRL+C, and then select the target field and paste the data using the Paste menu item or CTRL+V.

Expressing pad characters

Pad characters can now be expressed as being Sized in Bytes or Characters, and type definitions now have character sizes.


Reordering indexed objects

The process to perform map index re-ordering has changed in 8.2.0.1. Previously, in a map output card which has indexed rules, rules could be reordered as required by pressing Ctrl+Shift keys, then dragging and dropping indexed rules. Now, to reorder an indexed object, use the Reorder Index option in the context menu.


PACKAGE function change

There has been a change to the PACKAGE function, where it will now return a valid code page for data contained within group objects, which previously had an unknown code page.

This primarily affects the following three map rule functions on all platforms:

- GET
- PUT
- RUN

For example, if you are running a map on the UNIX System Services (USS) execution environment, that is set up to use the Java adapter, and has a rule that uses the PACKAGE function, change the rule to use, instead, the CPACKAGE function. Also, specify the character set as NATIVE for the second argument on the rule. Because of a change to the PACKAGE function, if you use it in this specific case, the map will convert the data to the NATIVE code page, which might be invalid for the Java adapter, and cause a Java exception error.

If you are running maps on the USS execution environment, the character set for NATIVE is EBCDIC, which is invalid for the JAVA adapter.

Change the rule from:

GET("JAVA","-T",PACKAGE(GROUP:RECORD))

to:

GET("JAVA","-T",CPACKAGE(GROUP:RECORD,"NATIVE"))

In this example, when you specify NATIVE in the second argument of the CPACKAGE function, the function treats the data as if it already is in the appropriate code page and therefore, does not attempt to convert it to NATIVE.


License management for WebSphere Transformation Extender for z/OS

WebSphere Transformation Extender for z/OS supports a new form of license management using Getting Started Sub-capacity Pricing. This is a new pricing option for starting projects with WebSphere Transformation Extender for z/OS. The two features of WebSphere Transformation Extender for z/OS that use Getting Started Sub-capacity Pricing are WebSphere Transformation Extender with Command Server, and WebSphere Transformation Extender with Launcher. They support a category of sub-capacity pricing called Execution-Based.

Note that the WebSphere Transformation Extender for Integration Servers, and WebSphere Transformation Extender for Application Programming features of WebSphere Transformation Extender for z/OS do not support Getting Started Sub-capacity Pricing, although they do support traditional sub-capacity pricing.

For more information about the Getting Started Sub-capacity Pricing, read the materials that are posted on the following IBM Web site:
http://www.ibm.com/servers/eserver/zseries/library/swpriceinfo/ipla.html



=====================================================================
6. RESOLVED AUTHORIZED PROGRAM ANALYSIS REPORTS (APARs)
=====================================================================

Adapters

[PK63796] Using Zip Adapter with MEMORY command created zip file contents with a time stamp of 1/24/1980. The third party zip file support libraries were updated to use dynazip's 6.00.05 libraries, which corrects the issue.

[PK64532] When an MQ Adapter Source Event was defined for a Launcher watch (MQ Adapter Listener), error messages were written to the MQ Adapter trace file each time the MQ Adapter polling did not find any messages to be picked up, causing the log file to increase in size indefinitely. Now, the MQ Adapter -TE command no longer creates the "MQGMO_NO_WAIT specified" message in the error log.

[PK65341] When running multiple maps that read and write from various message queues using the JMS adapter, the maps failed with the error "Unable to open Connection (to the message queue). The Design Studio was not properly loading the external JAR files upon which the JMS adapter depends, because the adapter was using the System class loader instead of the Eclipse-based class loader. The fix enables the JMS adapter to work in either an Eclipse or non-Eclipse based runtime environment. The JMS adapter now uses the current class loader before attempting a connection. Before this fix, the JMS adapter would always
default to using the System Class loader. This would work outside of the WebSphere Transformation Extender Design Studio environment. Within Design Studio, however, this would bypass the custom WTX class loader, which in turn would prevent the JMS adapter from connecting with the appropriate JMS provider.


Platform API

[PK63059] Fixed an issue where the user was uable to use path and filename set in an earlier rule within the GETRESOURCEALIAS function. A fix in function.c in mercmapr project allows the path to be set in an earlier rule and now the GETRESOURCEALIAS function successfully appends the file name.


Command Server

[PK64297] A 200% CPU usage increased from WebSphere Transformation Extender 6.7 to WebSphere Transformation Extender 8.1.0.3 when using the MVS Batch Command Server and using the XP Link version of the libraries for both releases. Code was added to use the lesser of the "size remaining," for a sized component, or the max size of an object as the max amount of data to accept when looking for syntax to determine the length of an object.

[PK65510] Fixed an issue where –M command line override for xsd files was not working if the xsd file was not in the map directory. The ParseArg function now correctly processes the –M option.


Launcher

[PK62220] Fixed an issue where the Launcher Time Trigger was not omitting the days correctly. Days of week were missing from "Omit:" when the both the days of the week and the time were specified.

[PK63239] Custom DB type tree item caused the map compiler to store invalid DB data inside of the .MMC file. This caused the Launcher to end abnormally with a runtime memory access violation when the DB adapter overwrote more entries than what actually existed in the compiled map. A runtime check has been made to dbutil to check for this corruption, but it is strongly recommended that customers who have such custom DB type tree structures recompile and redeploy their maps to avoid memory corruption.

[PK65255] Using external functions like GetResourceAlias and GetTXinstalldirectory during high volumes caused the Launcher to abnormally end due to memory corruption related to multithreading. The launcher process can randomly dump its core if there are two maps running at the same time, a multithreaded system, and both maps are using external WTX MATH, XMLLIB or RESOURCE ALIAS related functions. This issue, specific to UNIX platforms, is now fixed. The memory corruption was caused by a multithread unsafe function when executing code for external functions.


Core Engine

[PK63009] When using the PACKAGE() function, data was missing from the output. This was fixed by adding the length of the PWA to the length of the data which adjusted the length when data moves from a PWA to the output.

[PK62383] Map executed on AIX looped continuously with core engine. Code was added to handle an unordered group whose component failed its rule in the same way choice groups are handled (going on to the next component).

[PK61530] Fixed an issue on HP Itanium 64-bit that caused the MsgType field on input to be converted to null when dragged into the output field. This occurred when the MQ header value was hard coded into a message on HP Itanium. We now correctly map 4 byte Binary Data objects to the output.

[PK62859] Map performance issue on Sun Solaris caused map run time to increase exponentialy when the number of input objects increased. A fix was added to prevent the release character from being inherited from the previous level set, which caused duplicate delimiters to reallocate the byte block with each new record.

[PK61422] Fixed an issue with XML restriction characters on Sun Solaris. Now, instead of saving data after having substituted character restrictions, the actual content is saved.

[PK61094] Multi-byte release characters in input were causing unexpected output. Now, the input data pointer updates correctly after building the output release character.

[PK62112] Calling CPACKAGE/CTEXT functions with code page EUC-JP returned incorrect results. Since EUC-JP is not an actual IBM code page name, it was not located. Code was added to find the code page name and if not found, all aliases are checked. The processing logic now finds the EUC-JP code page alias when using CPACKAGE/CTEXT.

[PK61795] Segmentation fault core dump occurred on Sun Solaris. Code was added code to check for a "local" operand. If the operand is local, it does not need to be copied into a buffer and no action is taken, preventing a core dump from occurring when an output card is being created.

[PK61809] "Page Usage Count Error" was being returned when a map was run with the input file having 2000 or more transactions. This was caused by buffers that were released twice. The code that was manipulating the release flags was modified and code was added to clear the buffer.

[PK64167] "FAIL function aborted map" and "Not enough memory to execute map" errors occurred when using the API to execute a map to retrieve more than 10000 records from an Oracle database on Windows XP. Added code in EchoIn to free the Operand corresponding to the first parm when the second parm is NONE.

[PK64448] When returning the last Clone in a set, a copy of an Operand in a SeriesListCode was left in the buffer with the release bit set, causing the engine to abnormally end. Code was added to clear the release bit and buffer address.

[PK65061] An issue arose when FindOperand did not return the item buffer because it was too large, causing a 'Disk Read Error'. Now the GetDataPtr is forced to make sure the offset and length is in the buffer.

[PK65136] Fixed an issue with HANDLEIN that caused random failures where the execution engine was in a loop and output volumes filled up one or more SYSTMP files. If a target map input file was in burst mode the map would loop since the code for bursting was missing.

[PK65155] A system abnormally ended with a stack trace error of ICULeavSomething when a map invoked the LeavePrint function. This occurred when the data was read in from MQ and was in UTF format. The problem only occurred when the XML data was missing a carriage return/line feed on the last line of the data and the data was transferred to UNIX as binary so that the carriage returns were not removed. The problem did not occur if the data was transferred to UNIX as ASCII, which removed the carriage returns. Code to determine the maxcharlen of the converter was added, and ICULeavePrint now no longer abnormally ends, and output is successfully returned.

[PK65815] Fixed a performance problem with the engine related to “Date & Time” types. The problem was exposed with high system-time calls in mappings, resulting in high kernel cpu loads. Now, the ‘time’ system call is called only once for input and once for output.


Database Interface Designer

[PK63059] Fixed an issue where the Database Interface Designer (DID) abnormally ended after generating a type tree in MDQ from SQL Server 2005 Express Server. Now the DID releases the OLE DB-based COM interfaces in the proper order so that memory corruption does not take place. Also, the proper COM interfaces are released when working with WebSphere Transformation Extender 8.1 internationalized connectivity structures.


Eclipse Design Studio

Map Designer

[PK62593] Invalid rule pop-up windows that appeared when dragging unresolved rules starting with a comment no longer occur.

[PK61938] Fixed a map analysis issue that caused "Invalid map number on check 3" and "Map compilation failed" errors, when the map name length was 32 characters.

[PK63834] Fixed a problem with the Map Designer where it failed to run DataPower maps if two or more executable maps used the same type tree with different types in the tree due to a compiled type tree file naming convention. A new naming convention was designed to resolve this issue, and maps run as expected without producing a 'Could not read map' error.


Type Designer

[PK62262] Binary Date and Time Formats code was modified to prevent errors that occurred in the Type Designer when creating and using a DateTime field of Binary type. After receiving an Eclipse error dialog, nothing happened if an attempt was made to try to drill into the Item subclass using the + sign, and the Item Subclass in the properties field could not be expanded. This is now fixed.

[PK65361] Fixed an issue where the binary date attributes were not being saved in the Type Tree. The Number, Packed, and Size attributes were limited to the same set of values as for Number, Integer. Both Date and Time Binary issues were fixed for Type Properties.


XML Schema Importer

[PK65365] Fixed an issue where the Schema Importer was not correctly importing referenced schemas. The way the extended types are handled in redefine mode was changed by reusing the compositor of the base type, instead of creating a new one.

[PK65609] The XML importer previously detected imbedded spaces in element names and generated an error report, but leading and trailing spaces were truncated with no error detected and no analysis errors reported. Now an xsd element that has leading or trailing spaces is correctly detected as an error during type tree import and an error is reported.


[PK56110/PK60345] There are 2 resolved APARs that contributed to changes in the structure of the type trees imported from an XML Schema using the Classic option. Their effect on the type tree structure is described in the following section:

PK56110 - If a group representing a compositor (xs:sequence, xs:choice, xs:all) has a single component with a range (1:1), the group is removed.

PK60345 – If a type tree contains a structure like the following structure:

          - choice (1:1)
                  - Seq1
                    - element (0:s)
                  - Seq2
                    - element (0:s)

          it will be transformed into the following structure:

                - choice (0:1)
                  - Seq1
                    - element (1:s)
                  - Seq2
                    - element (1:s)


=====================================================================
7. COMMAND SERVER NOTES
=====================================================================

These notes are for the Command Server component of the following products:
- IBM WebSphere Transformation Extender with Command Server
- IBM WebSphere Transformation Extender with Launcher
- IBM WebSphere Transformation Extender Design Studio


Installation Information
Because procedures for Command Servers for Windows, HP-UX, RS/6000 AIX, and Solaris platforms might differ slightly, specific instructions are provided during the installation program to guide you.

The Command Servers for Microsoft Windows are components of the Client install and are installed with the IBM WebSphere Transformation Extender with Command Server and IBM WebSphere Transformation Extender with Launcher. These Command Servers are also available as components of the Command Server install for Windows-based platforms to be installed on your server for runtime purposes.

The ability to run maps at design time is provided with the IBM WebSphere Transformation Extender Design Studio install, but only from inside the Map Designer.

The HP-UX, RS/6000 AIX, and Solaris Command Servers are available as components of each platform-specific Command Server install to be installed on your server for runtime purposes.

The additional Command Servers for z/OS (Batch and CICS) that are not installed as components of the installation program for the products discussed in this file are available on platform-specific media. For information about the system requirements and procedures for installing these Command Servers, see the platform-specific readme, release notes, and the Program Directory.


Additional UNIX Runtime Information
You must also manually set the shared library path according to your platform. If you are going to configure the environment variables manually, do not execute the setup program; refer to the following section, Set Location for Temporary Files (DTX_TMP_DIR), for instructions.


Set Location for Temporary Files (DTX_TMP_DIR)
During map execution, the Command Server creates temporary files for resource handling purposes and for retaining debug information. The default directory for these temporary files is /tmp. However, you can specify the directory where you want these files to be kept by setting the DTX_TMP_DIR environment variable.

For example:

DTX_TMP_DIR=install_dir/tmp
export DTX_TMP_DIR

Note: If you choose to allow multiple groups to access the Command Server engine, the directory specified for DTX_TMP_DIR requires permission 777 to provide permission to the user, the group, and all others.

To accomplish this, run the chmod command:

chmod 777 $DTX_TMP_DIR

In addition, for multiple users or groups, define a DTX_TMP_DIR instead of letting it default to /tmp. This DTX_TMP_DIR variable must be defined and exported prior to running the chmod command. The DTX_TMP_DIR variable is defined and exported by the user or with the setup script.


Environmental Debug Information (DTX_DEBUG)
If a problem is encountered during map execution and the DTX_DEBUG environment variable had been defined, the Command Server can produce environmental debug information that can be helpful when determining the cause of the problem.

When you define the DTX_DEBUG environment variable, environmental debug information is recorded in a file named dtxinfo.log located in the directory defined by the DTX_TMP_DIR environment variable (which is the /tmp directory if DTX_TMP_DIR is not defined).

By default, the DTX_DEBUG environment variable is not defined and environmental debug information is not recorded.


Enabling Environmental Debug
To enable the environmental debug facility, set the DTX_DEBUG environment variable to TRUE.

For example:

DTX_DEBUG=TRUE
export DTX_DEBUG

The information recorded in the dtxinfo.log file provides information that can be useful when troubleshooting a specific map. The following is a sample of the information contained in the environmental debug file:

PROCESS_ID: 2309, API_REF: 1
Date/Time: Fri Jul 25 14:30:09.279783 2003
FILE: mercmain.c, line: 714
info: [IBM WebSphere Transformation Extender Product
Version: 0.0]

PROCESS_ID: 2309, API_REF: 1
Date/Time: Fri Jul 25 14:30:09.280252 2003
FILE: mercmain.c, line: 744
info: [IBM WebSphere Transformation Extender RUNNING:
Fri Jul 25 14:30:09 2003]

PROCESS_ID: 2309, API_REF: 1
Date/Time: Fri Jul 25 14:30:09.470357 2003
FILE: mercrun.c, line: 1951
New Map File - Fri Jul 25 14:30:09 2003
[/install_dir/examples/general/map/sinkmap/sinkmap.mmc]


Disabling Environmental Debug
To disable the environmental debug facility, set the DTX_DEBUG environment variable to FALSE.

For example, you might type:

DTX_DEBUG=FALSE
export DTX_DEBUG


Configuring the Map Execution Environment
Because file locking applies to all files to which were written during map execution, configure your map settings or use the appropriate execution commands to support it.

Examples include:

• A map's output files can be managed using the Retry setting or execution command (the Rc: i option within the -Ofx command).
• The work files, audit log, and trace files can be managed through the MapAudit, MapTrace and WorkSpace settings or using the execution command (-Yc: i).
• Another option for work files and audit log files is to specify the use of unique file names. Set the MapAudit and WorkSpace > FilePrefix settings to Unique or specify this option using the corresponding execution command ( WU and -AU).

Note: Because trace files do not have an option for using unique file names, they can be managed only
through the use of the map retry for non-data files execution command (-Y).

For information about specifying these settings and execution commands, see the Map Designer and the Execution Commands documentation.

Setting Shared Libraries Environment Variables
After you have installed mapping components on UNIX platforms, set the appropriate shared object path
environment variable to access the shared libraries. This procedure varies slightly depending on the platform
being used.

For example, to set this variable for an IBM RS/6000 AIX platform, enter the following:

LIBPATH=$LIBPATH: install_dir/libs
export LIBPATH

Note: The RS/6000 AIX platform caches shared libraries. This means if you update a shared library on the
disk, you will not be able to see the update. Use the slibclean command at user root to remove the old shared library from system memory.

To set this variable for an HP-UX platform, enter the following:

SHLIB_PATH=$SHLIBPATH: install_dir/libs
export SHLIB_PATH

To set this variable for Solaris platform, enter the following:

LD_LIBRARY_PATH=$LD_LIBRARY_PATH: install_dir/libs
export LD_LIBRARY_PATH

Note: These examples show install_dir/libs as the directory where the shared libraries are located.




=====================================================================
8. SOFTWARE DEVELOPMENT KIT NOTES
=====================================================================

These notes are for the Software Development Kit component of the following products:
- IBM WebSphere Transformation Extender for Application Programming
- IBM WebSphere Transformation Extender SDK

This section contains the following topics:
- Installation Prerequisites
- Online Library Installation
- Environment Variable
- IBM WebSphere Transformation Extender Integration For Java
Product Requirements
- IBM WebSphere Transformation Extender Integration for Java
Servlet Integrator
- EJB API based on Platform API
- EJB API based on IBM WebSphere Transformation Extender
Programming Interface
- IBM WebSphere Transformation Extender Programming Interface
Product Requirements
- C API
- COM API
- CORBA API


Installation Prerequisites

Online Library Installation
Software Development Kit documentation links to the Online Library and the Resource Adapters Library are dependent on the installation of the Online Library.

Environment Variable

• If you are installing the IBM WebSphere Transformation Extender for Application Programming or IBM WebSphere Transformation Extender Software Development Kit (SDK) with the intention of running the EJB API based on Platform API on your application server, the DTX_DO_NOT_CHDIR environment variable must be set to TRUE. When this variable is set to TRUE, the Platform API will not change to the directory where the compiled map is located. Anomalies in performance might be experienced.

The minimum system requirements, operating system requirements, exception, and installation details for the Windows-based and UNIX-based Software Development Kit are detailed in the following topics.

IBM WebSphere Transformation Extender for Application Programming
Integration for Java Product Requirements
To create map and type tree components for the IBM WebSphere Transformation Extender Integration for Java 8.2.x product, IBM WebSphere Transformation Extender Design Studio 8.2.x is also required.


IBM WebSphere Transformation Extender for Application Programming
Integration for Java Servlet Integrator
The following components must be installed to successfully run the Servlet Integrator:

• Web server and Servlet engine or an application server that has a Servlet engine available must be installed on the same machine as the Servlet Integrator.

• The servlet.jar file for Java SDK 2.1 must be installed. This file can be downloaded from the following Web site:

http://java.sun.com/products/

• For the UNIX version of the Servlet Integrator, ensure that the following variables in the install_dir/WI/webmapwizard.sh file are set correctly:

JAVA: Java 2 SDK installation directory
JAVAHOME: JVM installation directory
WIHOME: IBM WebSphere Transformation Extender
for Application Programming installation directory

Note: Servlet Integrator users must download the J2EE 1.5.b03 compliant API packages and place the j2ee.jar file in the environment variable CLASSPATH before running the Web Integrator Servlet wizard.


EJB API based on Platform API
The following components must be installed to successfully run the EJB API:

- EJB 1.0, EJB 1.1, or J2EE compliant application server must be installed on the same machine as the EJB API.


EJB API based on IBM WebSphere
Transformation Extender Programming Interface
The following components must be installed to successfully run the EJB API:

- EJB 1.0, EJB 1.1 or 2.0, or J2EE compliant application server must be installed on the same machine as dtxpi.jar.


IBM WebSphere Transformation Extender for Application Programming
Programming Interface Product Requirements
The IBM WebSphere Transformation Extender Programming Interface consists of:
- C, C#, COM, CORBA, Java, and RMI APIs.
- EJB examples

The required header files, library files, and IDLs for these APIs are located in the following directories:

- Windows
Headers - install_dir
Library - install_dir
IDLs - install_dir\idl

- UNIX
Headers - $install_dir/src
Library - $install_dir/libs
IDLs - $install_dir/idl


C API
The following compilers are supported for use with the C API:

Windows 2000/XP
Microsoft Visual Studio .NET

Sun Solaris 9/10
Workshop 6.0

AIX 5.2/5.3
IBM C/C++ 3.6.6.7

HP-UX 11/11.1
HP ANSI C++ A.03.30

IBM z/OS USS
z/OS v1.2 C/C++ Compiler


COM API

The following compilers are supported for use with the COM API:

Windows 2000/XP
Microsoft Visual Studio .NET


CORBA API
The following compilers are supported for use with the CORBA API:

Windows 2000/XP/2003
Java - JDK 1.5.b_03
C++
Microsoft Visual Studio 6
Microsoft Visual Studio .NET

Borland Enterprise Server (Visibroker Edition) 5.2
was tested with the CORBA API for release 8.2.x.




=====================================================================
9. LAUNCHER STUDIO NOTES
=====================================================================

These notes are for the Launcher Administration, Management Console, and Resource Registry components of the IBM WebSphere Transformation Extender Launcher Studio product.

Non-Windows environments

This section contains the following topics:
- Configuration requirements
- Display Errors

Configuration requirements
For non-Windows environments, to use these products, the X Windows server, whose IP address or domain name that is specified in the export DISPLAY setting, needs to be running on the local host machine or system. You need to communicate to the remote system (X Windows client) where (display_name) on the local host to display the X Windows WTX GUI client application before you run the WTX GUI client application.

You will need to set the DISPLAY environment variable and export it to communicate to the X Windows WTX GUI client which X Windows server will do the displaying for it using the following syntax:

The syntax might vary depending on the shell version that you are using.

Syntax:

export DISPLAY=<display_name>:<server_display[.screen_number]>

Values:

• The DISPLAY environment variable name must be in uppercase letters.
  
• The display_name is the IP address or domain name of the local host machine that will be displaying the X Windows WTX GUI client application.
• The server_display refers to the number assigned to the X server that will do the displaying on the host machine.

Most of the time, you will specify the server_display as :0, and not specify the screen_number because most local host machines have a maximum of one display monitor, keyboard, and mouse.

If your system has more than one monitor (display screen), each of which is identified by a unique screen number, as in multi-headed systems, you will specify the screen_number by appending it to the end of the X server_display specification, for example, :0.1. This communicates to the remote server which screen the WTX application should access. The default screen_number is 0, which refers to the primary screen, and when it is 0, you do not need to specify it; for example, you can specify only the server_display simply as :0.


Example 1:

export DISPLAY=mycomputer.ibm.com:0

Values:

• mycomputer.ibm.com is the domain name of the local host that will be displaying the X Windows WTX GUI client application.

• 0 is the value for the server_display that is assigned to the DISPLAY environment variable.

Result:

• The host system exports the value to the X Windows client so that it will display the X Windows WTX GUI client application on the primary screen of the computer with the mycomputer.ibm.com domain name through the X server assigned as 0.

Example 2:

export DISPLAY=192.168.1.110:0

Values:

• 192.168.1.110 is the IP address of the local host that will be displaying the X Windows WTX GUI client application.

• 0 is the value for the server_display that is assigned to the DISPLAY environment variable.

Result:

• The host system exports the value to the X Windows client so that it will display the X Windows WTX GUI client application on the primary screen of the computer with the 192.168.1.110 IP address through the X server assigned as 0.

Display Errors
To avoid seeing display errors related to font.properties when starting the Launcher Administration, Management Console, or Resource Registry, ensure that the display X server has access to all fonts used in the font.properties of the Java installation.

On Solaris JVMs, the font.properties consistently refer to fonts not included with Exceed. This can sometimes cause havoc when displaying GUIs (for example, distortions and so on). To resolve this, a customized font.properties can be placed in your $HOME/lib directory. This will remove references to the offending fonts.




=====================================================================
10. WEB SERVICES NOTES
=====================================================================

One of the following IBM WebSphere Transformation Extender products,
including the Java Class Adapter or JMS Adapter, must be installed
prior to using Web Services:

- IBM WebSphere Transformation Extender with Command Server
- IBM WebSphere Transformation Extender with Launcher
- IBM WebSphere Transformation Extender for Application Programming
- IBM WebSphere Transformation Extender for Integration Servers

If you are using any of the following Java-based adapters, make sure
that you have installed the patches recommended for your HP-UX
version and Quality Pack:

- Siebel Business Object
- SOAP
- PeopleSoft Component Interface

The URL for these patches on the Hewlett-Packard Web site is:
http://www.hp.com/products1/unix/java/java2/sdkrte14/downloads/index_pa-risc.html

If you are using HP-UX version 11.11, the following patch is required to run any of the above-mentioned, Java-based adapters:

PHSS_28871




=====================================================================
11. CONTACTING CUSTOMER SUPPORT
=====================================================================

Contact Customer Support at 1-800-IBM-SERV, or go to the support portal.



=====================================================================
12. NOTICES AND TRADEMARKS
=====================================================================

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 document 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 document. The furnishing of this document does not grant 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-0032, 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 the 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:

IBM Corporation
577 Airport Blvd., Suite 800
Burlingame, CA 94010
U.S.A.

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

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

This information contains 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.

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Programming interface information
Programming interface information, if provided, is intended to help you create application software using this program.

General-use programming interfaces allow you to write application software that obtain the services of this program's tools.

However, this information may also contain diagnosis, modification, and tuning information. Diagnosis, modification and tuning information is provided to help you debug your application software.

Warning: Do not use this diagnosis, modification, and tuning information as a programming interface because it is subject to change.

Trademarks and service marks
IBM, the IBM logo and ibm.com are trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.

• Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries.
• IT Infrastructure Library is a registered trademark of the Central Computer and Telecommunications Agency which is now part of the Office of Government Commerce
• 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.
• Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
• Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation 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
• UNIX is a registered trademark of The Open Group in the United States and other countries.
• Cell Broadband Engine is a trademark 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 and logos are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Other product and service names might be trademarks of IBM or other companies.

This product includes software developed by the Eclipse Project
(http://www.eclipse.org/)