Release Notes for WebSphere Transformation Extender, version 8.2.0.6

Release Notes

Abstract

This document provides information about the release of WebSphere® Transformation Extender, version 8.2.0.6.

Content

IBM® WebSphere® Transformation Extender, version 8.2.0.6
release notes

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

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

About this release
Installation and configuration information
Upgrade and migration information
Known limitations, problems, and workarounds
New and changed behavior
Resolved Authorized Program Analysis Reports (APARs)
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.6 release is a full version of the product. Version 8.2.0.6 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
To download the software for WebSphere Transformation Extender V8.2.0.6, go to Passport Advantage Online.

After you install this 8.2.0.6 release, go to WebSphere Transformation Extender Support downloads to download and install any Interim Fix releases. For details about the Interim Fix, go to the IBM WebSphere Transformation Extender support web site.

For information about known problems and workarounds in Version 8.2.0.6, go to http://www.ibm.com/support/docview.wss?rs=2320&uid=swg21415601. For answers to frequently asked questions and workarounds for known problems in all WebSphere Transformation Extender releases, view the tech notes that are on the IBM Support web site.

For information about fix packs for versions of the WebSphere adapters that are packaged with this version of the IBM WebSphere Transformation Extender products, go to the WebSphere Adapters Family support web site.

For information about the documentation and how to access it, see the
Documentation release notes.

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.6 installs the IBM version of Java™ 2 Runtime Environment, Standard Edition, Version 1.5.0 SR9-0.

Use the installed version of JRE. If you configure WebSphere Transformation Extender to use a different JRE, it must be the same version as the installed JRE version.

The JRE is not included with the WebSphere Transformation Extender for z/OS® product, Version 8.2.0.6.

Native schema support

Opening maps referencing XML Schemas

The initial map open process fully parses and validates the schema and creates a read-only, intermediary native schema type tree (.mtx) file. Subsequent open processes retrieve the WebSphere Transformation Extender-specific information that is stored in this .mtx file, similar to the way the open process retrieves the information from a type tree (.mtt) file. Retrieving the information from the cached .mtx file is designed to improve the response time for opening maps that reference an XML Schema.

Support of Restart attribute and Reject function

WebSphere Transformation Extender information, including the Restart information, is stored in temporary, read-only native schema type tree (.mtx) files. A change to a schemas that is referenced in the .mtx file might update the .mtx file and remove the Restart information that is stored there. If this occurs, or if the file gets deleted, you must recreate the Restart attribute. In the Design Studio, right-click the type in the card and click Restart.

ODO rules supported on a DataPower platform

WebSphere Transformation Extender supports the Occurs Depending On (ODO) style of component rules on a DataPower platform. The ODO component rules start with the syntax constructs:
COUNT($) <= and COUNT($) =.

Use one of the following formats to create component rules that support ODO:

COUNT($) <= previous_component or constant
COUNT($) = previous_component or constant

The following list is the complete set of component rule formats that are available for you to use on a DataPower platform:

$ = numeric constant
$ = string literal
COUNT($) <= previous_component or constant
COUNT($) = previous_component or constant

COBOL Occurs Depending On component rules

COBOL provides support for a variable-length table data structure whose length is determined by the Occurs Depending On (ODO) clause and the data element that it identifies. A variable-length table
provides support for a table structure that contains a number of rows that are not defined at design time; for example, an account table which contains a varying number of accounts.

When you use the COBOL Copybook Importer to import a COBOL copybook that includes an ODO clause, the ODO restriction is not automatically imported into the type tree. If you need to impose the
rules necessary to enforce the ODO in the type tree, you must change the type tree after it has been imported.

The ODO restrictions are most commonly implemented in a WebSphere Transformation Extender type tree as component rules. To implement an ODO restriction as a component rule, put the component rule on the component that is identified with the ODO clause, used to determine the length of the variable-length table. The component rule references the previously defined component, identified by the ODO clause, which limits the number of occurrences of the current component.

The following example represents two lines from a COBOL copybook:

05 ORDREV_OUT_NUM_ACCTS PIC 9(04).
05 ORDREV_OUT_ACCOUNT_INFO OCCURS 0 TO 1000 TIMES
DEPENDING ON ORDREV_OUT_NUM_ACCTS.

