Release notes for WebSphere Transformation Extender, V8.4.0.2

Content

IBM WebSphere® Transformation Extender, version 8.4.0.2
release notes

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


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

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



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

This release is a full version of the product. Version 8.4.0.2 can coexist on the same computer with earlier point releases of the product starting from Version 8.1.


Where to find the software to download
To download the software for WebSphere Transformation Extender Version 8.4.0.2, go to Passport Advantage Online.

For details about supported hardware and software, see the system requirements.

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

For an overview of new features in this release, see the What's New information in the information center.

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

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 Launcher Studio
- IBM WebSphere Transformation Extender Design Studio with SDK
- IBM WebSphere Transformation Extender for Application Programming


WebSphere DataPower support
The key feature of this release is its compatibility with WebSphere® DataPower®. The additional updates that were not available in an earlier release of WebSphere Transformation Extender Design Studio that was compatible with WebSphere DataPower are listed in the What's New information in the information center. For information about the documentation and how to access it, see the Documentation release notes.

WebSphere Transformation Extender support for WebSphere DataPower aligns with and depends upon specific versions of WebSphere DataPower SOA Appliances. Disregard any references to DataPower-specific features in the WebSphere Transformation Extender documentation and in the Design Studio if there is no alignment of your version of WebSphere Transformation Extender with WebSphere DataPower SOA Appliances.

See the current alignment of WebSphere DataPower SOA Appliances with WebSphere Transformation Extender at: www.ibm.com/software/integration/datapower/library/documentation. Navigate to the information center for the specific WebSphere DataPower SOA Appliance and version, and go to the Software requirements topic under Integration > WebSphere Transformation Extender > Overview.

See the current alignment of WebSphere DataPower SOA Appliances with WebSphere Transformation Extender Enterprise Application Packs and Industry Packs at: www.ibm.com/support/docview.wss?uid=swg21452358.


Java™ Runtime Environment (JRE)
WebSphere Transformation Extender 8.4.0.2 installs the IBM version of Java™ 2 Runtime Environment, Standard Edition, Version 1.6.0 SR 9 FP2.

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

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


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

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

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

• Delete the .metadata folder that is in your workspace, and then reimport the workspace, or switch to a different workspace.

Run the cleanextenderstudio.bat batch file to clear the cached version of the Design Studio plug-ins under the following circumstances:

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

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

• You installed a fix pack release on top of a WebSphere Transformation Extender 8.4 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.

ODBC Adapter
The ODBC Adapter supports both IBM and DataDirect ODBC drivers. ODBC drivers from other vendors might work, but they are not tested for compatibility with WebSphere Transformation Extender. Because of this, the ODBC Adapter is usually better suited for use with IBM and DataDirect ODBC drivers.

However, when designing a map to connect to a DB2 data source that is located on a Linux®, UNIX®, Microsoft® Windows® or z/OS system, you might prefer to use the DB2 Adapter. The DB2 Adapter connects to the DB2 database without using an ODBC driver manager and still provides all the functionality that is present in the ODBC Adapter.

Specify the ODBC Adapter from either the map command line, for example, -DBTYPE ODBC, or from the Database Interface Designer, for example, in the "Adapter Type" field of the "Database Definition" window.

For more details about using the ODBC adapter, see the related topics in the WebSphere Transformation Extender information center.


DB2 Adapter
For the DB2 Adapter to connect with a DB2 database from a Linux, UNIX, or Microsoft Windows system, install an IBM Data Server Client Package. An IBM Data Server Client Package is available for you to download from the Internet for free. Select an IBM Data Server Client Package that includes the CLI driver, which the DB2 Adapter uses to connect to a DB2 database. When configuring a database connection for a z/OS or IBM i operating system, you also need a DB2 Connect license. For further information about choosing, installing, and configuring an IBM Data Server Client Package, see the IBM Data Server Clients and Drivers topic in the IBM DB2 Database for Linux, UNIX, and Windows Information Center.

