IBM WebSphere® Transformation Extender, Version 8.1, Service Pack 1 Release Notes (rev. 4) © Copyright IBM Corporation 2006. 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. 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 6. Software Development Kit Notes For the following products: - IBM WebSphere Transformation Extender - IBM WebSphere Transformation Extender SDK 7. Launcher Studio Notes For the following product: - IBM WebSphere Transformation Extender Launcher Studio 8. Contacting customer support 9. Notices and trademarks ===================================================================== 1. ABOUT THIS RELEASE ===================================================================== This release, while considered the first service pack for release 8.1, is a full version of the product. If you have release 8.1(84), you must completely uninstall it before installing this release - 8.1(114). However, this release can coexist on the same computer as older releases of the product, starting from release 8.0. The new features in this release are listed in the documentation under "What's New". 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 - IBM WebSphere Transformation Extender SDK Java runtime environment (JRE) ------------------------------ WebSphere Transformation Extender 8.1 is installed with and supports the IBM version of Java(TM) 2 Runtime Environment, Standard Edition, Version 1.4.2. We recommend that you use the included JRE. If you configure your WebSphere Transformation Extender product installation to a different JRE, it must be the same level as the included version. ===================================================================== 2. INSTALLATION AND CONFIGURATION INFORMATION ===================================================================== Installation error: uncompress not found ---------------------------------------- [EC103417] 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. Path location for the response files ------------------------------------ [EC77052] 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 --------------------------------------- [EC76944] 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 canceled the dialog before you made your language selection and the Installer GUI has stopped responding, exit the Installer GUI and then restart it. Configuring UNIX environment variables -------------------------------------- The environment variables required to execute an WebSphere Transformation Extender map or system must be set prior to execution. You can set the environment variables (PATH, DTX_TMP_DIR, DTX_HOME_DIR, and the appropriate library path variable for your platform) by running the setup program. After you log on to your computer, execute the setup program in the WebSphere Transformation Extender installation directory before executing a map or system file (using the Launcher). This sets the required environment variables for this session only. Modify the .profile script to set the environment variables for all sessions. Note: The following command procedure assumes that your UNIX command line environment is the Korn (ksh) shell. Execute the command as follows: . /install_dir/setup where install_dir represents the directory in which you have installed your WebSphere Transformation Extender products. Note: There must be a space between the initial period (.) and the command path. Soft DATA Segment or Heap Size on UNIX systems ------------------------------------------------ Using the default setting for the Soft DATA segment or heap size parameter can cause problems on UNIX platforms. This Soft DATA Segment value should be reset to a value larger than the default by the root user. Note: On AIX platforms, use IBM's Smit (System Management Interface Tool) utility to reset the Soft DATA Segment value. Set this value one time for each user (not for each session). Choosing the correct value depends on the following factors: - amount of memory available on the machine - size of data being processed - type of processing occurring on the respective data - other major applications that may 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 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++ run-time environment component for AIX 5 (xlC.aix50.rte run-time package), you must install the 7.0.0.3 maintenance level in order to use the WebSphere Transformation Extender software on AIX platforms. To install the xlC.aix50.rte 7.0.0.3 maintenance level, download it from the following URL: http://www-1.ibm.com/support/docview.wss?rs=32&con%20text= SSEP5D&dc=D400&uid=swg24008966&loc=en_US&cs=u Running the maxdata script on AIX platforms ------------------------------------------- The maxdata script is provided to increase the maximum values for memory availability on your AIX system. Run the maxdata script prior to executing any WebSphere Transformation Extender maps. The script requires a 777 permission level. Run the script only once for each respective executable and run it on the respective executable(s) whenever the executable gets updated or replaced during the installation of a patch or update. Sun Solaris product requirements -------------------------------- WebSphere Transformation Extender products that run on Sun Solaris platforms require certain patches be installed. To resolve a failure to listen on TCP sockets, install the Patch Cluster or install the following patches: 105529-03 /kernel/drv/tcp patch 105214-01 /kernel/fs/sockfs patch (contract customers only) 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 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 and Quality Pack: CORBA Adapter Java Class Adapter Java Message Service (JMS) Adapter JNDI Adapter The URL for these patches on the Hewlett-Packard Web site is: http://www.hp.com/products1/unix/java/java2/sdkrte14/downloads/ index_pa-risc.html If you are using HP-UX version 11.11, the following patch is required to run any of the above-mentioned, Java-based adapters: PHSS_28871 Configuring Java-based adapters ------------------------------- The instructions below require you to modify the CLASSPATH environment variable. This can be done directly, or by adding the JAR files to the dtx.ini file. To do so, add entries to the [External Jar Files] section. For example: [External Jar Files] jarN=c:\mypath\myjar.jar Note: N represents the next available number if multiple jar entries exist. For example: [External Jar Files] jar1=c:\J2EE\lib\j2ee.jar jar2=c:\mypath\myjar.jar Note: Environment variables can not be used in these entries. 1) (This step is not necessary for AIX and HP-UX platforms.) Install Java 2 SDK, Enterprise Edition (J2EE (TM)) v1.4.2 and set environmental variable J2EE_HOME to point to the installed directory. Update the CLASSPATH environment variable as described below. For Windows: %J2EE_HOME%\lib\j2ee.jar For Sun Solaris: $J2EE_HOME/lib/j2ee.jar 2) The IBM version of Java 2 Runtime Environment, Standard Edition v1.4.2 is provided with this release. Make sure the environment variable JAVAHOME points to the installed location of this version of the JRE, and that the CLASSPATH environment variable includes: %JAVAHOME%\lib 3) For Windows platforms only: Set the PATH environment variable to include the following: install_dir\java\bin where install_dir represents the directory in which you have installed your WebSphere Transformation Extender products. 4) For UNIX systems only: Ensure that the client-side LIBPATH environment variable contains a reference to the directory in which Java 2 JRE is installed. Specifically, this is the directory in which the libjvm.s* and libjava.* files are located. For example: $(JAVAHOME)/jre/bin/classic:$(JAVAHOME)/bin Library path environment variables: HP-UX: SHLIB_PATH (SHLIB_PATH should point to the hotspot subdirectory instead of classic.) Sun Solaris: LD_LIBRARY_PATH AIX: LIBPATH Follow any provider-specific installation and setup instructions. CICS Adapter ------------ The CICS adapter requires the cicssrvr.loadlib file that is shipped with WebSphere Transformation Extender and is located in the installation directory. The cicssrvr.loadlib file includes server-side components required to use the CICS adapter to connect to CICS. To install it, follow these instructions: 1) Transfer the cicssrvr.loadlib file in binary mode from the installation directory on your computer to a z/OS data set with 80 byte fixed-length records (RECFM=FB, LRECL=80, system-determined blksize). This means no ASCII-to-EBCDIC translation and no elimination of carriage-return or line-feed characters. 2) After you have installed the file on z/OS, issue the TSO RECEIVE command to create a load library from it. At the "READY" prompt, type the following: receive inda(‘my.upload’) The following messages are displayed: INMR901I Dataset MY.UPLOAD from USER on NODENAME INMR906A Enter restore parameters or 'DELETE' or 'END' + 3) Type the name of the load library to be created as follows: da('my.loadlib') Messages are displayed, indicating that the load library is being created. 4) Define the programs to the CICS region that will be running the CICS Adapter server-side components. The programs can be defined to CICS by adding the following statements to the CICS CSD definitions. To update the CSD, use either the DFHCSDUP CICS batch utility program or use the CEDA transaction and use the following statements as an example: DEFINE PROGRAM(DTXC3270) GROUP(DTXCICS) DESCRIPTION(3270 BRIDGE EXIT) LANGUAGE(LE) DATA(ANY) DEFINE PROGRAM(DTXCDRIV) GROUP(DTXCICS) DESCRIPTION(ADAPTER DRIVER) LANGUAGE(LE) DATA(ANY) 5) Add the cicssrvr load library to the DFHRPL concatenation for the CICS region that will be running the CICS adapter server-side components. DB2 Adapter (UNIX) ------------------ [EC54202] If you are using the AIX DB2 Adapter, you must have the DB2 client version 8.1 fix pack 3 or later installed on the client computer. Java Class Adapter ------------------ [EC95495] 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 file (or another jar file containing the J2EE classes) that is no longer shipped with WebSphere Transformation Extender. Oracle and Oracle AQ Adapters ----------------------------- Only Oracle database and Oracle AQ versions 9i and 10g are supported in this release. Oracle database and Oracle AQ adapter library files for version 9i are installed by default and are referred to as the "base" product. However, both 9i and 10g libraries are provided in the product installation directory. To use 10g, rename the 10g library file (for example, m4ora10g.dll) to the "base" library file name (for example, m4ora.dll). Oracle database adapter "base" library files: - m4ora.dll (Windows) - libm4ora.so(.sl) (UNIX) Oracle AQ adapter "base" library files: - m4aq.dll (Windows) - libm4aq.so(.sl) (UNIX) After the installation process completes, use the following platform-specific instructions to rename a versioned library file (10g in this case) to the base library file. UNIX ---- 1) Change the directory to install_dir/libs. 2) Copy the applicable Oracle library file for "backup" purposes: - For the Oracle database adapter, make a copy of libm4ora.so(.sl). - For the Oracle AQ adapter, make a copy of libm4aq.so(.sl). 3) In the installation directory, locate the 10g library file and rename it to be the base library file: - For the Oracle database adapter, rename libm4ora10g.so(.sl) to libm4ora.so(.sl). - For the Oracle AQ adapter, rename libm4aq10g.so(.sl) to libm4aq.so(.sl). 4) Move the renamed library file to libs directory. Note: To revert back to 9i, you can repeat the same process using the additional 9i libraries that were installed with the product. For example, rename libm4aq9i.so(.sl) to libm4aq.so(.sl). Windows ------- 1) Go to the product installation directory. 2) Copy the applicable Oracle library file for "backup" purposes: - For the Oracle database adapter, make a copy of m4ora.dll. - For the Oracle AQ adapter, make a copy of m4aq.dll. 3) In the installation directory, locate the 10g library file and rename it to be the base library file: - For the Oracle database Adapter, rename m4ora10g.dll to m4ora.dll. - For the Oracle AQ adapter, rename m4aq10g.dll to m4aq.dll. To revert back to 9i, you can repeat the same process using the additional 9i libraries that were installed with the product. For example, rename m4ora9i.dll to m4ora.dll. When you use Oracle database and AQ adapters together in the same system, their Oracle client versions (9i or 10g) must match and also be for the same version of Oracle that is installed on the server. For example, if Oracle 10g is installed on your server, and you want to use both the Oracle database adapter and the Oracle AQ Adapter in the maps in your system, you must use the 10g version for both adapters. You cannot use a 9i Oracle database adapter with a 10g Oracle AQ adapter in this case. They must both be the 10g version. VAN Adapter ----------- Scripts for the VAN adapter are located in: install_dir\examples\adapters\van\scripts The VAN adapter installation requires that a current version of Cleo A+ must already be installed. The adapter has been successfully tested with Cleo A+ Version v2.36.03 on the Windows platform and v3.17.20 on the UNIX platform. Customers installing the VAN Adapter for the first time should contact CLEO Communications and order Cleo A+ for Windows. CLEO Communications Sales Department 4203 Galleria Drive Loves Park, IL 61111 Phone: 800.233.2536, x 2693 Fax: 815.654.8294 Email: SalesIL@cleo.com Web Site: http://www.cleo.com/ Customers upgrading from an earlier version of the VAN adapter should also contact CLEO directly, according to the contact information above, to order an upgrade from the earlier version of Cleo A+ provided with the VAN adapter. When ordering your upgrade, you must provide the serial number from your original Cleo A+ software. ===================================================================== 3. UPGRADE AND MIGRATION INFORMATION ===================================================================== - [EC92680] Maps and system files from version 5.0 are not compatible with version 8.1. To use your systems and maps from version 5.0 in this release, you must regenerate them. - [EC97190] If you are migrating from 8.0 to 8.1, you must run your database triggering scripts in order to successfully run source-triggered database systems. After version 8.1 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. - [EC92916] 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.1). 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 allow *.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 re-generated. They are converted on-the-fly. - *.mmc files do not need to be recompiled. - *.msd files still work the same way, creating an *.osd when the file is opened. - *.mdq files should still open in the current version. Recommendations for preparing maps to run in this version --------------------------------------------------------- - Analyze each type tree file for logic and structure and then save it in the current version of the Type Designer. - Regenerate type trees for queries, tables, and stored procedures. - For maps that will be executed using a current version of the Command Server or Launcher, build all maps using the equivalent (current) version of the Map Designer. - Build and generate the Launcher system (.msl) file or the command file for all systems defined in the current version of the Integration Flow Designer. - If you are upgrading from an earlier version of the UNIX Launcher (formerly known as the Event Server) in which you used a script file containing the unsupported "lci -start" and "lci -stop" features to start and stop your UNIX Launchers, note that these commands have been replaced by a fully supported and documented feature of the Management Console. You must change your existing scripts using lci as follows: To start the Launcher: FROM: TO: lci -start launcher.sh -start To stop the Launcher: FROM: TO: lci -stop launcher.sh -stop where: is the number of the first designated listening port in the range specified in the LauncherAdmin.bin file. The default value is "5015" and it is not required for the -start option. However, if it is provided, it should match the first listening port specified in the LauncherAdmin.bin file. - If you have designed maps that could produce 0 bytes of data to an adapter (this is especially critical for R/3 adapters), you must change the OnSuccess setting to CreateOnContent or use the -XO adapter option. - When opening a map in this version that was created in an earlier version that still references a custom adapter or an adapter that is no longer supported, the Source or Target in the Edit Card dialog will be blank. The map will still build successfully, but will result in a "Source not available" or "Target not available" message when executed. The solution is to select an adapter from the list in the Edit Card dialog. Converting type trees generated in earlier versions --------------------------------------------------- You can use the XML Type Tree Compatibility utility wizard (invoked from the Type Designer) and the dsxmlconv utility command (invoked from the command line) to convert type trees that were generated in WebSphere Transformation Extender versions 6.7, SP1, SP2, and 7.0. ===================================================================== 4. KNOWN LIMITATIONS, PROBLEMS, AND WORKAROUNDS ===================================================================== Number elements with length --------------------------- [EC109308] There is a known issue with number elements that can occur after importing an XML Schema that contains a nillable element. When using the generated XML type tree, the validation map might run successfully, however, the generated XML output is invalid for the Schema. To work around this issue, modify the generated XML type tree by changing the element type (Item Subclass property) from Number to Text for the elements that contain a nillable element. BEA Tuxedo Adapter temporarily unavailable ------------------------------------------ Due to BEA licensing issues, the BEA Tuxedo Adapter is not available in this release of WebSphere Transformation Extender. Map Designer ------------ [EC76088] The use of IN on a single object in the DataAudit settings causes the Map Designer to stop responding. [EC95727] Due to a problem with 3rd party software, the "Other" selection button for creating custom breakpoint colors for the Map Debugger is not keyboard accessible. Resource Registry ----------------- [EC99744] 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. SNMP Collection temporarily unavailable ------------------------------------------ [EC101622] Due to licensing issues, the SNMP Collection is not available in this release of WebSphere Transformation Extender. PACKAGE function change ----------------------- [EC103974] 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. 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 ------------------------------------------------------------------- [EC105608] There is a known issue with the Oracle 9i Client and Oracle 10g Client libraries that occurs when both an Oracle Client Library and a DB2 Client library are present. Because of the Oracle Client library issue, the following problems could occur with your WebSphere Transformation Extender maps: - When both the DB2 Adapter and Oracle Adapter are used in a map, the map fails (crashes). - When both the DB2 Client and Oracle Client libraries are loaded, a failure (crash) occurs when the map attempts to connect to the Oracle database. To work around this issue, you can regenerate the Oracle Client library using the -Bsymbolic link option or contact Oracle for fix information. ===================================================================== 5. 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 This section contains the following topics: - Installation Information - Additional UNIX Run-Time Information - Set Location for Temporary Files (DTX_TMP_DIR) Installation Information ------------------------ Because procedures for Command Servers for Windows, HP-UX, RS/6000 AIX, and Solaris platforms might differ slightly, specific instructions are provided during the installation program to guide you. The Command Servers for Microsoft Windows are components of the Client install and are installed with the IBM WebSphere Transformation Extender with Command Server and IBM WebSphere Transformation Extender with Launcher. These Command Servers are also available as components of the Command Server install for Windows-based platforms to be installed on your server for run-time purposes. The ability to run maps at design time is provided with the IBM WebSphere Transformation Extender Design Studio install, but only from inside the Map Designer. The HP-UX, RS/6000 AIX, and Solaris Command Servers are available as components of each platform-specific Command Server install to be installed on your server for run-time 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 Run-Time Information ------------------------------------ You must also manually set the shared library path according to your platform. If you are going to configure the environment variables manually, do not execute the setup program; refer to the following section, Set Location for Temporary Files (DTX_TMP_DIR), for instructions. Set Location for Temporary Files (DTX_TMP_DIR) ---------------------------------------------- During map execution, the Command Server creates temporary files for resource handling purposes and for retaining debug information. The default directory for these temporary files is /tmp. However, you can specify the directory where you want these files to be kept by setting the DTX_TMP_DIR environment variable. For example: DTX_TMP_DIR=install_dir/tmp export DTX_TMP_DIR Note: If you choose to allow multiple groups to access the Command Server engine, the directory specified for DTX_TMP_DIR requires permission 777 to provide permission to the user, the group, and all others. To accomplish this, run the chmod command: chmod 777 $DTX_TMP_DIR In addition, for multiple users or groups, define a DTX_TMP_DIR instead of letting it default to /tmp. This DTX_TMP_DIR variable must be defined and exported prior to running the chmod command. The DTX_TMP_DIR variable is defined and exported by the user or with the setup script. Environmental Debug Information (DTX_DEBUG) ------------------------------------------- If a problem is encountered during map execution and the DTX_DEBUG environment variable had been defined, the Command Server can produce environmental debug information that can be helpful when determining the cause of the problem. When you define the DTX_DEBUG environment variable, environmental debug information is recorded in a file named dtxinfo.log located in the directory defined by the DTX_TMP_DIR environment variable (which is the /tmp directory if DTX_TMP_DIR is not defined). By default, the DTX_DEBUG environment variable is not defined and environmental debug information is not recorded. Enabling Environmental Debug ---------------------------- To enable the environmental debug facility, set the DTX_DEBUG environment variable to TRUE. For example: DTX_DEBUG=TRUE export DTX_DEBUG The information recorded in the dtxinfo.log file provides information that can be useful when troubleshooting a specific map. The following is a sample of the information contained in the environmental debug file: PROCESS_ID: 2309, API_REF: 1 Date/Time: Fri Jul 25 14:30:09.279783 2003 FILE: mercmain.c, line: 714 info: [IBM WebSphere Transformation Extender Product Version: 0.0] PROCESS_ID: 2309, API_REF: 1 Date/Time: Fri Jul 25 14:30:09.280252 2003 FILE: mercmain.c, line: 744 info: [IBM WebSphere Transformation Extender RUNNING: Fri Jul 25 14:30:09 2003] PROCESS_ID: 2309, API_REF: 1 Date/Time: Fri Jul 25 14:30:09.470357 2003 FILE: mercrun.c, line: 1951 New Map File - Fri Jul 25 14:30:09 2003 [/install_dir/examples/general/map/sinkmap/sinkmap.mmc] Disabling Environmental Debug ----------------------------- To disable the environmental debug facility, set the DTX_DEBUG environment variable to FALSE. For example, you might type: DTX_DEBUG=FALSE export DTX_DEBUG File Locking (DTX_FILE_LOCKING) -------------------------------- The file locking facilities allow two or more mapping processes or threads to write to the same output file or files in a controlled manner. These files include not only output files, but also work files, audit log files, and trace files. By default, file locking is enabled and the Command Server for UNIX uses file locking. Enabling File Locking --------------------- File locking is enabled by default; that is, DTX_FILE_LOCKING environment variable is set to TRUE or is not defined. To enable file locking, set the DTX_FILE_LOCKING environment variable to TRUE. For example: DTX_FILE_LOCKING=TRUE export DTX_FILE_LOCKING Note: To use file locking, the DTX_TMP_DIR environment variable must be set to a common directory for all instances where maps are using common output files. Disabling File Locking ---------------------- To disable the file locking facility, set the DTX_FILE_LOCKING environment variable to FALSE. For example: DTX_FILE_LOCKING=FALSE export DTX_FILE_LOCKING Note: If you do not want to use file locking, and the DTX_FILE_LOCKING environment variable is not defined, you must set DTX_TMP_DIR to unique directory paths for each mapping process. Configuring the Map Execution Environment ----------------------------------------- Because file locking applies to all files to which were written during map execution, configure your map settings or use the appropriate execution commands to support it. Examples include: - A map's output files can be managed using the Retry setting or execution command (the Rc: i option within the -Ofx command). - The work files, audit log, and trace files can be managed through the MapAudit, MapTrace and WorkSpace settings or using the execution command (-Yc: i). - Another option for work files and audit log files is to specify the use of unique file names. Set the MapAudit and WorkSpace > FilePrefix settings to Unique or specify this option using the corresponding execution command ( WU and -AU). Note: Because trace files do not have an option for using unique file names, they can be managed only through the use of the map retry for non-data files execution command (-Y). For information about specifying these settings and execution commands, see the Map Designer and the Execution Commands documentation. Setting Shared Libraries Environment Variables ---------------------------------------------- After you have installed mapping components on UNIX platforms, set the appropriate shared object path environment variable to access the shared libraries. This procedure varies slightly depending on the platform being used. For example, to set this variable for an IBM RS/6000 AIX platform, enter the following: LIBPATH=$LIBPATH: install_dir/libs export LIBPATH Note: The RS/6000 AIX platform caches shared libraries. This means if you update a shared library on the disk, you will not be able to see the update. Use the slibclean command at user root to remove the old shared library from system memory. To set this variable for an HP-UX platform, enter the following: SHLIB_PATH=$SHLIBPATH: install_dir/libs export SHLIB_PATH To set this variable for Solaris platform, enter the following: LD_LIBRARY_PATH=$LD_LIBRARY_PATH: install_dir/libs export LD_LIBRARY_PATH Note: These examples show install_dir/libs as the directory where the shared libraries are located. ===================================================================== 6. SOFTWARE DEVELOPMENT KIT NOTES ===================================================================== These notes are for the Software Development Kit component of the following products: - IBM WebSphere Transformation Extender - 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 - Running Multiple Versions On The Same Computer 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 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 Integration For Java Product Requirements ----------------------------------------- To create map and type tree components for the IBM WebSphere Transformation Extender Integration for Java 8.1 product, IBM WebSphere Transformation Extender Design Studio 8.1 is also required. IBM WebSphere Transformation Extender 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 may 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 installation directory Note: Servlet Integrator users must download the J2EE 1.4.2 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 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.4.2_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 7.5. ===================================================================== 7. 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. This section contains the following topics: - Launcher Administration, Management Console, and Resource Registry - Display Errors Launcher Administration, Management Console, and Resource Registry ------------------------------------------------------------------ Display Errors -------------- To avoid seeing display errors related to font.properties when starting the Launcher Administration, Management Console, or Resource Registry, ensure that the display X server has access to all fonts used in the font.properties of the Java installation. On Solaris JVMs, the font.properties consistently refer to fonts not included with Exceed. This can sometimes cause havoc when displaying GUIs (for example, distortions and so on). To resolve this, a customized font.properties can be placed in your $HOME/lib directory. This will remove references to the offending fonts. ===================================================================== 8. CONTACTING CUSTOMER SUPPORT ===================================================================== Contact Customer Support at 1-800-IBM-SERV or from the product page of the IBM Web site: www.ibm.com/software/integration/wtx ===================================================================== 9. 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.1