Add the following type tree component rule to the construct that represents ORDREV_OUT_ACCOUNT_INFO:

ORDREV_OUT_ACCOUNT_INFO
RULE: COUNT($) <=
ORDREV_OUT_NUM_ACCTS Field

When WebSphere Transformation Extender parses the data at run time, the ORDREV_OUT_NUM_ACCTS data field contains a numeric value. For this example, assume that at run time, the value of ORDREV_OUT_NUM_ACCTS is 50. That value will be used in the component rule: COUNT($) <= ORDREV_OUT_NUM_ACCTS Field, so COUNT($) <= 50.

When this rule is run, WebSphere Transformation Extender processes the first 50 occurrences of ORDREV_OUT_ACCOUNT_INFO, and treats any data that follows the 50 occurrences as the successive construct in the copybook.

If the component that limits the number of occurrences is not numeric, then you might need to specify some additional component rule functions. The following example specifies ORDREV_OUT_NUM_ACCTS as text, not numeric.

05 ORDREV_OUT_NUM_ACCTS PIC X(04).
05 ORDREV_OUT_ACCOUNT_INFO OCCURS 0 TO 1000 TIMES
DEPENDING ON ORDREV_OUT_NUM_ACCTS.

You need to specify a rule that converts the text item to a number, as in the following example:

ORDREV_OUT_ACCOUNT_INFO
RULE: COUNT($) <=
TEXTTONUMBER(ORDREV_OUT_NUM_ACCTS Field)

To do before opening the Design Studio

By default, Eclipse applications cache plug-ins. In certain circumstances, the default Eclipse behavior might prevent Design Studio from opening, cause Design Studio to be unstable or to exhibit the behavior of an earlier release, or cause the run map process to fail.

To avoid these problems, take one of the following steps before you open the Design Studio application:

Clear the cached version of the Design Studio plug-ins by running the cleanextenderstudio.bat batch file. The cleanextenderstudio.bat batch file is installed at the root of install_dir

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 to clear the cached version of the Design Studio plug-ins under the following circumstances:

Your workspace got corrupted.

In this case, the open process fails when Eclipse attempts to open the Design Studio.

You installed a patch provided by the WebSphere Transformation Extender customer support team that 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 WebSphere Transformation Extender.

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
=====================================================================

When you use WebSphere Transformation Extender with another product, ensure that you satisfy the system requirements of the base product and apply all required fixes to the base product. For information about product fixes, go to http://www.ibm.com/support/entry/portal/Downloads.

On all Microsoft® Windows® operating systems, ensure that the WebSphere Transformation Extender installation directory has Write permission for the logged-in user.

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

If you installed a previous version of WebSphere Transformation Extender, you can reuse your existing references to the installation location of the previous release. To reuse existing references, change the target installation location of Version 8.2 to match the path of the previous installation. For example, if you previously installed WebSphere Transformation Extender Version 8.1, change the installation path for Version 8.2 to c:\Program Files\IBM\WebSphere Transformation Extender 8.2.

Changing the JVM heap size in Design Studio
WebSphere Transformation Extender Design Studio sets a default Java Virtual Machine (JVM) heap size. You can adjust the heap size of the JVM to meet the needs of your installation. To change the heap size, edit the C:\IBM\WebSphere Transformation Extender 8.2\ExtenderStudio.bat file and change the value of the -Xmx640M parameter. For example, to set the default heap size to 1 GB, change -Xmx640M to -Xmx1024M.

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

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

Support for DataDirect ODBC drivers
WebSphere Transformation Extender supports DataDirect ODBC drivers release 5.3 on both UNIX® and Windows® systems.

WebSphere Transformation Extender does not support DataDirect ODBC drivers on Linux for System z®.

Prerequisite procedures for running ODBC Adapters

To run the ODBC Adapters on Windows or UNIX operating systems:

Install the IBM-branded ODBC drivers on Windows or UNIX.
Configure the ODBC DSN on Windows or configure the odbc.ini file to define the ODBC DSN on UNIX.
Configure WebSphere Transformation Extender to access the ODBC DSN so that you can run maps on Windows or UNIX.

ODBC User's Guide:

The ODBC User's Guide is available in both PDF and HTML file formats on Windows and UNIX.

