Release Notes for WebSphere Transformation Extender V8.2.0.4

Release Notes

Abstract

This document provides information about the release of WebSphere® Transformation Extender V8.2.0.4

Content

IBM® WebSphere Transformation Extender, version 8.2.0.4 release notes (rev. 9)

© Copyright IBM Corporation 2006, 2010. 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

Software Development Kit Notes
For the following products:

IBM WebSphere Transformation Extender for Application Programming
IBM WebSphere Transformation Extender SDK

Launcher Studio Notes
For the following product:

IBM WebSphere Transformation Extender Launcher Studio

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

Contacting customer support
Notices and trademarks

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

This 8.2.0.4 release is a full version of the product. Release 8.2.0.4 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.4 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

After you install this 8.2.0.4 release, be sure to check the IBM Web site under
WebSphere Transformation Extender Support downloads
(http://www.ibm.com/software/integration/wdatastagetx/support/download.html)
if there are any Interim Fix releases to download and install. If there are any Interim Fix releases, see the 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.4&q2=technotes&sort=rk&tc=&ibm-search.x=16&ibm-search.y=11&dc=&dtm.

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.4 is installed with and supports the IBM version of Java™ 2 Runtime Environment, Standard Edition, Version 1.5.0 SR4.

Use the included JRE. If you configure your WebSphere Transformation Extender product installation to a different JRE, it must be the same version as the included version. You can upgrade the JRE service release (SR).

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

New WebSphere applications supported

WebSphere Transformation Extender adds support for the following WebSphere applications:

- WebSphere Integration Development 6.2
- WebSphere Message Broker 6.2

New operating systems supported

WebSphere Transformation Extender adds support for the following operating system:
- AIX version 6.1.a

New adapter supported

WebSphere Transformation Extender 8.2.0.4 provides adapter support for the following database server and messaging software versions:

- Oracle 11g
- Sybase 15
- SQL Server 2008
- TIBCO RV8

New WebSphere applications supported

- WebSphere Application Server 6.2
- WebSphere Enterprise Service Bus 6.2
- WebSphere Integration Developer 6.2
- WebSphere Process Server 6.2

Native schema support

Opening maps referencing XML Schemas

In earlier releases, each time you opened a map in the Design Studio graphical user interface (GUI) that referenced an XML Schema instead of a type tree, the process fully parsed and validated the schema,
which increased the response time. In this release, the initial map open process fully parses and validates the schema, but also creates a read-only, intermediary native schema type tree (.mtx) file. However, on subsequent open processes, it just retrieves the WebSphere Transformation Extender-specific information that is stored in this .mtx file, similar to how it retrieves the information from a type tree (.mtt) file. Retrieving the information from this cached file on subsequent open processes, is designed to improve the response time for opening maps that reference an XML Schema.

Support of Restart attribute and Reject function

The WebSphere Transformation Extender Native schema functionality now supports the Restart attribute and the Reject function. In earlier releases, the Restart attribute information used to be saved in type tree (.mtt) files. In this release, WebSphere Transformation Extender information, including the Restart information, is stored in temporary, read-only native schema type tree (.mtx) files. Any changes to schemas referenced in these .mtx files might cause the process that maps items from the schema, to update the .mtx file, and remove the Restart information that was stored there. If this occurs, or if the file gets deleted, you must recreate the Restart attribute by right-clicking the type in the card in the Design Studio, and clicking Restart.

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 need to make changes to 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 representing 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, the first 50 occurrences of ORDREV_OUT_ACCOUNT_INFO are processed. WebSphere Transformation Extender determines any data that follows the data consumed as the 50 occurrences, to be the successive construct in the copybook.

If the component that is limiting the number of occurrences, such as ORDREV_OUT_NUM_ACCTS in the previous example, 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

TEXTTONUMBER(ORDREV_OUT_NUM_ACCTS Field)

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, such as 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 run a WebSphere Transformation Extender map or system must be set prior to the running of the map.

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, run the setup program in the WebSphere Transformation Extender installation directory before running 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.

Run 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
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++ run-time package maintenance level 9.0.0.5 or higher. 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 is provided to increase the maximum values for memory availability on your AIX system. Run the maxdata script prior to running 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

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.

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

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:

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, 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
This release supports Oracle database and Oracle AQ versions 9i, 10g, and 11g.

Oracle database and Oracle AQ adapter library files for version 9i are installed by default and are referred to as the "base" product. However, another set of Oracle adapter libraries are provided in the product installation directory that supports both the Oracle 10g and 11g database clients.

To use Oracle 10g or 11g, you have to copy the version 10g library files to the "base" library file names. The base file names are listed below.

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)

To enable the WebSphere Transformation Extender Oracle adapter to communicate with an Oracle 10g or 11g database client, use the following platform-specific instructions.

UNIX

Change the directory to install_dir/libs.
Copy the libm4ora10g.so(.sl) Oracle database adapter to libm4ora.so(.sl), and the libm4aq10g.so(.sl) Oracle AQ adapter to libm4aq.so(.sl).

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

Windows