Specify the DB2 Adapter from either the map command line, for example, -DBTYPE DB2, or from the Database Interface Designer, for example, in the "Adapter Type" field of the "Database Definition" window.

For more details about using the DB2 adapter, see the related topics in the WebSphere Transformation Extender information center.


WebSphere adapters
WebSphere Transformation Extender Version 8.4 includes Version 7.5 of the WebSphere FTP Adapter and WebSphere Email Adapter. See the WebSphere adapter requirements.


Native schema support

Opening maps that reference XML Schemas

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


Support of Restart attribute and Reject function

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


About translations
WebSphere Transformation Extender, version 8.4 products are available in the following languages:

• Brazilian Portuguese
• English (United States)
• French
• German
• Italian
• Japanese
• Korean
• Simplified Chinese
• Spanish
• Traditional Chinese

WebSphere Transformation Extender products display in English if the IBM representative of a country did not choose to translate them.


About documentation translations
When WebSphere Transformation Extender product documentation was not significantly updated for version 8.4, the information center and online library provide version 8.3 documentation, including 8.3 translations when they exist.

When WebSphere Transformation Extender product documentation was significantly updated for version 8.4, the information center and online library provide translations of the version 8.4 product documentation if the IBM representative of a country chose to translate them.

If a country did not choose to translate documentation that was updated for version 8.4, the information center and online library provide version 8.3 translations, if they exist. Otherwise, the information center and online library provide version 8.4 documentation in English.

For the latest documentation, see the English documentation in the information center on the web at:
http://www.ibm.com/software/integration/wdatastagetx/library



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

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


On all Microsoft Windows operating systems, ensure that the WebSphere Transformation Extender installation directory has Write permission for the logged-in user. Write permission is required to run a map.


Installing and uninstalling
WebSphere Transformation Extender products and online library

For the procedure to install WebSphere Transformation Extender products, go to http://www.ibm.com/support/docview.wss?rs=2320&uid=swg27019810.

For the procedure to uninstall WebSphere Transformation Extender products, go to
http://www.ibm.com/support/docview.wss?rs=2320&uid=swg27019817.

For the procedure to install the WebSphere Transformation Extender online library, go to
http://www.ibm.com/support/docview.wss?rs=2320&uid=swg27019816.


Default installation location
WebSphere Transformation Extender products are installed in the default location:
C:\IBM\WebSphere Transformation Extender 8.4

If you installed an earlier version of WebSphere Transformation Extender in a location that does not contain a specific version in the path, you can reuse the existing references to the installation location in various files such as batch, configuration, and initialization files. To reuse existing references that you have when doing product upgrades, change the target installation location of version 8.4 to match the path of the previous installation. For example, if you previously installed WebSphere Transformation Extender version 8.3 under C:\WebSphere Transformation Extender, after you uninstall the version 8.3 release, when you are installing version 8.4, you can change the default installation path for version 8.4 to C:\WebSphere Transformation Extender in the product installation wizard.


64-bit product versions
cannot be installed in the same directory as Design Studio
In WebSphere Transformation Extender version 8.4 and later fix packs, the Design Studio is a 32-bit application. You cannot install a 64-bit version of a WebSphere Transformation Extender product in the same directory as Design Studio.


Design Studio shared library requirements
Design Studio does not support 64-bit libraries. Install a 32-bit version of any product or component that shares a library with Design Studio. If you install both a 32-bit version of the product and a 64-bit version, ensure that the 32-bit version occurs first in the PATH statement.

For example, when you install both the 32-bit version and the 64-bit version of WebSphere MQ Explorer V7.0, ensure that the products occur in the PATH statement in the following order:

C:\Program Files (x86)\IBM\WebSphere MQ\bin;C:\Program Files (x86)\IBM\WebSphere MQ\bin64;


Changing the JVM heap size in Design Studio
WebSphere Transformation Extender Design Studio sets a default Java Virtual Machine (JVM) heap size. You can adjust the heap size of the JVM to meet the needs of your installation. To change the heap size, edit the C:\IBM\WebSphere Transformation Extender 8.4\DesignStudio\wtx_eclipse\eclipse\eclipse.ini file and change the value of the -Xmx512m parameter. For example, to set the default heap size to 1 GB, change -Xmx512m to -Xmx1024m.


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

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