Windows
The PDF file (odbcuser.pdf) is located in <wtx install dir>\odbc\books\odbcuser.
The HTML help is located in <wtx install dir>\odbc\html. You can navigate to the HTML version by opening the help.htm file that is under the html subdirectory.

You can also navigate to the ODBC User's Guide by opening the books.pdf file under <wtx install dir>\odbc\books. The books.pdf file points to the User Guide as well as to other documentation.

UNIX
The PDF file (odbcuser.pdf) is located in odbc_drivers/book.
The HTML help is located in odbc_drivers/help. You can navigate to the HTML version by opening the help.htm file that is under the help subdirectory.

You can also navigate to the ODBC User's Guide by opening the books.pdf file under odbc_drivers/book. The books.pdf file points to the User Guide as well as to other documentation.

To read about the new features of DataDirect ODBC drivers release 5.3, view the Preface section in the "What's New in This Release?" topic of the PDF or HTML version of the ODBC User's Guide.

Installing and configuring IBM-branded ODBC drivers on Windows

To install the IBM-branded ODBC drivers:

Select custom installation in the Setup program.
Make sure that the component for the "IBM WTX Branded ODBC Drivers" is selected in the Select Components window.
Complete entering the selections in the Setup program.

To configure the ODBC DSN:

Select Start > Settings > Control Panel > Administrative Tools > Data Sources (ODBC).
Select the System DSN tab, and then click Add.
In the Create New Data Source window, select the WTX IBM ODBC driver for this release and click Finish.
Enter the appropriate values in the window that opens for the WTX IBM ODBC driver that you selected.
Select the option that tests the connection from the WTX IBM ODBC driver to the database server that you previously configured. This step is optional.

Installing and configuring IBM-branded ODBC drivers on UNIX

To install IBM-branded ODBC drivers:

Select the appropriate ODBC driver option to install. Specific 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)

The IBM-branded ODBC drivers are installed on the UNIX operating systems listed above under the odbc_drivers subdirectory of the WebSphere Transformation Extender installation location. The readme.txt file in the odbc_drivers subdirectory contains details about the contents of the subdirectory, such as the release notes, configuration information, and instructions about how to access the ODBC driver help system.

To configure the odbc.ini file to define the ODBC DSN:

Configure the odbc.ini file, which is located in the odbc_drivers subdirectory, to define the ODBC DSN. For instructions, see "Configuring the Product on UNIX/Linux > Data Source Configuration > Configuration Through the System Information File" in the ODBC User's Guide.

For your maps to use the ODBC settings in the odbc.ini file at run time, you must first run the WebSphere Transformation Extender "setup" script. For details about how to run the "setup" script, see the Configuring UNIX environment variables section. After you run the script, the ODBC library paths are automatically configured.

Configuring access to the ODBC DSN

To configure WebSphere Transformation Extender to access the ODBC DSN so that you can run maps that use ODBC Adapters on Windows or UNIX:

To configure the ODBC DSN

To configure the odbc.ini file to define the ODBC DSN

Database Query File
This is the name of the file that you used in step 1.
Database
This is the name of the database that you defined in step 2b.

When you use an MDQ file:

-MDQ <mdq file>
<mdq file> is the name of the file that you used in step 1.
-DBNAME<db name>
<db name> is the name of the database that you defined in step 2b.

When you do not use an MDQ file:

-DBTYPE ODBC
-SOURCE <data source>
<data source> is the DSN that you used in the "To configure the ODBC DSN" procedure on Windows, and the "To configure the odbc.ini file to define the ODBC DSN" procedure on UNIX.

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

Product requirement for exporting type trees as schema

The Export as Schema utility requires Microsoft .NET framework version 1.0 or 1.1. You can use the Export as Schema utility to export a type tree:

In the Design Studio, by clicking Tree > Export as Schema
In the command line outside of the Design Studio, by using the texport utility command

Configuring UNIX environment variables
The environment variables that are required to execute a 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 is the directory where you installed the 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. The root user must reset the Soft DATA Segment value to a value that is larger than the default.

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 run on the machine

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

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++ Runtime Package Maintenance Level
If you are currently using either the 7.0.0.1 or 7.0.0.2 maintenance levels of the IBM XL C/C++ runtime environment component for AIX 5 (xlC.aix50.rte runtime package), you must install maintenance level 7.0.0.3 or later to use the WebSphere Transformation Extender software on AIX platforms.