Go to the product installation directory.
Copy the m4ora10g.dll Oracle database adapter to m4ora.dll, and the m4aq10g.dll Oracle AQ adapter to m4aq.dll.

To revert back to 9i, you can repeat the same process using the additional version 9i library that was installed with the product. 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 same 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 in this case. They must both be the 10g version.

Sybase 15 adapter

Sybase database versions 12.5 and 15 are supported in this release. 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:
- m4sybs.dll (Windows)
- libm4sybs.so(.sl)(UNIX)

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

Change the directory to install_dir/libs.
Make a copy of libm4sybs.so(.sl) for "backup" purposes.
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

Go to the product installation directory.
Make a copy of m4sybs.dll for "backup" purposes.
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 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.3. 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 are migrating from 8.0 to 8.2.0.4, you must run your database triggering scripts to successfully run source-triggered database systems. After version 8.2.0.4 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.4).

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

Open the map.
Delete the unresolved rules.
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 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 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 run. The solution is to select an adapter from the list in the Edit Card dialog.

Converting type trees generated in earlier versions
You can start the dsxmlconv utility command from the command line to convert type trees that were generated in WebSphere Transformation Extender versions earlier than V8.0.

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

JRE version not supported on POWER7 processors

WebSphere® Transformation Extender V8.2.0.4 installs the IBM version of Java™ 2 Runtime Environment, Standard Edition, Version 1.5.0 SR4, which is an earlier version of Java than POWER7® processors require. Link to the workaround.

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.

JEXIT function

[PK80285] The JEXIT function does not work on the following operating systems:

This is a known product issue. Therefore, JEXIT is not included in the product installation for these operating systems. If you need to use JEXIT on any of them, contact customer support for WebSphere Transformation Extender products, and ask for the following fix: LAIF fix for WTX CQ 29424/APAR [PK80285]

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

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><B>1234 </B><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><B>1234</B><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."

Native schema maps

If you have maps that run successfully in earlier 8.2 versions of WebSphere Transformation Extender, such as 8.2.0.0, 8.2.0.2, 8.2.0.3, but fail to run in the 8.2.0.4 version, you might have to revise your map. This is because the process of mapping items from the schema has changed in this release.

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.

Exception when using workspace from earlier version

If you are in the 8.2.0.4 version of Design Studio, and are using a workspace created in an earlier version, which contains adapter projects with the server runtime variable pointing to jar file locations that do not exist, Design Studio might trigger a null pointer exception in the WebSphere adapters importer wizard similar to the following example:

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, do the following steps:

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 that are 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. Then you must change the runtime location to which the adapter projects from the earlier release of Design Studio are pointing, to that new runtime environment location. To determine which projects are problematic, view them in the list of errors in the Problems view.

To remove the problematic runtime dependency definition, select it in the Installed Server Runtime Environments window, click Remove, and click OK.
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.
The importer wizard should now run without triggering the null pointer exception.

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.

Message encountered after you select the option to prevent
type tree from being overwritten when using the XML Schema Importer wizard

When you are generating a type tree from an XML Schema using the XML Schema Importer wizard, and the type tree already exists, you are prompted to allow the generation process to overwrite the file, or to
prevent it from overwriting it.

If you click No in the Overwrite Warning window, the generation process displays the following extraneous error message:
"Cannot open ttmaker.log". The process did not overwrite the type tree, based on your selection, so you can ignore this message, and click Finish to exit the wizard.

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.

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.

Removing a Launcher system without shutting down other Launcher systems
To see how to remove a WebSphere Transformation Extender Launcher system without shutting down other Launcher systems, go to http://www.ibm.com/support/docview.wss?uid=swg21433119.

IBM MQ Adapter example produces unexpected results
To download the new IBM MQ Adapter example files and the instructions about how to run the example, go to http://www.ibm.com/support/docview.wss?uid=swg21441273.

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

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:

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:

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

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

Adapters

Archive Adapter

[PK75531] Fixed a problem with the tar adapter where the adapter would fail on PUT if the file name + dirpath was longer than 100 chars. The valid limit is MAX_PATH. Using tar to archive a file produced an error if the path/file name was in excess of 100 characters since tar has a limit of 100 chars, but only for file name itself (not for path + filename).

DB2 Adapter

[PK77103] Fixed an issue where the DB/2 native adapter was returning data in a text format, versus a packed binary format when using the DB2 native adapter (DB2 z/OS) to generate a type tree. Data will now be retrieved from the database as a sized binary group as defined by the DB design tools and TTMAKER. A sized binary group in this case is packed decimal.

FTP Adapter

[PK72640] Resolved an issue where using HANDLEIN in a map rule before calling the runmap resulted in a disk read error. The problem was in the Substitute function that caused an object to be a different size than the size of the input object it was based upon. Substitute did not indicate that the object no longer corresponded to the input object. When the run map tried to read the input object and the object was smaller than it was supposed to be, the run map reported a Disk Read Error. Now Substitute clears the dwDI variable in the Operand when it does a substitution. This indicates to the system that the resulting object no longer corresponds to the input object it was based upon, so HandleIn creates a temporary scratch file to hold the object, and the run map completes successfully.