Installing the example files
To install the WebSphere Transformation Extender example files on Microsoft Windows operating systems:

1. After you begin installing the WebSphere Transformation Extender Design Studio, in the Setup Type window, click Custom installation.
2. In the Select Components window, ensure that Example Files is selected.

The result is that the WebSphere Transformation Extender Design Studio installs the example files in the install_dir\examples folder.


Comment out malloc bucket configuration for 64-bit Launcher on AIX systems

On AIX® systems, an AIX APAR causes the Launcher to crash or hang when spawning processes on 64-bit WebSphere Transformation Extender. A known AIX problem can cause memory corruption in processes that use malloc buckets:

• AIX V5.3: APAR IV03273
• AIX V6.1: APAR IV20249
• AIX V7.1: APAR IV28148

Memory corruption causes random Launcher process crashes or hangs. To prevent the problem, edit the $DTX_HOME_DIR/bin/launcher.sh file and comment the lines as shown below:

#  if [ "`uname`" = "AIX" ]
#  then
#    export MALLOCOPTIONS=pool,buckets,bucket_sizing_factor:16,multiheap:8,considersize
#  fi



Required patch for 64-bit WebSphere Transformation Extender V8.4.0.x when using mtsmaker or any 64-bit database adapter

A patch is required only by customers who have a 64-bit runtime installation of WebSphere Transformation Extender version 8.4.0.x on a Microsoft Windows system and who use a database adapter or mtsmaker to create a type tree from a database. Please ensure that your system meets these specifications before you request the patch.

A mismatch between the common dbutil64 library and the adapter's code exposes the 64-bit version of any database adapter and the mtsmaker utility to memory corruption, bad memory reads and writes, or memory leaks on Microsoft Windows 64-bit systems.

Contact WebSphere Transformation Extender technical support to obtain the patch for APAR PM70729.



WebSphere adapter requirements
For WebSphere adapter system requirements, see:
Email adapter: http://www.ibm.com/support/docview.wss?uid=swg27020945
FTP adapter: http://www.ibm.com/support/docview.wss?uid=swg27020997


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


Prerequisite procedures for
running ODBC Adapters with DataDirect ODBC drivers

To run the ODBC Adapters with DataDirect ODBC drivers on Microsoft Windows or UNIX operating systems, you must do the following procedures:

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

ODBC User's Guide:

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


Microsoft Windows:
The PDF file (odbcuser.pdf) is located in <wtx install dir>\odbc\books\odbcuser.
The HTML help is located in <wtx install dir>\odbc\html.

You can navigate to the HTML version by opening the help.htm file that is under the html subdirectory.

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


UNIX:
The PDF file (odbcuser.pdf) is located in odbc_drivers/book.
The HTML help is located in odbc_drivers/help.

You can navigate to the HTML version by opening the help.htm file that is under the help subdirectory.

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

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


Installing and configuring IBM-branded ODBC drivers on Windows

To install the IBM-branded ODBC drivers:

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

To configure the ODBC DSN:

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

On 32-bit and 64-bit Microsoft SQL Server Enterprise 2008R2 systems, use the ODBC Administrator to configure the ODBC System DSN. For example, run c:\windows\SysWOW64\odbcad32.exe.


Installing and configuring IBM-branded ODBC drivers on UNIX

To install IBM-branded ODBC drivers:

Select the appropriate ODBC driver option to install. Specific WebSphere Transformation Extender product installations include IBM-branded ODBC drivers for the following operating systems:

UNIX 32-bit:

• AIX®
• Linux®
• Solaris
• HP-UX (Itanium™)

UNIX 64-bit:

• AIX
• Linux
• Solaris
• HP-UX (Itanium)

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


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

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

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


Configuring access to the ODBC DSN

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