If you are currently using a maintenance level that is within the 8.0.0.2 through 8.0.0.9 range, or any other level that does not include the fix for AIX APAR IY87291, you must install the AIX APAR fix.

To download the latest maintenance level of xlC.aix50.rte runtime package or the AIX fix for APAR IY87291, contact IBM AIX support.

To use the WebSphere Transformation Extender software on AIX V9.0 operating systems, you must install the required IBM XL C/C++ runtime package maintenance level 9.0.0.5 or later. To download the PTF, go to http://www.ibm.com/support/entry/portal/Downloads/Software/Rational/XL_C~C++_for_AIX.

Running the maxdata script on AIX platforms
The maxdata script sets the maximum number of data segments that a process can use on your AIX system. Run the maxdata script on the 32-bit version of WebSphere Transformation Extender before you run any maps. It is not necessary to run the maxdata script on a 64-bit version of WebSphere Transformation Extender.

The script requires a 777 permission level. Run the script once for each WebSphere Transformation Extender executable, such as the launcher executable or the dtxcmdsv executable. When an executable is updated or replaced by the installation of a patch or an update, run the script again.

To run the script:
1. Change to the install_dir/bin directory.

cd $DTX_HOME_DIR/bin

2. Specify

./maxdata ./

executable_name segments

where segments is the number of 256 MB data segments that a process can use. For example:

./maxdata ./launcher 8

Number of Segments	Process Memory Limit
0	256 MB
1	256 MB
2	512 MB
3	768 MB
4	1024 MB (1 GB)
5	1280 MB (1.24 GB)
6	1536 MB (1.5 GB)
7	1792 MB (1.75 GB)
8	2048 MB (2 GB)

HP-UX product requirements
To run the Launcher on HP-UX platform, use the following settings for max_thread_proc and maxdsiz:

Kernel Parameters	Default Value	Increase To
max_thread_proc	64 processes	512 processes
maxdsiz	64 MBytes	<user dependent>

The value of maxdsiz depends on the amount of available memory and the size of the data used in the maps that are being run. The default of 64 MB is typically not enough. If memory permits, set maxdsiz to 512 MB for large data.

Recommended patches for Java-based adapters

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

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

To obtain the patches, go to the Hewlett-Packard web site http://www.hp.com/products1/unix/java/java2/sdkrte14/downloads/index_pa-risc.html

On HP-UX version 11.11 systems, the PHSS_28871 patch is required to run any of the Java-based adapters listed above.

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.

(This step is not necessary for AIX and HP-UX platforms.)
Install Java™ 2 SDK, Enterprise Edition (J2EE™) 1.5.0 SR9-0 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
The IBM version of Java™ 2 Runtime Environment, Standard Edition 1.5.0 SR9-0 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
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.
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.

Installing CICS Adapter when WebSphere Transformation Extender for Application Programming is not installed
Use this procedure to install the required CICS server-side components when WebSphere Transformation Extender for Application Programming is not installed on a z/OS system. This procedure is not required on a system where WebSphere Transformation Extender for Application Programming is installed.

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:

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.
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' +
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.
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)
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. After installing the jar files from an appropriate j2ee installation, modify the CLASSPATH to include the modules.

Oracle and Oracle AQ Adapters
This release supports Oracle database and Oracle AQ versions 9i, 10g, and 11g.

Library files for Oracle database and Oracle AQ adapter version 9i are installed by default and are referred to as the "base" product. However, the product installation directory contains a set of Oracle adapter libraries that support both the Oracle 10g and 11g database clients.

To enable the WebSphere Transformation Extender Oracle adapter to communicate with an Oracle 10g or 11g database client, use the following platform-specific instructions to copy the version 10g library files to the "base" library file names.

	Oracle Database Adapter "Base" Library File Names	Oracle AQ Adapter "Base" Library File Names
Windows	m4ora.dll	m4aq.dll
UNIX	libm4ora.so(.sl)	libm4aq.so(.sl)

UNIX
1) Change the directory to install_dir/libs.
2) Copy the libm4ora10g.so(.sl) Oracle database adapter to libm4ora.so(.sl).
3) Copy the libm4aq10g.so(.sl) Oracle AQ adapter to libm4aq.so(.sl).