HTTP Adapter

[PK77674] A change was made to enable the HTTP adapter to comply with the HTTP 1.1 RFC specification to prevent certain Web Servers and protocol analyzers from raising an error. Previously, if using port 8080 with the HTTP adapter the Header host was missing 8080 so an error was encountered. The HTTP adapter places the port number inside of the HTTP "Host" header whenever transmitting data to a host that resides on a different port than the default of 80. If sending data to a host on port 8080, then the HTTP Host header will be, "Host: xyzserver:8080", versus "Host: xyzserver". If a client uses the default port 80 then the map completes successfully.

Java Class Adapter

[PK78019] A fix has been made to the Java Class adapter to correct null pointer exceptions. These exceptions occurred whenever the IdleJava setting was enabled and no tracing was being performed. By idling out Java connections, all JNI and JVM objects can be freed and thereby enable better monitoring of overall JVM memory usage. The Java class adapter no longer generates a null pointer exception after disconnecting from an idle connection. Now the null pointer exception will only occur if tracing is disabled and the IdleJava setting setting expires.

[PK79397] Global reference leaks were encountered when using the Java Class adapter. Additional tracing logic was included in the dstxjpi module as a verification check to ensure that no WebSphere Transformation Extender Java-related adapters are contributing to a JVM leak.

JMS Adapter

[PK74950] Resolved an issue where messages were stuck in processing due to connection failures with the JMS Server. Now, the JMS adapter will re-process any watch events that could not be processed due to
connectivity problems. Whenever a connectivity failure occurs before the message is pulled from the JMS queue, the new code will notify the JMS listener that the message should be re-processed, thereby eliminating the possibility of "stuck" messages.

ODBC Adapter

[PK78030] Resolved an issue where using DataDirect ODBC drivers to connect to an SQL Server from AIX caused the "Error in SQLPrepare: No columns found for table M_CATEGORY:". The ODBC adapter was not
handling the left bracket surround character properly. If the left bracket was specifed, the prepare command correctly inserted the table name with the left and right brackets. However, the subsequent insert statement did not. The WebSphere Transformation Extender ODBC adapter now properly quotes table and column names with the MDQ specified "surround" character.

Oracle ODBC Adapter

[PK74934] Fixed a problem in the typesdb ja.txt file that caused the Type Designer to crash when analyzing a type tree with the locale in dtx.ini set to ja. The translation string 3199 was properly converted to English to fix the issue.

Oracle 10G Adapter

[PK74255] Fixed an issue that caused CLOB data to produce the following error in Oracle 10g: "<7171-003>: Error returned by OCILobWrite, errcode=24817 - ORA-24817: Unable to allocate the given chunk for current lob operation." CLOB data that exceeds 10 MB is passed to the Oracle 9i or 10g client in 10 MB increments. This method is required by Oracle on designated platforms that have a locale setting which is different from the Oracle server. Now the trace file will show the different chunks of CLOB data getting passed successfully to the Oracle client.

SOAP Adapter

[PK75861] When trying to trace or write out a large SOAP return message, the SOAP adapter intermittently returned an error:

*ERR: java.lang.Exception: All Java-based adapter-related tracing is now done without the possibility of memory access violations.

Before this fix, any string data that included a "%" character could lead to memory access violations.

SQL Server Adapter

[PK77071] Fixed an issue with the 64 bit version of the ODBC adapter where the "-ROWCNT" option did not work on HP-UX ItaniumII. The problem was due to a different interface in the 64 bit version of the SQLExtendedFetch function.

WebSphere MSQ Adapter

[PK74987] Resolved an issue that prevented clearing of a control block and losing count of QTY, which caused changing any object to zeros, clearing the QTY counter. The clean up flag is now reset and burst
now stops after QTY is fulfilled.

CICS Command Server

[PK79592] Added improvements to the CICS engine to reduce CPU time when not using logging. Now, with logging turned off, the need to call the connection manager to load the adapter list is eliminated. Also eliminated are CICS ASKTIME and FORMATTIME, loading and accessing the ICU message catalog, the CICS read file request to the WebSphere Transformation Extender map dataset, and all of the CICS and system services needed to create and destroy the LE enclave. These changes improve the use of the WebSphere Transformation Extender Platform API RunMap function.

Command Server

[PK78284] Fixed a problem where a z/OS map with VSAM input was only reading the first record of data. VSAM files will now be read correctly by the batch command server.

[PK78011] Fixed a problem where the map audit file reports the wrong work file size if the work file is over 2G. The reported valued was a negative number.

Core Engine

[PK78763] A change was made to the variable used to keep track of the count from a WORD to a DWORD. This fixes an issue where the result of a COUNTABS() function was incorrect if the number of input objects exceeded 65535.

[PK78874] Added code to prevent a loop when encountering <quote> in ICU Unicode when no value has been established for <anyquote>.

[PK79052] A modification was made to change the way the number of bytes remaining to be checked is calculated. This resolves an issue where input was marked invalid with certain pagesize settings.

[PK79471] Modified several mercmapr (engine) modules to resolve a performance difference between 8.1 and 8.2 on MVS.