1. Start the Database Interface Designer (DID) and create a new or open an existing database query file. A database query file has a .mdq file extension.
2. Define a new database. Click Database > New.
3. For the Database Name setting, enter the name of the database that you are defining.
4. For the "Adapter > Type" setting, select ODBC.
5. For the "Data Source > Database Interface Designer" setting, enter or select the ODBC DSN that you specified in the "To configure the ODBC DSN" procedure on Windows.
6. For the "Data Source > Runtime" setting, enter or select the ODBC DSN that you configured on Windows or UNIX. If the map is run on Windows, enter the ODBC DSN that you configured in the "To configure the ODBC DSN" procedure. If the map is run on UNIX, enter the ODBC DSN that you configured in the "To configure the odbc.ini file to define the ODBC DSN" procedure.
7. Click OK.
8. When you define a database card in the Map Designer, reference the WebSphere Transformation Extender ODBC connection with the following parameters:

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

When you define a database adapter operation in a map rule through the GET, PUT, or DBLOOKUP functions, you can reference the WebSphere Transformation Extender ODBC connection with the following command-line options:

• When you use an MDQ file:




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



• When you do not use an MDQ file:




Command-line options	Definition
-DBTYPE ODBC	Specifies the ODBC type of database.
-SOURCE <data source>	<data source> is the DSN that you used in the "To configure the ODBC DSN" procedure on Windows, and the "To configure the odbc.ini file to define the ODBC DSN" procedure on UNIX.

Installation error: uncompress not found
The WebSphere Transformation Extender installation programs for UNIX operating systems rely on the UNIX "uncompress" program. The "uncompress" program might not be available in some Linux installations. If you encounter the installation error "uncompress: not found," install the "uncompress" program.


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

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

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

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

Execute the command as follows:

. /install_dir/setup

where install_dir is the directory where you installed the WebSphere Transformation Extender products.

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


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

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

Set this value one time for each user (not for each session). Choosing the correct value depends on the following factors:

• Amount of memory available on the machine
• Size of data being processed
• Type of processing occurring on the respective data
• Other major applications that run on the machine

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

ulimit -d <value>

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


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

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

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

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


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


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

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

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


Patch requirement for Red Hat Enterprise Linux on IBM z systems
On computers that run on Red Hat® Enterprise Linux on IBM z systems, you must install the RHEL 5 Server Update 4. Without this update, the Management Console and Launcher Administration trigger a Java exception error.


Microsoft .NET Framework 4.0 requirement
WebSphere Transformation Extender requires .NET Framework 4.0 to register an assembly such as dtxInterop.dll.

1. Download and install .NET Framework 4.0 from http://www.microsoft.com/download/en/details.aspx?id=17851.
2. To ensure that the current dtxCom.dll is registered:

a. Unregister the current dtxCom.dll:
regsvr32 /u dtxCom.dll

b. Register the V8.4 dtxCom.dll:
regsvr32 dtxCom.dll

Now you can use Microsoft .NET Framework 4.0 to register assemblies such as dtxInterop.dll. The regasm utility might require you to run the command prompt with administrator privilege.

Invoke the regasm utility from the Microsoft.NET\Framework directory. For example:
C:\Windows\Microsoft.NET\Framework\v4.0.30319\regasm dtxInterop.dll


Allocating additional virtual memory on Microsoft Windows 32-bit systems
In Windows 32-bit systems, maps that process large amounts of data in memory can fail due to heap fragmentation. You can edit the Windows boot.ini file to allocate additional Windows virtual address space:

1. Edit the Windows boot.ini file and add the /3GB switch. See the example and the editing procedure from Microsoft.
2. Use one of the following methods to make the Launcher or Command Server large-address-aware:
• Request and apply the patch for the Launcher or Command Server from the WebSphere Transformation Extender technical support team.
• Use Microsoft .NET Framework and the EDITBIN command /LARGEADDRESSAWARE option to update the appropriate binary file:

Launcher:
editbin /LARGEADDRESSAWARE mercntsvns.exe
Command Server:
editbin /LARGEADDRESSAWARE dtxcmdsv.exe

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

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

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

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


