IBM Lotus Enterprise Integrator for Domino (LEI) Release 6.5.2 JUne 29, 2004 A) What's New in LEI Release 6.5.2 B) System Requirements C) Installation and Migration Considerations D) Installing LEI - General Instructions E) Uninstalling LEI F) Operational Considerations G) What's Been Fixed in LEI Release 6.5.2 H) Documentation Errata I) Troubleshooting and Additional Support _______________________________________________________________________________ A) What's New in LEI Release 6.5.2 For the latest information about Enterprise Integration offerings, visit the http://www.lotus.com/ei Web site or the LDD http:/www.lotus.com/ldd Web site. LEI Release 6.5.2 is a point release to the major LEI 6.5 release. If you are new to the 6.5x stream, please also see the version 6.5 and 6.5.1 readme.txt at the LDD http://www.lotus.com/ldd Documentation Library. - Additional migration tool option You can now choose to migrate your LEI 3.x activities with their existing scheduling option (enabled or disabled) intact or, alternatively, to disable the scheduling option for all activities that are migrated. This option now appears during the migration process. - DataDirect driver availability The Lotus-branded DataDirect drivers are available for download on IBM Passport Advantage for licensed LEI users at the following URL: http://www-306.ibm.com/software/howtobuy/passportadvantage/ - iSeries installer product ID requirement (5799PTL): Before you can install LEI on a V5R3 or later iSeries platform, the iSeries product ID 5799-PTL must be installed. You can download that product from the "IBM eServer iSeries Tools for Developers" (5799-PTL) Web site at the following address: http://www-1.ibm.com/servers/enable/site/porting/tools - iSeries PTF requirements The Java PTF group number requirements are listed below: -- SF99269 is the required PTF group for V5R3 installations. -- SF99169 is the required PTF group for V5R2 installations. -- SF99069 is the required PTF group for V5R1 installations. - iSeries LEI installer The LEI installer now checks which OS400 version is installed on your system. If you are running V5R3, it uses a slightly modified installation procedure. If you are running pre-V5R3, the installation procedure is identical to previous releases. See the LEI installation guide for details. You can use the WRKPTFGRP command on V5R2 and V5R3 iSeries systems to determine what PTF groups are installed, specifically the Java PTF Group. B) System Requirements For complete details see the LEI Installation Guide. *Hardware Requirements* - 40MB disk space on Win32 - 80MB disk space on UNIX and iSeries (or OS/400) - 90MB temp space on Win32 - required by iSeries LEI Installer - 15MB temp space on Win32 - required by LEI installer - 90MB temp space on UNIX - required by LEI installer *Operating Systems and Versions* LEI 6.5.2 is supported on the following platforms - Windows NT 4 SP6a, 2000, and 2003 - AIX 4.3.3, 5.1, and 5.2 - Solaris 2.8 and 2.9 - Linux Red Hat 7.2 and United Linux v1.0 - OS400 V5R1, V5R2, and V5R3 Read all Domino documentation regarding the specific patches Domino requires for its server. The patch level required by Domino is a prerequisite for successful LEI installation. Patch requirements are updated periodically. See the Domino documentation for details. For example, the correct Solaris patch cluster is required. See IBM Technote 175748 for description of known issues for Windows NT 4.0 service pack 6a. *Software Requirements* LEI Release 6.5.2 requires Notes/Domino 6.0.4 or Notes/Domino 6.5.2. - Notes 6 client to administer the LEI Administrator database A 6.0.4 or 6.5.2 Notes client is required if LEI is installed on a Notes client. - Domino 6.5.2 or 6.0.4 server to manage the LEI Administrator database and run the LEI server if LEI is installed on a Domino server - Client libraries of the external systems to be accessed must be installed on the LEI server and the Domino server. When running activities, if the LEI server and the Domino server are on separate machines, the client libraries must be installed on both machines. - For UNIX - X Window system server environment - For UNIX - X Window system client libraries *** Verify that all of your database software is current with all available maintenance releases and/or fix packs. *Testing Connectivity* - The supplied DCTEST program tests connectivity from the system on which the LEI server is installed to external data sources. The LEI server acts as a client to your external data server. - Run the appropriate connectivity test program from the Domino server before running LEI. The program names are listed below by platform: Issue the following command for Windows (NT, 2000, 2003): ndctest Issue the following command for UNIX (AIX, Linux, and Solaris): dctest Issue the following command for iSeries: RUNDOMCMD SERVER(your_dom_server) CMD(CALL PGM(QDOMINOxxx/DCTEST)) BATCH(*NO) where xxx is the Domino release (6.5.2 for Domino 6.5.2 or 6.0.4 for Domino 6.0.4) A command window help menu appears that provides information for using the connectivity test program. C) Installation and Migration Considerations See the Installation Guide (leiig.nsf) supplied with LEI and also available as both a .nsf file and an HTML browseable at the LDD Documentation library (http://www.lotus.com/ldd) on the Enterprise Integrator product page for complete LEI installation and migration instructions. See below for related considerations. Installation Considerations - The user ID of the user who is installing LEI must be resident in the Domino Directory group LocalDomainAdmins or the LEI installation will fail. - The Domino server must be running during LEI installation. For the UNIX platforms, the installer does not error out if Domino is not running. You must verify that the Domino server is running before installing LEI. - DECS, if installed, must not be running during LEI installation. You can end DECS by typing 'tell DECS quit' at the Domino console. - The LEI installation utility does not inform you that you must make changes to your Domino Directory in order to support the server-side browsing method used by LEI Release 6x. See the LEI Installation Guide for details. - The LEI server must be installed on a machine where a Notes client or a Domino server is installed. Only one LEI server can be installed on any single non-partitioned machine. On a partitioned machine, an LEI server can be installed on each partition. The LEI server version and the Notes/Domino version must match, for example Domino 6.5.2 (or 6.0.4) with LEI 6.5.2. - On UNIX, do not use the following characters in an LEI server name: ", ', &, ;, :, / Migration Considerations - Users must add the path to the Domino executable directory to their system PATH variable. For example, if performing migration where the LEI server and Domino server are on the same machine, the PATH must include C:\lotus\domino. If the migration is being performed on an LEI server that is installed via the Notes client, and the Domino server is remote, the PATH to the LEI server must include C:\lotus\notes. If this pathing is not set, the migration Tool may briefly flash on the screen, and exit without any error message. To capture the error message, invoke the run_migration.exe launcher from a dos prompt (as below) to gain additional information: run_migration.exe -is:log c:\temp\mig.txt Then look in the c:\temp\mig.txt file to see the following error: java.lang.UnsatisfiedLinkError: no nlsxbe (nlsxbe.dll) in java.library.path at java.lang.ClassLoader.loadLibrary(ClassLoader.java:1380) at java.lang.Runtime.loadLibrary0(Runtime.java:766) at java.lang.System.loadLibrary(System.java:849) at lotus.domino.NotesThread.load(NotesThread.java:299) at lotus.domino.NotesThread.checkLoaded(NotesThread.java:320) at lotus.domino.NotesThread.initThread(NotesThread.java:140) at lotus.domino.NotesThread.run(NotesThread.java:202) LEI users must manually add the Domino executable directory path to their PATH setting because Domino and LEI installation do not. This is a Domino consideration, outside the scope of LEI, and is documented as a technote and in the LDD forums. A helpful technote is available at http://www.ibm.com/support by selecting "Search technical support", entering 183735 in the "Enter search terms" field, and then clicking Submit. You can also find assistance by performing an "All of LDD" search at www.lotus.com/ldd on the "unsatisfiedlinkerror" string. - If you have installed DECS and want to migrate your DECS Administrator to LEI Release 6.5.2, you must first upgrade your DECS Administrator to 6.5.2 before installing LEI. You can then install this release of LEI. The LEI installer automatically upgrades the DECS Administrator to this release of LEI. - The migration log does not indicate the names of activities or connections that have been skipped (not migrated) because they were logged as a duplicate of an activity or connection in the LEI 6.5.2 Administrator. - When performing a migration that includes a script vault, if the migration tool encounters a script in the target with the same name as one that you are migrating from the source, the migrating (source) script will be logged as a duplicate. The remaining scripts will be logged as duplicates and will not be migrated. - On iSeries, migrating from an LEI 3.1 Administrator to the LEI 6.5.2 Administrator at the end of LEI installation will correctly complete migration, but will leave the migration utility window open; you must manually close that window to complete the process. If another Administrator is to be migrated, you must start the LEI 6.5.2 migration utility again. Thus, if you intend to migrate more than one LEI 3.1 or DECS Administrator to LEI 6.5.2, invoke the migration utility separately, not as part of the LEI 6.5.2 installation utility. - On iSeries, if you receive the "Unable to open source database" message when starting the migration utility, then the database it is trying to access is not available. If you receive this message, check the following and then try again. 1. Is the Domino server from which you wish to migrate running? 2. Did you name the LEI Administrator correctly (leiadm.nsf and its variations)? 3. Does the server to which you are migrating have permission to access the source server? (Check the server log for the source Administrator.) D) Installing LEI - General Instructions See the Installation Guide (leiig.nsf) supplied with LEI and also available as both a .nsf file and an HTML browseable at the LDD Documentation library (http://www.lotus.com/ldd) on the Enterprise Integrator product page for complete LEI installation and migration instructions. See below for related considerations. Before installing to a UNIX platform, you must do the following: - Set the correct access controls in the names.nsf file on the Domino server. - Establish the correct access rights in the Notes ID file. - Ensure that all needed environment variables are set and exported. - Ensure that you have loaded and configured X Window system software. If you will be installing LEI to a Notes client, set the Notes ID to share its password with other Notes-based systems, as documented in the LEI installation guide. To avoid multiple promptings for password, ensure that your Notes client is running during LEI install. E) Uninstalling LEI The LEI uninstall process is explained fully in the Installation Guide (leiig.nsf) supplied with LEI and also available as both a .nsf file and an HTML browseable at the LDD Documentation library (http://www.lotus.com/ldd) on the Enterprise Integrator product page. F) Operational Considerations LEI Tech Notes and other user information can be found at http://www-3.ibm.com/software/lotus/support/integration/support.html. The Lotus Connector LotusScript Extensions Guide (lsxlc6.nsf) and Lotus Connectors and Connectivity Guide (lccon6.nsf) are not supplied with LEI. You can obtain them at the LDD Documentation Library or with your Domino release. Virtual Activities Considerations - When using any LEI Data Transfer activity in conjunction with an ODBC to DB2 or an ODBC to Oracle connection, the activity will fail if certain binary data types are mapped. Additionally, Virtual Documents activities will fail whether or not these binary data types are mapped as data due to the internal use of the types. With DB2, this occurs when using either the native IBM DB2 ODBC driver or the DataDirect DB2 ODBC driver. With Oracle, this occurs when using either the native Oracle ODBC driver (pre 8.1.5) or the DataDirect Oracle ODBC driver. The native Oracle ODBC driver version 8.15 and later does not appear to have this limitation. The affected data types are as follows, with possible suggested alternates where possible: DB2 BLOB,CLOB alternate: use VARCHAR FOR BIT DATA Oracle BLOB alternate: use LONG RAW or RAW For Virtual Documents, use one of the alternate types when setting up the EINOTEPROPS column and set the size to the largest allowable, which will be generally less than the recommended size of 10K when using the BLOB data type. - As of LEI release 6.5, when working with DB2 and the required EINOTEPROPS field, the suggested field size has changed from a 2GB BLOB to a 10240 VARCHAR FOR BIT DATA. This may cause errors in your Virtual Documents activities after you upgrade to LEI 6.5. The solution is detailed in the Virtual Documents chapter of the user guide in the section entitled Virtual Documents Required Column Data Types. - If Advanced RealTime is enabled ("EXTMGR_ADDINS=decsext" is present in your notes.ini file), whenever the Domino server is shut down, the LEI server is also shut down, regardless of whether it is run as an addin task ("ServerTasks=LEI" is present in your notes.ini file). This is not an issue if RealTime is not enabled on the Domino server. iSeries Considerations - On the iSeries platform, when transferring data from Notes to Japanese EBCDIC DB2, the Japanese single byte yen character (0x5c in LMBCS) is replaced with the backslash character. - On iSeries, the LCFieldList.Copy method of LC LSX drops the source LCStream object property values for Stream Flags and Max Length. As a result, they are not set in the target FieldList object. LCFieldList.MaxLength is a read-only property based on the LCStream type: LCTYPE_TEXT or LCTYPE_BINARY. You can manually set the LCFieldList.Flags property when copying, obtaining the property values from the source object. - Use the native Lotus Connector for DB2 to access the IBM DB2 UDB and IBM DB2 on iSeries. For the latest information about the iSeries platform, visit the http://www-1.ibm.com/servers/eserver/iseries Web site: For the latest information about Enterprise Integration offerings, visit the http://www.lotus.com/ei Web site. G) What's Been Fixed in LEI Release 6.5.2 The following issues have been corrected in LEI 6.5.2. General: Problem: LEI can only transfer up to half the double-bytes data into a Graphic field. Resolution: This limitation has been corrected. Problem: Error messages in the log file truncate at 256 characters. Resolution: This limitation has been corrected. Problem: If LEI is installed as a Domino addin on AIX, LEI may fail to shut down when Domino is shut down. Resolution: This limitation has been corrected. Activities: Problem: Virtual Fields performance using multi-value fields may degrade under a heavy activity load. Resolution: This limitation has been corrected. Problem: In a Virtual Fields activity, error logging was not consistent. When set to ignore errors or to handle errors on post open formulas, errors were not logged. Resolution: If set to ignore "not found" fetch errors, the error is not logged. Problem: When multiple Virtual Document activities are started simultaneously against the same nsf, a "form is unavailable" error appears and the activities fail. Resolution: This limitation has been corrected. Problem: Expectation is that an error in the LEI activity log document for a Scripted activity should cause the activity to fail and therefore prevent dependent activities from running. Resolution: This limitation has been corrected and dependent activities will not run. Connections: Problem: A Notes connection containing computed subforms can't be used as an activity target. Resolution: This limitation has been corrected. Problem: A sort order problem can cause replication activities to fail. Resolution: This limitation has been corrected. H) Documentation Errata Three new screens are used during LEI installation on the iSeries V5R3 platform. These screens are not mentioned in the LEI Installation Guide installed during LEI installation. However, they are described below and are documented in the LEI Installation Guide at the top level of the application CD/download, as well as in the Documentation Library at the Lotus Developers Domain http://www-10.lotus.com/ldd/doc on the LEI Product Page for 6.5.2. New LEI installer screen 1 manual instructions for V5R3 users: MKDIR DIR('/home/QUSER) MKDIR DIR('/home/QUSER/.vnc) QAPTL/VNCPASSWD PASSWORD() VERIFY() USEHOME(*NO) PWDFILE('/home/QUSER/.vnc/passwd') Click OK when you have completed these steps. New LEI installer screen 2 manual instructions for V5R3 users: Right click on My Computer. Click Properties. Click the Advanced tab. Click the Environment variable. Edit the path within the User variables list to include the path to the Internet Explorer executable (iexplore.exe). Click OK when you have completed these steps. New LEI installer screen 3 with information for V5R3 users: In order to use the LEI Installer on a V5R3 or later iSeries, an Internet Explorer (IE) window will automatically open for this LEI install. The DCTEST program command line for iSeries is incorrect in chapter 1 of the Connectors and Connectivity Guide. The correct command line is specified below: RUNDOMCMD SERVER(iseries) CMD(CALL PGM(DCTEST)) BATCH(*NO). Also, DCTEST on iSeries only supports Notes and DB2. I) Troubleshooting and Additional Support For the latest LEI technical information, including Tech Notes, visit the following Web page: http://www-3.ibm.com/software/lotus/support/integration/support.html Support is also available for LEI at the following Web page: http://www-3.ibm.com/software/lotus/support/ ***************************************************************************** Under the copyright laws, neither the documentation nor the software may be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form, in whole or in part, without the prior written consent of IBM Corporation, except in the manner described in the documentation or the applicable licensing agreement governing the use of the software. Domino, Notes, IBM Lotus Enterprise Integrator for Domino (LEI), LotusScript, Lotus Connectors, and Domino Enterprise Connection Services (DECS) are trademarks of Lotus Software, IBM Software Group. AIX, DB2/2, DB2, and IBM are registered trademarks of International Business Machines Corporation. All other trademarks are held by their respective owners. Copyright IBM Corporation 1985-2004 Lotus Software, IBM Software Group One Rogers Street Cambridge, MA 02142 All Rights Reserved. *****************************************************************************