[PK78248] Fixed a problem where a map that uses XSLT or any other customer function from libxmlib.so would fail on LINUX due to missing symbols.

[PK75582] Modified ProperCase so that when using ICU, we do the "propercase" "by hand", rather than using an ICU function to do the work. Now ProperCase goes through the data character-by-character setting the case using ICU functions when it is an ICU character set. ProperCase should get the same results for all character sets now.

[PK76702] Changed code in CheckDTEditString to correctly set the length of the "special value for NONE" and "special value for zero". This resolves an issue where the Map Compiler was setting an invalid length in the Edit String for a date/time object's special value for NONE, resulting in error 28.

[PK77783] Added code to set up packed and BCD numbers when they are the subject of a series-producing function. This fix is in generic code associated with the series-producing functions (as opposed to code specific to SUM) and resolves an issue where SUM(EXTRACT()) produced different results than SUM() given the same input data.

[PK57342] To prevent the engine from crashing when transforming SJIS to EBCDIC, code was added to recognize the Japanese EBCDIC and to set up the character-length array correctly.

[PK76169] Added code to check that the amount of data available during map input validation is at least as big as a pad character before searching for pad characters. This resolves an issue where a core dump occurred during map input validation in the ValidateInput() function when using WebSphere Transformation Extender 64bit on AIX.

[PK76261] The ONERROR() message was getting corrupted in the Audit log when executing a component rule passing a NULL as data. The Java module could not handle a NULL parameter and returned bad data. Now if a type fail (XML error) occurs, the component rule is not executed.

[PK76243] The Engine now calls ucnv_setSubstChars in the GetConverter function to replace the ICU substitute character for EBCDIC conversion in XML. "-UZICUQUEST" is the command line parm that will turn on this switch. This resolves the XML Parsing Error that reported data was not well-formed when trying to validate a file.

[PK75146] Memory corruption in the engine in EvaluateSeriesFunc caused the Launcher on Windows to not restart and to return a 128 null pointer exception. Now if the map is successful and MSD settings are correct, the launcher should successfully delete the input file.

[PK76286] Fixed the indexing issue for components in dstxxmlparser project that caused the component rule in the second or subsequent component of a group to display abnormal content trace and data auditing behavior. The component numbers, when the xml objects were pushed to the stack, were out of order.

[PK75644] Added code to set the "end of literal descriptor" indicator to resolve an issue where a map was building incorrect literal value descriptors for the hex literals used in a map rule.

[PK75957] Fixed a Reformat issue by replacing GetXMLSyntax with HandleGroup to build xml objects when attributes are set.

[PK76053] Modified the Reformat Function to resolve an issue with empty objects being built with only the initiator and terminator, but not the object itself, resulting in no output work file.

[PK78020] Fixed code in CSize to set the result to the number of characters returned by the "chopper". Previously, it was actually returning the total size of all characters rather than the count of characters on big-endian platforms.

[PK75558] Failing to free buffers in FillLeftRight while running a map resulted in a Page Usage Count Error. This happened when copying LOCAL input data into a buffer in FillLeftRight while failing to free that buffer before pointing the Operand at the resulting data.

[PK74793] Fixed an issue with the REFORMAT function losing bytes when storing pad characters. Added reformat code so that binary objects will always be considered as padded with NULLs.

[PK73751] Added code to clear the format string indicator in the Operand structure. This ensures that when converting a (character string) return value to a number, the conversion now allows for a decimal separator.

[PK74030] Fixed the CLONE function to resolve an issue with a memory leak in the buffer when using the Launcher. Now clone handling does not lose the buffer containing the original object being cloned.

[PK74253] Resolved an issue where the terminator value of Variable caused the map to fail. A change was made to PACKAGE to successfully handle the case in which there is no instance of the terminator in the work file.

[PK74139] Fixed an issue where the Trace file was not displaying numeric padded data for an output card. Now the message with the data is added to the code that builds padded numeric objects.

[PK73630] Modified code in libcoreapi.so to recognize that the level representing a search object cannot represent a series and that zero byte files are not subsequently produced upon output.

[PK73336] Fixed code that re-positions after setting literal strings that caused incorrect decimal representation for UTF16 big endian. Also added missing code to clean up after a character-set conversion
that changes the size of the string.

[PK73725] Changed the way a component number is stored and modified the level set in the XML parser code before calling SetTypeFound in the core engine. This resolves an issue where a data audit error was not providing accurate information about items in error. Now audit levels are set properly and the correct component number and level set are applied to the built object.

[PK74577] Added code in the RESTART logic to watch for end-of-data.
This resolves an issue where the Map Designer crashed running a validation map because once in RESTART, it failed to notice that we ran past the end-of-data for the input and continued to validate bad data until reaching the end of allocated memory.

[PK73216] Modified the properties for the EBCDIC tilde character to resolve an issue where UPPERCASE function converted the ~ (x'A1') character to ÷ (x'A1') on MVS when running a map using the WebSphere Transformation Extender Batch Command Server on z/OS. The EBCDIC table containing tilde character properites incorrectly had uppercase enabled.

