IBM Lotus Enterprise Integrator for Domino (LEI) Release 6.5.1 December 9, 2003 A) What's New in LEI Release 6.5.1 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.1 H) Documentation Errata I) Troubleshooting and Additional Support _______________________________________________________________________________ A) What's New in LEI Release 6.5.1 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.1 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 readme.txt at the LDD http://www.lotus.com/ldd Documentation library for the Enterprise Integrator product. - Current supported data drivers list The list of supported Lotus Connector data driver versions has been updated as below. All drivers are supplied with LEI. - Lotus Connector for DB2 with UDB 7.x and 8.1 - Lotus Connector for Oracle 7 with Oracle 7.3.4 and 8.0.5 - Lotus Connector for Oracle 8 with Oracle 8.0.5, 8i, and 9 - Lotus Connector for Sybase for Sybase 11.9.2 - Lotus Connector for OLE DB with SQL Server 2000 and Access 2000 - Lotus Connector for ODBC with DataDirect Lotus-branded driver 4.2 SP3 for standard ODBC connection - also see "Additional DataDirect ODBC driver support" statement above for additional 4.2 drivers. Supported systems include: - Sybase 12.5 - Oracle 9 - DB2 8.1 - SQL Server 2000 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.1 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 and V5R2 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 6.5.1 requires Notes/Domino 6.5.1. - Notes 6 client to administer the LEI Administrator database and run the LEI server if LEI is installed on a Notes client - Domino 6.5.1 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 (651 for Domino 6.5.1 or 604 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 6.5.1. See the LEI Installation Guide (leiig.nsf) 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.1 with LEI 6.5.1. - 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.1, you must first upgrade your DECS Administrator to 6.5.1 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.1 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.1 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.1 migration utility again. Thus, if you intend to migrate more than one LEI 3.1 or DECS Administrator to LEI 6.5,1, invoke the migration utility separately, not as part of the LEI 6.5.1 installation utility. 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.01.05 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.1 General: - LEI 6.x did not initialize correctly with a ServerKeyFileName and a KeyFileName. This has been corrected. Virtual Activities: - On iSeries, Virtual documents do not display if EINOTEPROPS is set to VARCHAR FOR BIT DATA or VARCHAR. This has been corrected. - On iSeries, Virtual attachments resynch with virtual fields has been inconsistent. This has been corrected. - When using a Virtual Documents activity in conjunction with an ODBC Sybase connection, the internal key fails to virtualize all records. This has been corrected. - When using Virtual documents in conjunction with an ODBC to SQLServer connection set, a document open event can hang the activity. This has been corrected. Data Management Activities: - An invalid field error may occur during replication of nested subforms. This has been corrected. H) Documentation Errata While the LEI 6.5.1 user documentation is slightly more current than the LEI 6.5 user documentation, it is not absolutely current to 6.5.1. In some cases, documentation additions and changes were not made and are instead documented below. LEI Installation Guide: - The documentation for the "setupAIX" executable doesn't adequately explain the syntax for the "-is:tempdir" option. The documentation should clearly specify that the name of the tempdir directory must be specified AFTER the "setupAIX -is:tempdir" wording, as for example: "setupAIX -is:tempdir mytempdir". The LEI installation guide should include the following information: Verify that there is enough space in your system temp directory. The installation program needs 45MB of free space in order to successfully execute. Either increase the size of the temp directory (/tmp file system) or change the directory that the LEI installation program uses as its temp directory. To do this, add the following setup program option, where "directory" is the path of the directory you want to use, for example: setupAIX -is:tempdir directory or setupSun -is:tempdir directory LEI User Guide: - You can use the Admin-backup activity to create a backup copy of the LEI Administrator and/or LEI Script Vault. To use the backup, copy the original administrator or script vault database to a new name (such as _mmddyy), delete the old database, and copy the backup to the data directory (typically \Lotus\Domino\data). Once copied, rename as either decsadm.nsf (admin) or leivlt6.nsf (script vault). Open the database and begin work. This procedure is not documented in the user guide. - In Chapter 13 of the LEI user guide, in the Using Stored Procedures in Virtual Document Events, the following two statements require change as noted below. - The statement "Second, for all the events except the delete event, ALL the external system table data fields mapped in the Virtual Document activity must be present as parameters. No other parameters are allowed. For a delete event stored procedure, only the EINOTEID is required" should be changed to "Second, for the create and update events, ALL the external system table data fields mapped in the Virtual Document activity must be present as parameters. No other parameters are allowed. For the open and delete events stored procedure, only the EINOTEID is required." - The statement "For Create or Update events, in addition to the mapped data fields, stored procedures must accept the EINOTEID field as an input parameter: For Open events, in addition to the mapped data fields, stored procedures must accept the EINOTEID field as an input/output parameter. For Delete events, only the EINOTEID must be mapped as an input parameter" should be changed to "For Create or Update events, in addition to the mapped data fields, stored procedures must map the EINOTEID field as an input parameter. For Open and Delete events, only the EINOTEID must be mapped as an input parameter". - User Guide documentation for the Archive activity incorrectly indicates that the Archive activity document has a select statement field; it does not. Lotus Connector LotusScript Extensions Guide: - There is an error in the LCField class chapter as below. The statements: LCFIELDF_KEY_GT -- Key condition is greater than LCFIELDF_KEY_LT -- Key condition is less than should be: LCFIELDF_KEY_GT -- Key condition is greater than or equal LCFIELDF_KEY_LT -- Key condition is less than or equal - There is an error for the DatetimeListGetValue Method in the LCStream class chapter as below. The statement: ... This method scans the list starting with the first element, searching for range values and counting them. Once the count reaches index, the range value at that position is returned. If the list contains a mixture, this might not be the indexed value in the list. should be: ...This method scans the list starting with the first element, searching for date-time values and counting them. Once the count reaches index, the date-time value at that position is returned. If the list contains a mixture, this might not be the indexed value in the list. Lotus Connectors and Connectivity Guide: - There is an error in the Oracle 8 Connectivity section of Chapter 2 as below: The statements: Connectivity software requirements depend on the operating system platform and the Oracle 8 version you are using. You must have Oracle client version 8.0.5 or 8i. Oracle connectivity on Solaris relies on the Oracle 8i client library found in ORACLE_HOME/lib. If you are using LEI and a pre-8i version of the Oracle client, you must create a symbolic link in ORACLE_HOME/lib using the command "ln -s libclntsh.so.1.0 libclntsh.so.8.0'". should be: ...You must have Oracle client version 8.05, 8i, or 9.x. Oracle connectivity on Solaris relies on the Oracle 8i client library found in ORACLE_HOME/lib or the Oracle 9 client found in ORACLE_HOME/lib32. If you are using LEI and a pre-8i version of Oracle client, you must create a symbolic link in ORACLE_HOME/lib using the command "ln -s libclntsh.so.1.0 libclntsh.so.8.0'". If you are using LEI and an Oracle 9 client, you must create a symbolic link in ORACLE_HOME/lib32 using the command "ln -s libclntsh.so.9.0 libclntsh.so.8.0". 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. *****************************************************************************