An additional version 9i library is installed with the product. To revert back to version 9i, copy the version 9i library files to the base library file names. For example, copy libm4aq9i.so(.sl) to libm4aq.so(.sl).

Windows
1) Go to the product installation directory.
2) Copy the m4ora10g.dll Oracle database adapter to m4ora.dll.
3) Copy the m4aq10g.dll Oracle AQ adapter to m4aq.dll.

An additional version 9i library is installed with the product. To revert back to version 9i, copy the version 9i library files to the base library file names. For example, copy m4ora9i.dll to m4ora.dll.

When you use Oracle database and AQ adapters together in the same system, their Oracle client versions (9i and 10g) must match and also be for the version of Oracle that is installed on the server. The exception is when you are connecting to version 11g, in which case, the Oracle database and AQ adapters must be versions 10g.

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.

Sybase 15 adapter

This release supports Sybase database versions 12.5 and 15. The Sybase database adapter library file for version 12.5 is installed by default and is referred to as the "base" product. However, both version 12.5 and 15 libraries are
provided in the product installation directory.

To use version 15, rename the version 15 library file (for example, m4sybs15.dll) to the "base" library file name (for example, m4sybs.dll).

Sybase database adapter "base" library files:
Windows: m4sybs.dll
UNIX: libm4sybs.so(.sl)

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

UNIX
1) Change the directory to install_dir/libs.
2) Rename libm4sybs15.so(.sl) to libm4sybs.so(.sl).

To revert back to version 12.5, you can repeat the same process using the additional version 12.5 library that was installed with the product. For example, rename libm4sybs12.so(.sl) to libm4sybs.so(.sl).

Windows
1) Go to the product installation directory.
2) Rename m4sybs15.dll to m4sybs.dll.

To revert back to version 12.5, you can repeat the same process using the additional version 12.5 library that was installed with the product. For example, rename m4sybs12.dll to m4sybs.dll.

VAN Adapter
Scripts for the VAN adapter are located in:

install_dir\examples\adapters\van\scripts

The VAN adapter installation requires a current version of Cleo A+ to 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 who are installing the VAN Adapter for the first time should contact CLEO Communications to order Cleo A+ for Windows.
Customers who are upgrading from an earlier version of the VAN adapter should contact CLEO to order an upgrade from the earlier version of Cleo A+ provided with the VAN adapter. To order your upgrade, you must provide the serial number from your original Cleo A+ software.

To contact CLEO Communications, go to http://www.cleo.com/.

Custom functions

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

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

If you migrate to version 8.2.0.6 from a release other than version 8.2.0.5, you might need to recompile maps that use International Components of Unicode (ICU) character sets. See the tech note at https://www.ibm.com/support/docview.wss?uid=swg21442962 for details.

Maps, type trees, and systems from versions 5.0 and later can be used with 8.2. You must regenerate systems. 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 migrate from 8.0 to 8.2.0.6, you must run your database triggering scripts to successfully run source-triggered database systems. After version 8.2.0.6 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.6).