Database Interface Designer

[PK78171] Fixed a save issue in dbmdqxml.cpp in the dbutil project to resolve an issue where a 7.5 version mdq file crashed the 8.1.0.4 DID when saving an mdq file.

[PK73513] Fixed a problem with Database Interface Designer where it did not allow you to specify SQL Server 2000 or 2005 instances in the Server fields leading to a connection failure. If you have different names for design and runtime, you need to follow the same naming convention to connect to the databases which are under server\instance combination.

Importers

WSDL Importer

[PK76327] Changed the WSDL adapter to use the operation name when constructing the request message of a SOAP operation. Previously, when using the WSDL Importer to create a type tree, the operation name was set to the WSDL message name instead of the operation name. This caused the web service to fail since there was no matching operation. If certain SOAP implementations require the request message name, the Java environment variable can be set as follows:

-Dadapter.wsdlimp.option.soap_request_name=message

[PK76962] Modified an incorrect prefix initiator in typetrees generated by the WSDL importer that was previously missing ':' after xmlns.

[PK75587] Fixed the WSDL Importer dialog to log and display nested exceptions from the importer. Previously, the WSDL Importer's Eclipse code failed to extract the error message from the exception, causing the importer to report "tree created successfully" when the tree was not found.

[PK75581] Fixed the default operation list setting to resolve an issue where a type tree that did not contain all elements was not imported correctly from WSDL.

XML Schema Importer

[PK77722] Added a branch in MetadataValidator's populateAbstractTypes method that checks if an element is nillable, and if so, changes the minOccur of its content container to 0. This resolves an issue where imported typetree elements were not declared optional even though the group was declared optional.

[PK74234] Resolved an issue where schemas imported with errors when generating a type tree due to a wrong conversion of the component paths from UTF-8. The length of the string that needs to be converted from UTF8 is stored in a WORD and not a BYTE.

[PK73772] Input documents which contain XML tags with valid XML sequences such as '&alt;', '>', '<' and so on, were rejected by the type tree as invalid input. The import fails because of structures not supported by the core engine. The schema importer was modified to not introduce the component rules that were responsible for failing the validation. As a workaround, the customer can either modify the schema and remove one of the types with the same name or remove the components from the resulting type tree.

Install

[PK75001] Added logic to insure the WebSphere Transformation Extender-provided java distribution is located prior to enforcing which JVM is selected for tooling execution. Previously assumed to be an installation problem, the prior changes to the tooling helper batch files assumed the java location was set by dtxcommon.

Integration Flow Designer

[PK79580] Resolved an issue with systems containing Pseudo maps caused by additional fields in the card structure which were not serialized properly. This resulted in improper retrieval from the system definition file (.msd) causing a failure to open the system definition file after saving it.

[PK75867] Fixed an issue where the Integration Flow Designer would crash when using SHIFT and ARROW keys without a text component selection in the System View, resulting in a Windows popup error.

[PK75481] Resolved an issue with the resource alias in the MapAudit Directory and Unique option resulting in a null string file name when hovering the mouse in the System view of the Integration Flow Designer on the Audit Log symbol.

[PK74884] Resolved an issue where the Custom Directory path was not saved for the Map Audit Setting. This caused the MapAudit, MapTrace and WorkSpace settings to not work properly with resource aliases. Settings are now retained with the resource aliases in them.

Java API

[PK77057] Resolved an issue where during the validation process, the Validation --> OnValidationError map setting is getting ignored and continuing the run in Map Designer and API. This resulted in the data log part of audit log to be incomplete if invalid data was entered.

[PK76764] The creation of new map instances from the Java API are now thread safe. Previously, startup threads involved with instantiating new maps, for example, through "new MMap", would encounter a race condition during initialization, leading to memory access violations.

Launcher

[PK79393] Modified the Java Launcher code to display error code7 for Unknown Error when it encounters error codes other than values 0 through 7.

[PK79413] Resolved an issue that resulted in a U4038 abnormal end while starting Launcher 8.2 on z/OS as a batch job. The following two DD statements when added to the DTXOPCON JCL disables Abend-AID and Fault Analyzer:
//ABNLIGNR DD DUMMY
//IDIOFF DD DUMMY

[PK78188] Fixed a problem with Dynamic Tracing facility where it did not work correctly when more than one watch or trigger component was present in the system. Also, replaced the DSTX reference in the trc file to Transformation Extender. Now, Management Console works fine with those systems having more than one component. Selecting 'Dynamic trace' option in the Management Console will not generate any exception internally and creates the .trc file as expected. The issue is specific to Windows platforms.

[PK79056] The refresh and rollback option cannot both be used with IBM MQSERIES. Customers must remove either the refresh or the rollback option to prevent intermittent stops, GPFs, or errors in *msl.txt.

[PK76468] Fixed a problem where the Management Console may fail to connect to the launcher on UNIX platforms. The nature of the issue is unit memory and the problem can be randomly exposed. Getaddrinfo
may fail causing all launcher server side ports not to establish listeners, ultimately causing all monitoring tools to fail to connect to the event server. The Getaddrinfo hints structure was not set correctly. Memset (&hints, sizeof(hints), 0) was used to reset to zero hints structure. It should be: Memset (&hints, 0, sizeof(hints))