Configuring Java-based adapters
To configure the Java-based adapters, you modify the CLASSPATH environment variable, either directly or by adding the JAR file entries to the [External Jar Files] section of the dtx.ini file. 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 cannot be used in these entries.

1. (This step is not required for AIX and HP-UX platforms.) Install Java™ 2 SDK, Enterprise Edition (J2EE™) v1.6.0 and set environmental variable J2EE_HOME to point to the installed directory. Update the CLASSPATH environment variable as described below.

Platform	CLASSPATH Environment Variable
Windows	%J2EE_HOME%\lib\j2ee.jar
Sun Solaris	$J2EE_HOME/lib/j2ee.jar

2. The IBM version of Java™ 2 Runtime Environment, Standard Edition v1.6.0 is provided with this release. Make sure the environment variable JAVAHOME points to the installed location of this version of the JRE, and that the CLASSPATH environment variable includes:

%JAVAHOME%\lib

3. For Windows platforms only: Set the PATH environment variable to include the following:

install_dir\java\bin

Where install_dir is the directory where you installed the WebSphere Transformation Extender products.

4. For UNIX systems only: Ensure that the client-side LIBPATH environment variable contains a reference to the directory where Java 2 JRE is installed. This is the directory where the libjvm.s* and libjava.* files are located. For example:

$(JAVAHOME)/jre/bin/classic:$(JAVAHOME)/bin

Platform	Library Path Environment Variable
AIX	LIBPATH
HP-UX	SHLIB_PATH (SHLIB_PATH should point to the hotspot subdirectory instead of classic.)
Sun Solaris	LD_LIBRARY_PATH

Follow any provider-specific installation and setup instructions.


SNMP Adapter and SNMP Agent software requirements
The WebSphere Transformation Extender SNMP Collection is no longer a separate product installation. The SNMP Adapter is automatically included with all base editions of WebSphere Transformation Extender version 8.4 and later. The SNMP Agent is an optionally installed component of WebSphere Transformation Extender with Launcher.

To use the SNMP Adapter or the SNMP Agent, you must install the Java™ Dynamic Management Kit (JDMK) runtime module available from Project OpenDMK.
1. An existing jdmkrt.jar file from a previous installation of the SNMP Collection prevents the version 8.4 SNMP Adapter or SNMP Agent from working. Remove any existing jdmkrt.jar file:

• On Windows systems, from the WTX installation directory.
• On UNIX systems, from the /libs subdirectory.

2. Download and install the OpenDMK binary runtime components from Project OpenDMK.
3. Add the jdmkrt.jar file to the CLASSPATH as described in the Configuring Java-based adapters topic of the Resource Adapters overview.

To use the SNMP adapter from the Design Studio, add the jdmkrt.jar file to the dtx.ini file, as described in the Configuring Java-based adapters topic.


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

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

To install the cicssrvr.loadlib file:

1) Transfer the cicssrvr.loadlib file in binary mode from the
installation directory on your computer to a z/OS data set with
80-byte fixed-length records (RECFM=FB, LRECL=80,
system-determined blksize).

This means no ASCII-to-EBCDIC translation and no
elimination of carriage-return or line-feed characters.

2) After you have installed the file on z/OS, issue the TSO
RECEIVE command to create a load library from it. At the
"READY" prompt, type the following:

receive inda(‘my.upload’)

The following messages are displayed:

INMR901I Dataset MY.UPLOAD from USER on NODENAME
INMR906A Enter restore parameters or 'DELETE' or 'END' +

3) Type the name of the load library to be created as follows:

da('my.loadlib')

Messages are displayed, indicating that the load library is being created.

4) Define the programs to the CICS region that will be
running the CICS Adapter server-side components.

The programs can be defined to CICS by adding the following
statements to the CICS CSD definitions. To update the CSD, use
either the DFHCSDUP CICS batch utility program or use the CEDA
transaction and use the following statements as an example:

DEFINE PROGRAM(DTXC3270)
GROUP(DTXCICS)
DESCRIPTION(3270 BRIDGE EXIT)
LANGUAGE(LE)
DATA(ANY)