[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.0 or later, after the type tree has converted successfully, some of the input map rules might not be converted, and 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 not converted, use Map Designer to complete the conversion process:

Open the map.
Delete the unresolved rules.
Compile and rerun the map.

String Literals
All string literals held in rules are encoded in UTF-16 (Unicode). The strings are converted to the appropriate code page when they are used in a rule. However, when a map writes a string literal to a binary text type, the data is written as UTF-16 because binary types have no code page encoding assigned to them.

Opening files from an earlier version
When you save a source file from an earlier version of a WebSphere Transformation Extender product component in the current version, WebSphere Transformation Extender automatically converts the content and structure of that file to the format of the current version.

After you convert a source file to the current version format, do not open it in earlier versions of a WebSphere Transformation Extender product component. The format of the map source has changed and there are additional 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. Earlier versions
converted *.mtt files on disk; v6.7 and this version convert *.mtt 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 are to run 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 upgrade from an earlier version of the UNIX Launcher (formerly known as the Event Server) that started and stopped your UNIX Launchers with a script file containing the unsupported "lci -start" and "lci -stop" commands, you must change your existing script files:
To start the Launcher, change lci -start to launcher.sh -start
To stop the Launcher, change 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. The <listen_port> is not required for the -start option, however, if you specify it, 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.

If you open a map that was created an earlier version and references a custom adapter or an adapter that is no longer supported, the Source or Target in the Edit Card dialog is blank. The map still builds successfully, but results in a "Source not available" or "Target not available" message when it is run. The solution is to select an adapter from the list in the Edit Card dialog.

Converting type trees generated in earlier versions
To convert type trees that were generated in WebSphere Transformation Extender versions 6.7, SP1, SP2, and 7.0, use the dsxmlconv utility command.

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

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 third-party software, the "Other" selection button for creating custom breakpoint colors for the Map Debugger is not keyboard-accessible.

Launcher

When WebSphere Transformation Extender 64-bit Launcher is installed on on AIX version 5300-06, the Launcher might not start. To correct the problem, after you run the setup script in the WebSphere Transformation Extender installation directory, enter the following command on the command line:

export AIXTHREAD_SCOPE=S

You also can add this command to the setup script to run the command 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 mixed content. For example, given the following schema:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="A">
<xs:complexType mixed="true">
<xs:sequence>
<xs:element name="B" type="xs:string"/>
<xs:element name="C" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:element>

And the following XML document:

<?xml version="1.0"?>
<A>
some text
First element
some other text
<C>Second element</C>
</A>

A validation map that uses this schema for its input and output cards does not create the mixed content in the output:

<?xml version="1.0"?>
<A>
First element
<C>Second element</C>
</A>

- XML schemas containing elements with the same name

WebSphere Transformation Extender maps do not handle XML schema sequences that contain elements with the same name. When an XML schema contains a sequence of elements that do not have unique names, a map creates the output correctly only for the first element. The map creates the output with empty values for all the subsequent elements that have the same name.

The workaround is to modify the XML schema and make sure that all of the elements contained in a sequence have unique names.

Example:

The following XML schema has a sequence that contains elements with the same name:

<xsd:element name=”test”>
<xsd:complexType>
<xsd:sequence>
<xsd:element name=”A” type=”xsd:string”/>
<xsd:element name=”B” type=”xsd:int”/>
<xsd:element name=”A” type=”xsd:string”/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>

When you run a map that uses a type tree imported from this schema within an output card, the map creates the following output:

<test><A>some text</A>1234 <A/></test>

For the first occurrence of the element with the name "A," the map correctly creates the output with the value "some text." For the next occurrence of the element named "A," the map incorrectly creates the output with an empty value.

Modify the XML schema so that all of the elements that are contained in the sequence have unique names. When you run the map that uses the type tree imported from the corrected schema, the map creates the following output:

<test><A>some text</A>1234<C>some other text</C></test>

The output for the first occurrence of the element with the name "A" has the value "some text," and the output for the element with the name "C" has the value "some other text."

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

- On a Windows platform, when you run a WebSphere Transformation Extender map 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 throws 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 produce 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.

Exception when using workspace from earlier version

In Design Studio V8.2.0.6, a workspace from an earlier version that contains adapter projects might trigger an exception in the WebSphere adapters importer wizard. A null pointer exception that is similar to the following example can occur when the server runtime variable of an adapter project points to jar file locations that do not exist.

java.lang.NullPointerException
at com.ibm.j2c.ui.internal.wizards.J2CWizard_CategoryPage.setupBuildModel (J2CWizard_CategoryPage.java:1257)
at com.ibm.j2c.ui.internal.wizards.J2CWizard_CategoryPage.performPageFinish (J2CWizard_CategoryPage.java:1212)
at com.ibm.j2c.ui.wizards.J2CWizard$4.run(J2CWizard.java:999)
at org.eclipse.swt.custom.BusyIndicator.showWhile(BusyIndicator.java:67)
at com.ibm.j2c.ui.wizards.J2CWizard.getPageNextToJ2CCategoryPage
(J2CWizard.java:992)

To correct this problem:

In the Design Studio, navigate to Window > Preferences.
Expand the Server folder and select Installed Runtimes. The Installed Server Runtime Environments window is displayed.
Click Edit on an installed server runtime to find the runtime variable for which the Generic J2EE Runtime window displays the Invalid location error message.
Do one of the following two choices:

In the Generic J2EE Runtime window, set the location value to the location of the jar files in the new installation path:
install_dir/ResourceAdapters/DependencyJars<new version>

If you already have another server runtime environment that points to the new installation path, you can remove the problematic runtime dependency definition.

To remove the problematic runtime dependency definition, select it in the Installed Server Runtime Environments window, click Remove, and click OK.
To determine which projects are problematic, view them in the list of errors in the Problems view.
Change the runtime location of the adapter projects from the earlier release of Design Studio to the new runtime environment location. To change the runtime location, select the project, click Properties, select Targeted Runtimes, select the existing runtime environment, which points to the new installation path, and click OK.
Restart the Design Studio.

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. To convert type trees that were generated in WebSphere Transformation Extender versions 6.7, SP1, SP2, and 7.0, use the dsxmlconv utility command by starting it from the command line.

When you use the dsxmlconv utility, you are not required to specify the importer type (-T) option.

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.

Resource Registry
When using the resource registry for database aliases defined in the database/query file (.mdq) or command line,
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 (??) are 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.

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

Layout of data in map trace files changed

When the map writes messages to the trace file, it includes the ellipses (...) only on user data that is longer than 16 bytes. It no longer includes ellipses on user data that is 16 bytes or less.

Consider an example where the user data has the value 'SYNTAX'.

Prior to this release, the input trace file entry would include the ellipses as indicated in the following example:

(Level 1: Offset 41, len 6, comp 5 of 7, #1, DI 00000005:)
Data at offset 41 (’SYNTAX...’) fails minimum size requirements
TYPE X’0007’ (LongSyntaxItem ROOT).

With this release, the input trace file entry does not include the ellipses because the user data is 16 bytes or less, as indicated in the following example:

(Level 1: Offset 41, len 6, comp 5 of 7, #1, DI 00000005:)
Data at offset 41 (’SYNTAX’) fails minimum size requirements
TYPE X’0007’ (LongSyntaxItem ROOT).

The following input trace file entry is an example of user data, value
'thisdatais21byteslong', that is longer than 16 bytes, and therefore, includes the ellipses:

(Level 1: Offset 41, len 21, comp 5 of 7, #1, DI 00000005:)
Data at offset 41 (’thisdatais21byte...’) fails minimum size requirements
TYPE X’0007’ (LongSyntaxItem ROOT).

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.

Deprecated Servlet Integrator and servlet support

The Servlet Integrator and servlet support are deprecated and not included in the 8.2.x.x product distribution.

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. Since WebSphere Transformation Extender 8.2.0.1, the 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 the CPACKAGE function instead. 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 converts 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.

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

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

For a list of APARs that are resolved in Version 8.2.0.6, go to http://www.ibm.com/support/docview.wss?&uid=swg27023924.

For lists of APARs that were fixed in earlier releases and are included in Version 8.2.0.6, go to

=====================================================================
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, the installation program provides specific instructions to guide you.

The Command Servers for Microsoft Windows are components of the client installation 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 installation for Windows-based platforms to be installed on your server for runtime purposes.

With IBM WebSphere Transformation Extender Design Studio, you can use the Map Designer to run maps at design time.

The HP-UX, RS/6000 AIX, and Solaris Command Servers are components of each platform-specific Command Server server installation for runtime purposes.

The additional Command Servers for z/OS (Batch and CICS) are available on platform-specific media. For system requirements and installation procedures for these Command Servers, see the platform-specific readme, release notes, and the Program Directory.

Additional UNIX Runtime Information
You must manually set the shared library path according to your platform.

Do not execute the setup program if you want to configure the environment variables manually. Instead, follow the procedure in Set Location for Temporary Files (DTX_TMP_DIR).

Set Location for Temporary Files (DTX_TMP_DIR)
During map execution, the Command Server creates temporary files for resource handling and for retaining debug information. The default directory for these temporary files is /tmp. To specify a different directory where for temporary files, set the DTX_TMP_DIR environment variable. For example:

DTX_TMP_DIR=install_dir/tmp
export DTX_TMP_DIR

If multiple users or groups are to access the Command Server engine, define a DTX_TMP_DIR instead of using the default /tmp directory. Define and export the DTX_TMP_DIR variable manually or by using the setup script. The directory specified for DTX_TMP_DIR must have permission 777 to provide permission to the user, the group, and all others. Define and export the DTX_TMP_DIR variable before you set the directory permission. To set the permission, run the chmod command:

chmod 777 $DTX_TMP_DIR

Enabling Environmental Debug Information (DTX_DEBUG)
When the DTX_DEBUG environment variable is defined, the Command Server can produce environmental diagnostic information that can be helpful when a problem is encountered during map execution. By default, the DTX_DEBUG environment variable is not defined and environmental debug information is not recorded.

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 (or in the /tmp directory, if DTX_TMP_DIR is not defined).

To enable the environmental debug facility, set the DTX_DEBUG environment variable to TRUE. For example:

DTX_DEBUG=TRUE
export DTX_DEBUG

To disable the environmental debug facility, set the DTX_DEBUG environment variable to FALSE. For example:

DTX_DEBUG=FALSE
export DTX_DEBUG

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]

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: Because the RS/6000 AIX platform caches shared libraries, if you update a shared library on the
disk, you will not be able to see the update. Use the slibclean command as the root user to remove the
old shared library from system memory.

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

SHLIB_PATH=$SHLIB_PATH: 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: In these examples, install_dir/libs is 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.x product, IBM WebSphere Transformation Extender Design Studio 8.2.x.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. To download this file, go to 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:

Files	Windows directory	UNIX directory
Headers	install_dir	$install_dir/src
Library	install_dir	$install_dir/libs
IDLs	install_dir\idl	$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.x.

Linking an application to an alternate ICU library version

WebSphere Transformation Extender uses ICU version 3.2 in 8.2.x.x releases.

A WebSphere Transformation Extender Application Programming Interface (API) user can link an application to a version of ICU other than ICU V3.2 by including the ICU version's lib names in the link line.

For example, to link your application to ICU V3.4.1, use the following link line:

-licuuc341 licuuc18n341 licudata341

If you do not want to specify the version numbers in the link line, the ICU team recommends that you start the icu-config script from the $(ICU_INSTALL)/bin/ directory.

To start the icu-config script, include the following code in your makefile:

ICU_LDFLAGS=`$(ICU_INSTALL)/bin/icu-config --ldflags-libsonly`

If you are using ICU V3.4.1, the icu-config script returns the following required link lines:

-licui18n341 -licuuc341 -licudata341

=====================================================================
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
To use these products in a non-Windows environments, the X Window server must be running on the local host machine or system.

The DISPLAY environment variable identifies the X Window server that is to display the X Window WebSphere Transformation Extender GUI client. The syntax might vary depending on the shell version that you are using. To set the DISPLAY environment variable:

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

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 is to display the X Window WebSphere Transformation Extender GUI client application.

server_display is the number assigned to the X Window server that is to display on the host machine.

Because most local host machines have a maximum of one display monitor, keyboard, and mouse, in most cases, you specify the server_display as :0, and omit the screen_number .

If your system has more than one monitor (display screen) as in multi-headed systems, each monitor is identified by a unique screen number. You specify the screen_number by appending it to the end of the X server_display specification, for example, :0.1. 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

Where:

mycomputer.ibm.com is the domain name of the local host that is to display the X Window WebSphere Transformation Extender GUI client application.
0 is the value for the server_display that is assigned to the DISPLAY environment variable.

192.168.1.110 is the IP address of the local host that is to display the X Window WebSphere Transformation Extender GUI client application.
0 is the value for the server_display that is assigned to the DISPLAY environment variable.

The host system exports the value to the X Window client so that it will display the X Window WebSphere Transformation Extender 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 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 that are not included with Exceed. This can sometimes cause problems such as distortions when displaying GUIs. To resolve this problem, a customized font.properties can be placed in your $HOME/lib directory, which will remove references to the problem 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

To download these patches from the Hewlett-Packard web site, go to
http://www.hp.com/products1/unix/java/java2/sdkrte14/downloads/index_pa-risc.html

If you are using HP-UX version 11.11, the PHSS_28871 patch is required to run any of the Java-based adapters listed above.

=====================================================================
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/).

WebSphere Transformation Extender, Version 8.2.0.6

[{"Product":{"code":"SSVSD8-1","label":"WebSphere Transformation Extender"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Not Applicable","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"8.2.0.6","Edition":"","Line of Business":{"code":"LOB59","label":"Sustainability Software"}}]

Tips

Release Notes for WebSphere Transformation Extender, version 8.2.0.6

Release Notes

Abstract

Content

Was this topic helpful?

Document Information

UID

Share your feedback

Need support?