[PK76111] Resolved an issue with the Java Event Server that resulted in duplicate launchers being started when more than one request to start the system occurred at the same time. Now when a system is in Starting state and another request to start the system occurs, the option to Start in the Management Console is disabled, and an error message, "Cannot start the system <system name> as it is in "System
Starting" state" is displayed.

[PK72124] Functionality was implemented in the launcher to call a new dstxpi function (mpiSetDTXINI) to set the ini file name if one is set through the launcher command line. This resolves an issue where parameters in the JNI Layer from an additional ini file created for multiple Launcher processes was not being recognized when a java adapter was loaded.

Launcher Agent

[PK76681] Resolved an issue where the Event Agent and Launcher Agent processes intermittently hung or did not respond. Whenever a new SSL connection cannot be accepted from either the Event Server HTTP adapter or the Internet HTTP client, the Event Agent times out after 30 seconds. This value can be adjusted through the DTX_SSL_ACCEPT_TIMEOUT_IN_SECS environment variable.

Management Tools

[PK74028] Resolved an issue where a fifo-s would not be closed right away when a process was stopped in the launcher, causing the error "Too many open files (errno:24)' - Closing the Process Stream" when the launcher was started. The fix is in EventServerThread.java.

Map Compiler

[PK78194] Added a new blob_DBLOOKUP_maprule_2 map to the code that uses the DBLOOKUP function in a map rule with the Database Adapter -MDQ and -DBNAME parameters. This resolves an issue where the DBLOOKUP function failed to execute when used in type tree component rule.

Design Studio

[PK78117] The Eclipse version of the Design Studio does not select the system class path while you are running maps inside of it, like the earlier non-Eclipse versions of Map Designer. Therefore, you need to specify the classpath in the "External Jar Files" section of the dtx.ini file, or move the JAR files into the WebSphere Transformation Extender installation directory.

[PK79527] Fixed an issue where the MapEditor.fMapPropertySheetPage was not set while a map was still loading. Also, the Extender properties buttons were missing and top level values were in the wrong sequence. Now Map editor initialization of the Map properties correctly sets input if the map is still loading.

[PK78913] Fixed a problem in export.c in mapsdb to resolve an issue where the Design Studio crashed when trying to export a map. The problem occurred because the code was not allocating the right bytes of memory for xml namespaces.

[PK79196] Updated the message in the ja (Japanese) translation file. Previously, input card names generated by the Wizard contained an unnecessary blank space in the Japanese Windows OS.

[PK78802] Added a missing enablement check for the Map Editor that caused the Design Studio ellipses button to not be highlighted when entering a rule.

[PK78764] Added synchronization code for the Type Tree editor to notify you when the file opened in the editor is deleted or moved, or its type stamp is changed. You will now see dialog followed by Save As dialog for the deleted/moved case and after reopening the editor for the content change case. This resolves the issue where a type tree opened in the designer is not refreshed when reimporting.

[PK78191] Fixed an issue where the Delete key was not working after using Shift + insert to paste object in a rule. The problem was that Shift + insert was also executing the insert (only) event which was to open the Functions view. When that happened, the editor lost focus and the key events went to the Functions view. Code was added to avoid calling the insert (only) event when doing Shift + insert and to leave the focus on the editor.

[PK74543] Modifications were made to code in the WTXClassLoaderFactory in the eclipsebridge project. The MFSEMDSOA jar file was causing the WebSphere Transformation Extender designers to crash when attempting to open maps, resulting in a java error. This file has been removed from the WebSphere Transformation Extender classpath.

[PK76920] Fixed a problem with the Map Designer where it did not handle resource aliases properly for the WorkSpace Directory map setting. Now the Map WorkSpace Directory setting handles the resource aliases properly.

[PK76726] The shortcut key Ctrl+B and the Map menu options do not work after selecting a functional map, as expected, but it was still possible to build a functional map using either the mouse or the Windows Application key on the keyboard. A .MMC file was produced (that would not execute) and if the map settings for the functional map dictated an audit log, this was created with only map inherited values for the input. Now, Build action is disabled from WIN for functional maps. The menu items now are disabled and a functional map cannot be built using either the mouse or the Windows Application key.

[PK76678] Resolved an issue where functions in the Functions view were getting replicated ad infinitum. The xmllib, mathlib and resourcelib libraries would appear twice. Now during any refresh, the functions are properly reloaded and updated in the list.

[PK75584] Fixed an issue in the Map analyzer isspace function that caused the Design Studio to crash when building a map with Japanese for the TypeName. Now the ICU isspace function is used and when the regional settings are changed to Japanese, the map is built and executed with no issues.

[PK75382] Fixed an issue that prevented mapping rules when a card name was the same as typetree objects. Previously, the card name could not contain the name of one the objects in the type tree path.