DEFINE PROGRAM(DTXCDRIV)
GROUP(DTXCICS)
DESCRIPTION(ADAPTER DRIVER)
LANGUAGE(LE)
DATA(ANY)

5) Add the cicssrvr load library to the DFHRPL concatenation
for the CICS region that will be running the CICS adapter
server-side components.


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

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


MIME Adapter
The MIME adapter requires the j2ee.jar and mail.jar files, or equivalent jar files that contain the J2EE and "javax.mail" classes. These modules are not shipped with WebSphere Transformation Extender. After installing the jar files from an appropriate j2ee installation, modify the CLASSPATH to include the modules.


S/MIME Adapter
WebSphere Transformation Extender supports the S/MIME adapter on Windows and 32-bit non-Windows operating systems. However, it does not support the adapter on HP Itanium operating systems.

If you use the S/MIME adapter on a supported non-Windows operating system, set the SMIMEDIR environment variable and specify a valid path for your environment. For example, set the path as:

CMD: export SMIMEDIR=/sol10t2000home/qalocal/automation/inst32/83SMIME


Oracle and Oracle AQ Adapters
See the WebSphere Transformation Extender system requirements for the supported database versions.

Support for Oracle databases does not include support for the Oracle Exadata platform.


Sybase adapter
With the Sybase adapter, you can connect to the Sybase Adaptive Server Enterprise (ASE) and Sybase IQ databases. See the WebSphere Transformation Extender system requirements for the supported database versions. See the WebSphere Transformation Extender Sybase adapter documentation for the list of supported data types.



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

• WebSphere Transformation Extender version 8.4 requires custom functions that run on Microsoft Windows systems to use the new mpiMemMalloc and mpiMemRealloc memory management functions to allocate or reallocate the lpDataFromApp buffer.

• The implementation of the ZIP adapter on the 32-bit version of Microsoft Windows is different from the implementation on the 64-bit version of Microsoft Windows. The 64-bit implementation is Java-based. The Java-based ZIP adapter uses the same command line options and error messages as the 32-bit adapter.

The 64-bit does not support the "Imploding" type of compression. A client that uses this older type of compression must select a different type of compression.

• Maps, type trees, and systems from versions 5.0 and later can be used with 8.4. 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 recompile and save the maps; otherwise, the processes must convert the files each time they load the files.

• If you are migrating from 8.0 to 8.4, you must run your database triggering scripts in order to successfully run source-triggered database systems. After version 8.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 reference different names.

• 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, open with this version (8.4).

• 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.4, 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, use Map Designer to complete the conversion process:

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

New executable aliases
Some executables have new aliases. The executable in version 8.4 is identical to the executable in earlier versions. Update any script files that call the following old executable file names to call the new alias:

Old executable name	New alias
dsany2xml	dtxany2xml
dsmapconv	dtxmapconv
dstx	dtxcmdsv
dstxpage	dtxpage
dstxprof	dtxprof
dstxver	dtxver
dsxsdexport	dtxxsdexport
mercnt	dtxcmdsv
mercver	dtxver

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. After conversion, the format of the map source has changed and there are added features that are not supported in the earlier versions.

• *.mtt files are converted in memory when the file is opened. The backup *.omt file is created when the file is saved.
• *.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 dynamically.
• *.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 open in the current version.

Preparing maps to run in this version

• Analyze each type tree file for logic and structure and then save it in the current version of the Type Designer.

• Regenerate type trees for queries, tables, and stored procedures.

• For maps that will be executed using a current version of the Command Server or Launcher, build all maps using the equivalent (current) version of the Map Designer.

• Build and generate the Launcher system (.msl) file or the command file for all systems defined in the current version of the Integration Flow Designer.

• Change any script file that uses the unsupported "lci -start" and "lci -stop" features to start and stop the UNIX Launchers to the supported commands, as follows:

Unsupported Command	Supported Command
lci -start	launcher.sh -start
lci -stop	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 must 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 you open a map that references a custom adapter or an adapter that is no longer supported in version 8.4, the Source or Target in the Edit Card dialog is blank. The map builds successfully, but returns a "Source not available" or "Target not available" message when it executes. The solution is to select an adapter from the list in the Edit Card dialog.

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


Performance of maps
If you are migrating from an earlier version, you should be aware of the relative performance of running maps in this version.
See http://www.ibm.com/support/docview.wss?uid=swg21431170.



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

For the latest documentation updates and for information about known problems and workarounds in Version 8.4, go to http://www.ibm.com/support/docview.wss?&uid=swg21570416.



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

For an overview of new features in this release, see the What's New information in the information center.

IBM Support Assistant Lite for WebSphere Transformation Extender V8.4
IBM Support Assistant Lite (ISA Lite) for WebSphere Transformation Extender V8.4 collects diagnostic files such as log files and configuration files for problem diagnosis. Download ISA Lite for WebSphere Transformation Extender V8.4 to simplify later collection of troubleshooting data.

New platform support
All WebSphere Transformation Extender components are supported on 32-bit and 64-bit Itanium operating systems.

Removed platform support
WebSphere Transformation Extender Version 8.4 is not supported on HP-UX on PA-RISC systems.


Default idle time for adapters
The dtx.ini file now sets a default idle time for most adapters, which you can override as required.

The Connection Manager shuts down the idle thread gracefully when running under a Launcher or Command Server. In an API environment that invokes maps that use Java-based adapters (such as JMS, Java Class, and JALE), you might wait additional idle seconds after a shutdown request. This delay occurs only when the custom application does not explicitly shut down WebSphere Transformation Extender by using the Java-based "terminateAPI" routine or the C-based "mpiTermAPI" routine.


Map override capability is removed from the Command Server map menu
The Setup option to override map settings is removed from the Command Server map menu. Use the Map Designer to override the map settings. In Design Studio, right-click an executable map and click Map Settings.

The execution commands that override map settings in a batch environment are not affected.





Custom function memory management changes
WebSphere Transformation Extender version 8.4 requires custom functions (including the EXIT function) that run on Microsoft Windows systems to use new memory management functions:

• In the code for a WebSphere Transformation Extender custom function, use the C programming language malloc and free runtime functions instead of the Microsoft Visual Studio GlobalAllocPtr and GlobalFreePtr macros.

• Use the following new WebSphere Transformation Extender programming interface functions to allocate the lpDataFromApp buffer:
• mpiMemMalloc
• mpiMemRealloc
• mpiMemFree

RUN function now returns code 56 for invalid options
In earlier releases, the RUN function returned an empty string if you specified an option that is not valid for the RUN function. When you specify an invalid option in WebSphere Transformation Extender version 8.4, the RUN function returns code 56 "Invalid command line error."


Deprecated components and functions

• Microsoft SQL Server Adapter -DBTYPE MSSQLSVR7 command

The command line option for specifying the use of the Microsoft SQL Server Adapter has changed from "-DBTYPE MSSQLSVR7" to "-DBTYPE SQLSVR". The "MSSQLSVR7" designation is now deprecated but is currently supported and handled as though "SQLSVR" was specified.

Removed components and functions
The following components and functions were deprecated in earlier releases and are not included in Version 8.4:

• Base64 adapter
• BEA Tuxedo adapter
• FS Manager adapter
• Quoted Printable adapter
• VAN adapter
• VMware Server

Disregard any references to these components in the documentation.


Mapping data objects from one output card to another
In earlier versions of the WebSphere Transformation Extender Map Designer, to map data objects from one output card to another output card, you could press the ALT key and drag the object into the new destination. The WebSphere Transformation Extender 8.3 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.


Improved error message for missing XML schema
At run time, a missing schema generates the error message "XML Parser: Invalid metadata location" when the schema is used as a type tree or as type-tree metadata, or when the schema is referenced from another schema that is being used. In WebSphere Transformation Extender version 8.4, the message is displayed in the map status message and logged in the audit log, as well as being logged in the trace log and the XML error log.