[PK74930] Type Tree values do not display correctly when changed in the BYTES section. The back end values for pad were updated, but the view was not refreshed properly. Specifying the size of the Pad variable depends upon the Pad To Size As variable. If the default SizeAs variable is Bytes, max bytes is selected. If it changes to Characters, max characters size is selected.

[PK74887] Fixed code in the TEImages.java plugin to resolve an issue with an incorrect icon displaying for the restart attribute in a map input card. The image name was misspelled, causing the red dot to appear as a red square when viewed from the Map Designer.

[PK74543] Fixed code in WTXClassLoaderFactory in the eclipsebridge project to prevent a java error code of 1073741819 when attempting to build a map. The MFSEMDSOA jar file caused the designers to crash and was removed from WTX classpath.

[PK73486] Resolved an issue that caused the Design Studio to crash when trying to add a group. This and subsequent slow performance was caused by printing invisible characters on the Details panel for big text selection. When a Type Tree node contains selected text that is quite big and "Show invisible characters" is not checked, the performance will not be affected.

[PK73609] Added expansion state to the Properties node to resolve an issue where the Expanded properties view was not maintained when navigating between components.

[PK73003] Added a fix to the parserul project to resolve an issue where a map compile returns an opcode error followed by Eclipse crash with a JVM error on map rules that are approximately 32K in size. The sizing limitation with rules in the output field has been resolved.

WebSphere Transformation Extender for Integration Servers

[PK79411] Fixed a JVM memory leak heap exposed when a WebSphere Transformation Extender map runs in a WebSphere Message Broker environment and the map uses a JAVA based adapter. Previously, running a simple message broker flow with a WTX plugin node that invoked the SWIFTNet-FIN pack Java validation component (JVC) (through the WebSphere Transformation Extender Java Adapter) caused the JVM to run out of memory and crash the broker. The problem is resolved with attaching/detaching each time to the JVM.

[PK77463] Fixed an issue with the way DTX accesses the timezone value, which caused an exception when trying to access the timezone external integer parameter when running WebSphere Transformation Extender for Message Broker. This produced an S0C4 abnormal end in coreapi.so during WebSphere Message Broker deployment.

[PK74284] Fixed an issue in MapSelectionDialog.java in the mercdev project that prevented selection of an executable map(mmc) from the WMB WTX node option when browsing to select an mmc after starting the toolkit with -vmargs -Duser.language={de} (German language setting). Now when German is selected as the language, maps with .mms extensions are displayed properly.

Native Schema Support

[PK77391] A memory storage leak found on z/OS was resolved by changing WtxMap's setNamespace method to free the instance of the passed WtxString if its string value is already in the namespace map. This allows the constructor to create an fData instance that adopts its elements to permit the fData's removeAllElements method to free its content.

Platform API

[PK79408] Added error messages to display when z/OS SDK InitializeRunMapInstance fails for any reason. Also fixed an error in the DD asembler code where it would return a good return code when the map was actually not found.

[PK75165] Corrected InitializeRunMapInstance to check for the DDNAME passed to resolve an issue with SDK on z/OS where all calls to the SDK resulted in a MAP INIT ERROR.

Resource Registry

[PK74669] Backup option was not working correctly when using the resource registry in the Command server. Fixed the Command Server backup option with resource name.

SUN Cluster

[PK74524] Fixed a problem with SUN cluster support where WebSphere Transformation Extender start and stop method would fail to bring up the event server resource after configuring the Sun system as a Cluster environment.

Type Designer

[PK79467] A change was made to the comparison algorithm in Typetree.IsRestrictionEqual(Typetree pTypeTree) to resolve an issue that caused the Design Studio to crash when comparing type trees.

[PK77825] Added code to do a more intelligent check for <WSP>, <OWSP>, and the various whitespace characters (regardless of how they're specified). This resolves an issue where the delimiter and terminator are not distinguishable in Record_invalid Group during type tree analysis.

[PK75382] Resolved an issue that caused a 'Cannot create view' error when using the German version of Windows only. Running cleanextenderstudio.bat resolved the issue.

[PK76093] Fixed an issue that occurred when a type tree is opened and closed with no changes made but you are asked to 'Save changes'. Now the Type Tree editor will not ask to save a file unless an actual change was made.

[PK75101] Setting locale=ja in the dtx.ini file caused the Type Designer to crash when analyzing. A fix was made to the 3199 translation string in typesdb ja.txt to allow for successful analysis.

[PK74027] Fixed an issue where 'Open type tree' did not work when a map was opened using file/file open. The Design Studio opens external types trees.

[PK74219] Propagation errors appeared when trying to propagate a numeric sign type. The function nomenclature Propagate was modified to allow propagation in the plugin properties package. This fixes the propagate issues in Type Properties.

[PK74315] Fixed an issue in the typesdb project (attrib.c) that caused padding for the Date/Time field to not work correctly. Now the pad value behaves correctly when changed and focused is returned.

[PK74431] Fixed the properties for DateTime in Type Editor plugin to allow for successful formatting of a partitioned type and the subsequent propagation of the changed format of its subtypes.

[PK74007] Enabled multiple selection in the Extender Properties view to allow propagation on multiple properties. Now selecting multiple properties by hitting the Ctrl key works correctly.

[PK72865] Fixed an issue with special characters when copied to the typesdb. Previously, editing the delimiter character, changing it to a comma temporarily and then placing a broken pipe character (¦) back in and attempting to save the map caused a map failure.

Type Tree Maker

[PK75190] Corrected issues with NONE and ZERO in type tree export and import. Previously, multiple type tree properties were lost during exporting and importing due to an incorrect internal script generation for NONE and ZERO. Missing assignments resulted in property values not being retained after the import.

[PK69960] Changes were made to ttmaker maps and trees to define a special value for empty on the Unordered component. This fixes an issue where the Imported Type Tree Maker file resulted in the Choice Group Subclass being changed to Sequence Group Subclass.

XML Parser

[PK78118] Fixed code in the dstxxmlparser project to prevent the map from building invalid offsets at different level sets, causing invalid output when using the RESTART attribute with partially invalid XML input.

[PK77602] Fixed an issue in Group Stack that caused an empty XML attribute field in a subsequent output card that contained a mapped value for an XML attribute to become empty (NONE) on subsequent cards. This caused an incorrect offset to be used when using an AttributeList object.

[PK77476] Fixed code to allow schemas to be located on the Web when calling WebSphere Transformation Extender from WebSphere Message Broker. Previously, the maps were held in Websphere Service Registry and Repository (WSRR) and the local policy did not allow the use of any files on the local file system.

[PK77477] Fixed an issue with namespaces when document verification is well formed. Previously, namespaces were ignored, causing the Map Designer crash on the second execution of a map.

[PK77041] Fixed an issue where XML data failed validation when using a large XML Schema imported type tree with well formed (Xerces only) data in the input card.

[PK77099] Resolved an unexpected parser error where the ouput trace contained invalid erroneous characters. This was caused by not allowing for the "where used" stuff in the TYPENAMES BYTEblk.

[PK76684] Resolved an issue where the Xmlparser was running out of stack due to extremely deep recursion in buildDataObjects. When a map was running in well formed mode, the namespaces were not being considered. So if an element with the same name but different namespaces were present in the same level, invalid objects were built, causing the Map Designer to crash on the second map execution.

[PK76260] Fixed an indexing issue for the components in dstxxmlparser project by adding code to unwind the xml stack when a exception occurred in the parser object. This previously caused objects to not be audited when input failed XSD validation.

[PK75763] Fixed an issue with restart. If a object is in restart mode, the stack is emptied at the endschema object mode. Previously, the map returned "input type contains errors". Now the correct response is "one or more inputs was invalid".

[PK76184] Fixed an issue where Restart was overriding the failure of component rule ONERROR(TEXTTONUMBER($)<4, "ERROR") on the ReceiverCode element. The map ended with both a 28 Warning and an 8 Failure, but the 28 Warning took precedence. Now the map returns 8 in both instances.

[PK74401] Fixed an issue with the XML decl in the dstxxmlparser project that prevented an XML header of <?xml version="1.0" encoding="UTF-8"?> to be written to output when the UTF8 ï»¿ character started the input file.

[PK72670] Fixed an issue with component rule validation for XML type trees that caused component rules for an item in a group to work on only the first instance.

[PK73735] Fixed an issue with Resart and the GetXMLErrorMsg function with non-well formed xml documents. A restart variable must be added to the Document Element Object under doc group. Once restart is added, the map runs successfully with "Input type contains error message".

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

The ability to run maps at design time is provided with the IBM WebSphere Transformation Extender Design Studio installation, 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 installation 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 run the setup program; see the following section, Set Location for
Temporary Files (DTX_TMP_DIR), for instructions.

Set Location for Temporary Files (DTX_TMP_DIR)
During the running of a map, 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 theCommand 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 the running of a map 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
Configure your map settings or use the appropriate execution commands to support file locking in all files that are written to during map execution:

Files	Managed Through
Output files	Retry setting Execution command: Rc:i option within the -Ofx command
Audit log	MapAudit setting Execution command: -Yc:i
Trace files	MapTrace setting Execution command: -Yc:i
Work files	Workspace setting 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).

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 removes 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 from the product page of the IBM Web site:

http://www.ibm.com/software/integration/wtx

=====================================================================
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
The following terms are trademarks or registered trademarks of International Business Machines Corporation in the United States or other countries, or both:

i5/OS
IBM
the IBM logo
AIX
AIX 5L
CICS
DB2
DB2 Universal Database
Domino
HelpNow
IMS
Informix
iSeries
Lotus
Lotus Notes
MQIntegrator
MQSeries
MVS
Notes
OS/400
Passport Advantage
pSeries
Redbooks
SupportPac
WebSphere
z/OS

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. 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.

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.

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

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

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

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

WebSphere Transformation Extender, Version 8.2.0.4

[{"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.4","Edition":"International;US","Line of Business":{"code":"LOB59","label":"Sustainability Software"}}]

Tips

Release Notes for WebSphere Transformation Extender V8.2.0.4

Release Notes

Abstract

Content

Was this topic helpful?

Document Information

UID

Share your feedback

Need support?