Example files installation
The WebSphere Transformation Extender Design Studio product no longer includes example files in the Typical installation, but instead, it includes them in the Custom installation. See Installing the example files.


SNMP Agent tracing
When you run the SNMP Agent on UNIX operating systems with tracing enabled, log information about the Launcher and associated map events is not only output to a file, but also output to the standard output console.

To disable the logging of messages to the output console, modify the logging.properties file in the following way:

1. Open the logging.properties file, which is located under the java/lib subdirectory of the path where WebSphere Transformation Extender is installed.
2. Set the following entry to OFF and then save the file:
   java.util.logging.ConsoleHandler.level = OFF

Results:
When you run the SNMP Agent with the java.util.logging.ConsoleHandler.level set to OFF, the log information is no longer output to the console screen; it is only output to the log file.



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

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



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

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


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

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

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

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

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


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

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


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

DTX_TMP_DIR=install_dir/tmp
export DTX_TMP_DIR

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

chmod 777 $DTX_TMP_DIR


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

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


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

DTX_DEBUG=TRUE
export DTX_DEBUG

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

DTX_DEBUG=FALSE
export DTX_DEBUG

The following is a sample of the information contained in the environmental debug file:

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

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

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


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

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

LIBPATH=$LIBPATH: install_dir/libs
export LIBPATH

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

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

SHLIB_PATH=$SHLIB_PATH: install_dir/libs
export SHLIB_PATH

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

LD_LIBRARY_PATH=$LD_LIBRARY_PATH: install_dir/libs
export LD_LIBRARY_PATH

Note: In these examples, install_dir/libs is the directory where the shared libraries are located.



=====================================================================
8. SOFTWARE DEVELOPMENT KIT NOTES
=====================================================================
When installing Design Studio, select Custom Install to install the Software Development Kit components.

Any base version of WebSphere Transformation Extender can be used as the runtime environment with the Software Development Kit:

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

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.


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.

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

Files	Windows Directory	UNIX Directory
Headers	install_dir	$install_dir/src
Library	install_dir	$install_dir/libs
IDLs	install_dir\idl	$install_dir/idl
Schemas	install_dir	$install_dir/src

Linking an application to an alternate ICU library version
This release of WebSphere Transformation Extender uses ICU version 4.8.

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

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

-licuuc341 licuuc18n341 licudata341

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

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

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

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

-licui18n341 -licuuc341 -licudata341




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

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


Non-Windows environments

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


Configuration requirements
To use these products in a non-Windows environments, the X Window server must be running on the local host machine or system. You must set the DISPLAY environment variable and export it.

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

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


• The DISPLAY environment variable name must be in uppercase letters.

• The display_name is the IP address or domain name of the local host machine that is to display the X Window WTX GUI client application.

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

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

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

Example 1:

export DISPLAY=mycomputer.ibm.com:0

Where:

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

The host system exports the value to the X Window client so that it will display the X Window 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

Where:

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

The host system exports the value to the X Window client so that it will display the X Window 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 display errors related to font.properties when starting the Launcher Administration, Management Console, or Resource Registry, ensure that the display X server has access to all fonts used in the font.properties of the Java installation.

On Solaris JVMs, the font.properties consistently refer to fonts that are not included with Exceed. This can sometimes cause problems such as distortions when displaying GUIs. To resolve this problem, a customized font.properties can be placed in your $HOME/lib directory, which will remove references to the problem fonts.



=====================================================================
10. CONTACTING CUSTOMER SUPPORT
=====================================================================

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



=====================================================================
11. NOTICES AND TRADEMARKS
=====================================================================
Notices
This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this 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 character set (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan Ltd.
1623-14, Shimotsuruma, Yamato-shi
Kanagawa 242-8502 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
J46A/G4
555 Bailey Avenue
San Jose, CA 95141-1003
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, and 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. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample 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
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml.

• Intel, Intel logo,and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.
• Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.
• Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
• Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both.
• UNIX is a registered trademark of The Open Group in the United States and other countries.

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