Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
Entity–attribute–value model wikipedia , lookup
Extensible Storage Engine wikipedia , lookup
Open Database Connectivity wikipedia , lookup
Ingres (database) wikipedia , lookup
Microsoft Jet Database Engine wikipedia , lookup
Relational model wikipedia , lookup
Microsoft SQL Server wikipedia , lookup
Front cover Implementing IBM Lotus Enterprise Integrator grator 6 on the IBM iSeries Server Architecting and designing enterprise solutions using LEI 6 Installing and administering LEI 6 on the iSeries server Getting the most out of the Advanced RealTime activities Deb Landon Ian Barrack Kim Greene Shu Sia Lukito Rajat Prashar ibm.com/redbooks International Technical Support Organization Implementing IBM Lotus Enterprise Integrator 6 on the IBM ~ iSeries Server September 2003 SG24-6941-00 Note: Before using this information and the product it supports, read the information in “Notices” on page ix. First Edition (September 2003) This edition applies to IBM Lotus Enterprise Integrator for Domino (LEI) Release 6.0.1 (product number 5733-LEI) or later for use on OS/400 Version 5 Release 1 and later. © Copyright International Business Machines Corporation 2003. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi The team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv Chapter 1. Introduction to IBM Lotus Enterprise Integrator (LEI) 6 for Domino . . . . . . 1 1.1 A business case for LEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.2 DECS and DCRs defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2.1 DECS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2.2 DCRs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.3 LEI defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.3.1 Connection documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3.2 Activity documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.3.3 Current limitations with using LEI 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.4 A comparison of DECS, DCRs, and LEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.4.1 Advanced RealTime feature - virtual attachments . . . . . . . . . . . . . . . . . . . . . . . . 10 1.4.2 Advanced RealTime feature - integrated credentials . . . . . . . . . . . . . . . . . . . . . . 10 1.5 What’s new with LEI 6.0 and LEI 6.0.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 1.5.1 What’s new in LEI 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 1.5.2 LEI 6.0.1 on the iSeries server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 1.6 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.6.1 iSeries relational database versus LEI verses Lotus Domino . . . . . . . . . . . . . . . . 15 1.6.2 DB2 UDB iSeries terminology differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 1.7 Data type conversions/mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 1.7.1 iSeries SQL data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 1.7.2 iSeries native physical file data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 1.7.3 Domino Designer data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 1.7.4 Data type mapping guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Chapter 2. Architectural scenarios and considerations . . . . . . . . . . . . . . . . . . . . . . . . 2.1 Architectural scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.1 Scenario 1: Single iSeries server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.2 Scenario 2: Remote database server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.3 Scenario 3: LEI 6 integration with Domino R5 applications . . . . . . . . . . . . . . . . . 2.1.4 Scenario 4: Decentralized Advanced RealTime access . . . . . . . . . . . . . . . . . . . . 2.1.5 Scenario 5: Advanced RealTime in a hub and spoke environment . . . . . . . . . . . 2.1.6 Scenario 6: Accessing multiple relational databases from iSeries . . . . . . . . . . . . 2.2 Security considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.1 Generic user ID and password in connection document. . . . . . . . . . . . . . . . . . . . 2.2.2 Integrated credentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.3 Fields and public key encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3 Performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3.1 LEI considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3.2 Performance spectrum scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3.3 DB2 UDB considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3.4 Connection pooling verses persistent connections . . . . . . . . . . . . . . . . . . . . . . . . © Copyright IBM Corp. 2003. All rights reserved. 25 26 26 27 29 31 33 35 36 36 37 40 41 41 43 44 45 iii 2.3.5 Persistent connections in Advanced RealTime activities . . . . . . . . . . . . . . . . . . . 47 Chapter 3. Installation and configuration on the iSeries platform . . . . . . . . . . . . . . . . 3.1 Prerequisites for operating LEI on the iSeries server . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.1 Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.2 Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.3 Required PTFs for OS/400 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.1.4 Domino Enterprise Connection Services (DECS) . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Pre-installation activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2.1 Domino server document changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2.2 ID modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2.3 TCP/IP configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3 Installation of LEI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.1 Installation Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.3.2 Process of Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4 Administration of LEI on the iSeries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.1 LEI Administrator database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.2 Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.3 Starting and stopping the LEI server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 50 50 50 52 55 56 56 57 59 60 60 60 76 77 80 85 Chapter 4. Migrating from Lotus Enterprise Integrator 3.x . . . . . . . . . . . . . . . . . . . . . . 87 4.1 Migration considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 4.1.1 Migrating scripted documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 4.1.2 Migrating metaconnection documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 4.1.3 LEI clustering and remote administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 4.1.4 Duplicate connection and activity documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 4.2 Pre-migration activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 4.3 Process of migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 4.4 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 4.4.1 Migration log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 iv Chapter 5. Base connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1 Distributed Relational Database Architecture (DRDA) . . . . . . . . . . . . . . . . . . . . . . . . 5.2 iSeries to iSeries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2.1 Connecting from an iSeries server to an iSeries server . . . . . . . . . . . . . . . . . . . 5.2.2 Creating a local relational database directory entry . . . . . . . . . . . . . . . . . . . . . . 5.2.3 Creating a DRDA connection to a remote iSeries server . . . . . . . . . . . . . . . . . . 5.2.4 Test connectivity using the DCTEST utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3 xSeries server to iSeries server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.1 Required software and setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.2 iSeries DB2 UDB client configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.3 Testing connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.3.4 Errors encountered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4 iSeries to pSeries connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.1 Determining pSeries remote database server port . . . . . . . . . . . . . . . . . . . . . . . 5.4.2 Creating a remote RDBDIRE entry to the pSeries server . . . . . . . . . . . . . . . . . . 5.4.3 Ensure the iSeries server is not using the default CCSID. . . . . . . . . . . . . . . . . . 5.4.4 Perform the DCTEST connectivity test . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.4.5 Creating a connection document to DB2 UDB on the pSeries server. . . . . . . . . 103 104 104 105 105 109 117 120 120 121 133 139 140 140 145 146 148 151 Chapter 6. Connection documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.1 DB2 connection document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.1.1 Connectivity section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.1.2 Table selection section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 154 154 157 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 6.1.3 Other section. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2 Notes connection document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.1 Connectivity section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.2 Other section. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3 File connection document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.1 Connectivity section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.2 Subdirectory Selection section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3.3 Other section. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.4 Text connection document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.4.1 Connectivity section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.4.2 Text specifications section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.4.3 Other section. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.5 Metaconnectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.5.1 Collapse/Expand metaconnector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.5.2 Meter metaConnector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.5.3 Order metaConnector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.5.4 Trace metaConnector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.6 Test connection documents using the CONTEST utility . . . . . . . . . . . . . . . . . . . . . . . 157 157 158 166 166 167 168 168 169 170 170 174 174 174 176 177 179 180 Chapter 7. Setting up the examples environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.1 OS/400 libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.1.1 Download and set up the libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.1.2 EMPLIB library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.1.3 AUTOBODY library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2 Domino databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2.1 Autobody demo database (autobodydemo.nsf) . . . . . . . . . . . . . . . . . . . . . . . . . 7.2.2 Case files database (casefile.nsf) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2.3 Employee database (employee.nsf) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2.4 Medical records database (medrec.nsf) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 184 184 185 188 189 190 192 192 193 Chapter 8. Advanced RealTime activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.1 Virtual documents activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.1.1 How does the virtual documents activity work? . . . . . . . . . . . . . . . . . . . . . . . . . 8.1.2 External system metadata for virtual documents activities . . . . . . . . . . . . . . . . . 8.1.3 Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.1.4 Deletion involving virtual documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.1.5 Domino replication involving virtual documents . . . . . . . . . . . . . . . . . . . . . . . . . 8.1.6 Event options for virtual documents activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2 Virtual fields activity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2.1 How does the virtual fields activity work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2.2 Event options for virtual fields activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.3 Differences between virtual documents and virtual fields . . . . . . . . . . . . . . . . . . . . . . 8.3.1 Advantages of virtual documents activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.3.2 Limitations of virtual documents activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.3.3 Using virtual fields with virtual documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.4 Virtual attachments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.5 Virtual agents activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.6 Example 1: Using a virtual documents activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.6.1 Create a DB2 connection document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.6.2 Create a virtual documents activity document . . . . . . . . . . . . . . . . . . . . . . . . . . 8.6.3 Testing the virtual documents activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.7 Example 2: Using virtual documents with a DB2 UDB view . . . . . . . . . . . . . . . . . . . . 8.7.1 Create a DB2 connection document to EMPLIB.EMP_DEPT. . . . . . . . . . . . . . . 195 196 196 197 199 199 200 201 201 202 202 203 203 203 204 204 205 206 206 208 215 216 217 Contents v vi 8.7.2 Create a virtual documents activity document . . . . . . . . . . . . . . . . . . . . . . . . . . 8.7.3 Testing the virtual documents activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.8 Example 3: Using virtual fields with multiple DB2 tables. . . . . . . . . . . . . . . . . . . . . . . 8.8.1 Create a DB2 connection document to EMPLIB.EMPLOYEE . . . . . . . . . . . . . . 8.8.2 Create a DB2 connection document to EMPLIB.DEPARTMENT . . . . . . . . . . . . 8.8.3 Create a virtual fields activity document to EMPLIB.EMPLOYEE. . . . . . . . . . . . 8.8.4 Generate key documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.8.5 Create a virtual fields activity document to EMPLIB.DEPARTMENT . . . . . . . . . 8.8.6 Testing the virtual fields activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.9 Example 4: Using virtual fields with virtual documents . . . . . . . . . . . . . . . . . . . . . . . . 8.9.1 Create a DB2 connection document to EMPLIB.EMPLOYEE2 . . . . . . . . . . . . . 8.9.2 Create a DB2 connection document to EMPLIB.DEPARTMENT . . . . . . . . . . . . 8.9.3 Create a virtual documents activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.9.4 Create a virtual fields activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.9.5 Testing the activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.10 Example 5: Using virtual agents and virtual attachments . . . . . . . . . . . . . . . . . . . . . 8.10.1 Create a DB2 connection document to AUTOBODY.AUTOBODY_EST . . . . . 8.10.2 Create a DB2 connection document to AUTOBODY.AUTOBODY_DAMAGE . 8.10.3 Create a DB2 connection document to AUTOBODY.DAMAGETOT . . . . . . . . 8.10.4 Create a virtual documents activity document . . . . . . . . . . . . . . . . . . . . . . . . . 8.10.5 Create a virtual fields activity document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.10.6 Create a virtual agents document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.10.7 Testing the virtual attachments activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.10.8 Testing the virtual agents activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 223 224 224 226 228 229 229 231 231 232 234 234 236 237 237 238 240 242 243 246 248 253 254 Chapter 9. Batch activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.1 Scripted activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.1.1 Example: Building a direct transfer scripted activity . . . . . . . . . . . . . . . . . . . . . . 9.2 Replication activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2.1 Primary key replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2.2 Timestamp replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2.3 Example: Timestamp replication from DB2 UDB to Domino. . . . . . . . . . . . . . . . 9.3 Other data moving activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.3.1 Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.3.2 Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.3.3 Direct transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.3.4 Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.3.5 Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.3.6 Admin-Backup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.3.7 Admin-Purge Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 256 256 264 264 264 266 272 272 273 273 273 273 273 273 Appendix A. Removing Lotus Enterprise Integrator (LEI). . . . . . . . . . . . . . . . . . . . . . Considerations prior to removing LEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access to data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LEI clustered environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Domino Enterprise Connection Services (DECS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process of removing LEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 276 276 276 276 277 Appendix B. Using iSeries Navigator to access DB2 UDB . . . . . . . . . . . . . . . . . . . . . Connecting to an iSeries server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with a library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying a library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 286 288 288 290 292 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Viewing the contents of a table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 Checking for journaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 Running SQL scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 Appendix C. Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the LEI log (leilog.nsf) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Domino log (log.nsf) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling log conflicts in replication activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging SQL statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the trace metaconnector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Notes Server Diagnostic (NSD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using spool file output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the OS/400 command line interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using iSeries Navigator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 306 307 309 310 311 311 312 312 314 Appendix D. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 317 317 317 Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 319 319 319 320 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 Contents vii viii Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 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 give 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. 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. 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. 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 illustrates 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. 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 IBM's application programming interfaces. © Copyright IBM Corp. 2003. All rights reserved. ix Trademarks The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both: Redbooks(logo) ™ ^™ eServer™ ibm.com® iNotes™ iSeries™ pSeries® xSeries® zSeries® AIX® ™ AS/400® Distributed Relational Database Architecture™ Domino™ Domino Designer® DB2 Connect™ DB2 Universal Database™ DB2® DRDA® Informix® IBM® Lotus Enterprise Integrator® Lotus Notes® Lotus® Notes® OS/400® PartnerWorld® Passport Advantage® QuickPlace® Redbooks™ Sametime® The following terms are trademarks of other companies: Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporation 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. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by SET Secure Electronic Transaction LLC. Other company, product, and service names may be trademarks or service marks of others. x Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Preface This IBM Redbook helps you to implement Lotus® Enterprise Integrator® (LEI) 6 on the IBM ~™ iSeries™ server. It is targeted for system administrators who plan to implement or upgrade to LEI 6 in their organization. The redbook provides tips and techniques to help you successfully deploy and administer LEI 6 on an iSeries server. We begin by providing a brief introduction to what’s new with LEI 6 and cover some architectural scenarios of how LEI 6 infrastructure could be implemented in a customer’s environment. We then provide detailed information about how to install and administer LEI 6 on the iSeries server. Migrating or upgrading from LEI 3.x is also covered. This redbook also provides some basic connectivity information about how to connect one iSeries server to another as well as from iSeries to pSeries®, and xSeries® to iSeries. Finally this redbook provides some working examples of how to use the Advanced RealTime activities that are new in LEI 6. It also provides examples of some of the batch activities previously available in LEI 3.x such as a scripted activity and a replication activity. Note: This redbook is based on Domino™ 6.0.1 and Lotus Enterprise Integrator (LEI) 6.0.1. Newer releases will continue to provide new and enhanced functions. Refer to the readme file associated with the follow-on LEI releases for additional information or you can access the LEI user documentation in Documentation Library of the Lotus Developer Domain Web site at: http://www.lotus.com/ldd The team that wrote this redbook This redbook was produced by a team of specialists from around the world working at the International Technical Support Organization, Rochester Center. Deb Landon is a certified IT Specialist in the IBM International Technical Support Organization, Rochester Center. Her current area of expertise is focused on Domino for iSeries and related Lotus products such as Sametime® and QuickPlace®. Debbie has been with IBM for 19 years working first with the S/36 and then the AS/400®, now iSeries server. Before joining the ITSO in November of 2000, she was a member of the PartnerWorld® for Developers, iSeries team supporting Business Partners in the area of Domino for iSeries. © Copyright IBM Corp. 2003. All rights reserved. xi Ian Barrack is chairman of Simban Holdings Pty. Ltd., an Australian based professional services firm. A Certified Lotus Instructor, he has 14 years experience in providing consultancy services in both private and government arenas. From a defense background, Ian has worked with developing solutions utilizing IBM/Lotus environments since 1993 based on Intel, Sun, iSeries, and zSeries® platforms. His expertise is in supplying corporate solutions incorporating systems/data security, enterprise integration, systems design and troubleshooting. The center of Ian’s attention is on providing appropriate solutions to organizations of all sizes. Ian can be contacted at [email protected]. Kim Greene, president of Kim Greene Consulting, Inc., specializes in Domino for iSeries consulting, development, customized education, and performance. Kim has over six years of experience with Domino and 14 years of experience with the AS/400 and iSeries platforms. Kim specializes in iSeries Domino performance analysis, system and application tuning, enterprise integration with back-end applications and data, and Domino application development. Other services offered include providing customized iSeries Domino education and training for customers and Business Partners. For more information about any of these services, see www.kimgreene.com. Kim is also a frequent writer for technology magazines and speaks at many conferences worldwide. Previously she was employed at IBM where she worked in the PartnerWorld for Developers (PWD) organization helping IBM business partners incorporate Domino into their existing applications. Prior to working in PWD she worked in several areas of OS/400® performance in the AS/400 development laboratory. Shu Sia Lukito is an Advisory IT Specialist with IBM Software Services for Lotus (ISSL) within the Bethesda, MD office. Her current area of expertise is focused on Domino design and development and related Lotus technologies, such as enterprise integration, Sametime, and QuickPlace. Rajat Prashar is an IT Architect with IBM Software Service For Lotus (ISSL) working out of the Toronto Lab. As an IT Architect with ISSL, his main role is the design and development of strategic e-business solutions for IBM customers. Rajat has over 10 years of experience in technology consulting and holds a degree in MIS from Concordia University. His areas of expertise include Web application development, enterprise integration, collaboration, knowledge management, and e-commerce. xii Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Thanks to the following people for their contributions to this project: Tim Bishop Steve Kluck Gary Mulford Domino for iSeries development team, IBM Rochester Mike Gilley IBM iSeries Support Center, Lotus Domino team Brian Hallstrom Deb Maguire Lotus Support Center Andre Guirard Lotus Enterprise Integration Team Mike Pascoe Enterprise Support Services, IBM Rochester Jeff Huebert DRDA/DDM development team, IBM® Rochester Become a published author Join us for a two- to six-week residency program! Help write an IBM Redbook dealing with specific products or solutions, while getting hands-on experience with leading-edge technologies. You'll team with IBM technical professionals, Business Partners and/or customers. Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you'll develop a network of contacts in IBM development labs, and increase your productivity and marketability. Find out more about the residency program, browse the residency index, and apply online at: ibm.com/redbooks/residencies.html Preface xiii Comments welcome Your comments are important to us! We want our Redbooks™ to be as helpful as possible. Send us your comments about this or other Redbooks in one of the following ways: Use the online Contact us review redbook form found at: ibm.com/redbooks Send your comments in an Internet note to: [email protected] Mail your comments to: IBM Corporation, International Technical Support Organization Dept. JLU, Building 107-2 3605 Highway 52N Rochester, Minnesota 55901-7829 xiv Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 1 Chapter 1. Introduction to IBM Lotus Enterprise Integrator (LEI) 6 for Domino This chapter provides an overview of the IBM Lotus Enterprise Integrator (LEI) 6 product. You will learn the following by reading this chapter: What LEI is How LEI can be used to solve business problems What is Domino Enterprise Connection Services (DECS) and Domino Connection Resources (DCRs) and how do they compare to LEI 6 What functions the LEI 6 product provides What is new in LEI 6.0.1 What is new with LEI 6 on the iSeries A discussion of the terminology differences between Domino and DB2® Universal Database™ (DB2 UDB) Data type mappings between Domino and DB2 UDB on the iSeries © Copyright IBM Corp. 2003. All rights reserved. 1 1.1 A business case for LEI Enterprise integration is a critical requirement for almost every iSeries customer. The iSeries has a very rich set of applications that rely on relational data stored in DB2 UDB. Since the release of OS/400 V4R2, Lotus Domino has also been a significant part of the iSeries portfolio. With Domino, iSeries servers can run collaborative, workflow, Web-enabled applications that are written for the Domino environment. There are many options available when integrating back-end data into Domino. This back-end data may be DB2 UDB data, Enterprise Resource Planning (ERP) data, other relational data such as from Sybase, Oracle, or SQL server. The most common back-end data source on the iSeries is DB2 UDB. The Lotus enterprise integration strategy is shown in Figure 1-1. The diagram shows how Lotus’ strategy provides full access to Domino from any client to any data. This is critical in today’s business environment. Many businesses have data in various types of data sources, including relational databases, transactional systems, ERP systems, and many others. These back-end resources need to be accessed from a multitude of client types, including Web browsers, Lotus Notes® clients, wireless devices such as phones or pagers, the iNotes™ client, and so on. WEB BROWSER DB2 UDB ORACLE LOTUS NOTES SYBASE PDA OLE-DB WAP PHONE CLIENT DOMINO SERVER LEI ODBC DATA iNOTES PAGER FILE NOTES TEXT SAP R/3 Figure 1-1 Lotus’ enterprise integration strategy Most application architectures today have three tiers: Presentation Application logic Data Application development teams have different skills to create and maintain each tier of the application. The presentation layer requires HTML and JSP skills, application logic requires LotusScript, Java, servlets, C, and other skills, while data access requires database administration skills, SQL, data normalization, and possibly stored procedure knowledge. 2 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server LEI eases the strain placed on businesses by making it easier to integrate with various back-end systems. Through its forms-based nature, LEI lightens the burden on application developers by not requiring someone to have specific database administration skills, SQL skills, or the ability to write stored procedures. While there are many different ways to access back-end data sources from Domino, LEI is a tool that provides very powerful enterprise integration options. LEI is a separately acquired Lotus product for the Domino server. It provides the ability to perform high-volume data transfers, synchronize disparate data sources, and provide real-time integration with back-end data sources. The synchronization capability is a unique feature of LEI. LEI can synchronize a Domino database with a DB2 UDB database, or an Oracle database with a DB2 UDB database. The possibilities are endless. LEI provides a visual mapping tool to establish integration between data sources, including the ability to initiate event-driven or scheduled high-volume data transfers between Domino applications and Relational Database Management Systems (RDBMS), Enterprise Resource Planning (ERP), and Transaction Processing (TP) system enterprise sources. LEI activities and data transfers can also be programmatically customized using LotusScript or Java. LEI is used by many businesses to allow their employees to work in a disconnected mode while still having access to enterprise data. This is extremely important for sales personnel who work remotely and who are often not connected to the server most of the day to access back-end data sources such as DB2 UDB with a Domino database. The application user, in this case a remote sales person, can replicate the Domino application and data to a laptop. They then have access to back-end data without needing to be connected to the back-end system. This is a very powerful feature. Domino 6 extends this rich functionality of LEI by incorporating data real-time through a new technology called virtualization that makes integration with back-end data sources seamless. One of the biggest inhibitors to using Domino Enterprise Connection Services (DECS) R4.6/R5 or Domino Connection Resources (DCR) technology in Domino 6 is the problem of having to synchronize keys between DB2 UDB and Domino data sources. This has been a real problem for many iSeries users because those keys quickly become out of sync as non-Domino applications, such as RPG and COBOL programs, insert or delete records from these same back-end DB2 UDB data sources. If the insertions and deletions are not happening exclusively through Domino, DECS and DCRs are not aware that new keys are available and that some keys have been eliminated in the back-end data store. There are work-arounds to this issue, but they require programming skills to resolve. LEI 6 eliminates most of these work-around requirements by providing real-time access to back-end data stores through its virtualization technology. This new technology offers the ability to integrate with back-end data stores without having to store any keys in the Domino environment. Virtualization is almost magical. It provides the functionality of having all the data stored outside of Domino, while still allowing an end user to work with that data as if it were stored locally in the Domino database. This means the virtualized data can participate in views, offering a very rich set of functionality not previously available with real-time data access mechanisms. 1.2 DECS and DCRs defined In the previous section, both DECS and DCRs were briefly discussed. Let’s look at these two integration options in further detail so you understand how they compare with the functionality provided by LEI. Chapter 1. Introduction to IBM Lotus Enterprise Integrator (LEI) 6 for Domino 3 1.2.1 DECS DECS has been a component of the Domino server since Release 4.6.3 and offers developers a non-programmatic way to create applications that provide live, native access to enterprise information and data. DECS provides real-time access to data in a back-end data source such as DB2 UDB. DECS can be used to visually map data between Domino and back-end data sources such as DB2 UDB, Notes, text, stream files, and ERP systems. The relationship between a Domino application and an enterprise data source on the back-end is defined in a Domino database known as the DECS Administrator. The DECS administrator provides a visual wizard and online documentation to assist the application developer in defining the external data source connections to the back-end data source. Fields in this data source and the Domino application are visually identified and mapped in activity documents which are created in the DECS Administrator database. With these connection and activity documents, Domino applications can operate on enterprise or external data as seamlessly as if they were located in Domino. With DECS, external, back-end data can be viewed, created, updated, or deleted directly and transparently by the Lotus Notes or Web browser client. The biggest inhibitor for businesses to utilize DECS in their Domino applications requiring enterprise integration is the issue described in the previous section. This is the issue of the keys becoming out of sync when applications external to Domino access the same DB2 UDB databases that Domino is accessing. 1.2.2 DCRs DCRs (Data Connection Resources) were introduced with Domino 6. DCRs brings the technology of DECS into the Domino Designer® client so that you can define a connection to an external data source, such as a relational database. You can then use the connection to link the fields that are contained in a form to fields that are found in the external source. DCRs are reusable in an application and can be shared across applications. You can use DCR technology to access data in enterprise systems and then take advantage of the power of a Domino application to replicate, share, secure, and manage the data. DCRs have the same issue as DECS, where keys can become out of sync if there are applications external to Domino manipulating the back-end DB2 UDB databases. For more information about DCRs, see the article ‘Lotus Domino Designer 7 Technical Overview’ on the Lotus Developer Domain LDD Today Web site. This article can be found at: http://www.lotus.com/ldd/today.nsf Additional information about both DECS and DCRs can be found in the Domino Designer Client help database. Both DECS and DCR support comes with the base Domino 6 code. They are not separate products you need to purchase. 1.3 LEI defined The LEI product has been providing core integration technology between Domino and back-end data sources for a number of releases now. The product was first introduced as NotesPump. As popularity in this tool grew, the NotesPump product was rewritten and enhanced to become LEI. LEI is a server based data distribution tool that provides customers with a forms based, no programming required method to move information between legacy and relational server sources and Domino applications. It is the perfect tool for solving business problems that 4 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server require data stored in different types of data sources to tightly integrate. LEI has a number of functions that allow for this integration. These functions are described below in 1.3.2, “Activity documents” on page 6. LEI has an incredibly rich set of functionality for integrating Domino with numerous back-end data sources. LEI is a separate product that is purchased from Lotus. In the next two sections we discuss the two main components for using LEI, connection and activity documents. 1.3.1 Connection documents Connection documents define the data sources that are involved in the functionality defined in the activity documents. Depending on the activity, some LEI activities, such as replication, require both a source and destination connection document. Others, such as virtual fields, require only one. The information provided in a connection document includes the type of data source being connected to, appropriate user authentication information for connecting to that data source, the data source name, and connector specific information such as whether the data source is being journaled or not in the case of DB2 UDB. There are a core set of connectors that ship with the Domino server code that allow for the source and destination data sources to correspond. Connectors provide the strategic ‘plumbing’ for enterprise integration. They deliver native connectivity, via a consistent object model, to external data sources. Connectors allow Domino applications to connect, authenticate, and translate data that resides within relational databases, enterprise resource planning, and transaction processing systems. There are two sets of connectors, the base connectors and premium connectors. The base connectors are included in the Domino 6 server code and include the following: DB2 Notes Oracle Sybase OLE DB ODBC File System Text Because Lotus Domino is a cross platform product, not all of these connectors are supported on every platform. The base Domino connectors that are currently supported on the iSeries server include: DB2 Notes File System Text Note: Future releases of LEI on the iSeries server will support additional base connectors. Premium connectors provide access to ERP back-end data sources. Because these connectors are provided by the ERP provider themselves, they are a chargeable feature. It is very important to use an ERP connector rather than manipulating the back-end ERP files directly. This is necessary because ERP systems have many sets of business rules that need to be applied to the back-end data being manipulated. Chapter 1. Introduction to IBM Lotus Enterprise Integrator (LEI) 6 for Domino 5 At the time this redbook was written, only one ERP provider has a connector available to work with Domino 6. That ERP provider is SAP R/3 version 1.7. Also at the writing of this redbook, the SAP R/3 connector does not support the new Advanced RealTime activities, only the batch LEI activities are supported with LEI 6. For the latest information about what premium connectors are available to work with LEI 6, refer to the Lotus Enterprise Integration Web site at: http://www.lotus.com/ei For details about creating connection documents, see Chapter 6, “Connection documents” on page 153. Metaconnectors Metaconnectors are special LEI connection documents that provide additional data processing on data returned from a specified connector. There are four different metaconnection documents support in LEI 6: Collapse/expand Provides the capability to take multiple records from one data source table and collapse them into a single form field. This metaconnection document also performs the reverse operation to expand data into multiple records. Meter Provides a way to collect statistical usage data and is useful to identify and quantify data access patterns. Order Useful when ordering data sets from different server sources. This metaconnection is especially helpful to order data sets returned from Domino to match the order alphanumeric data is returned from the iSeries DB2 connection. Trace This metaconnector is used to debug problems with connection documents. For more details about metaconnection documents, see the 6.5, “Metaconnectors” on page 174. 1.3.2 Activity documents Activity documents define the type of function LEI will perform. Each activity is created by filling out a specific activity document. The document collects the appropriate information about the source and target environments. In the activity document, you also select the connection documents to specify what the source and target data sources will be. For the Advanced RealTime activities, there is a user assistant which prompts you for input via dialog boxes for completing the form. User assistance is enabled by default. If you would like to disable this feature you can click the Turn User Assistant Off button. By disabling the user assistant wizard, you will be taken directly to the Advanced RealTime activity document rather than going through the dialog boxes. The batch activities in LEI do not utilize the user assistant. When creating one of these activity documents, you are taken directly to the document to fill in the appropriate parameters. Following is a quick introduction to each of the different types of activities that can be created within LEI. The activities are grouped into two categories, batch and Advanced RealTime activities. 6 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Batch LEI activities Batch LEI activities have been available with the LEI product from it’s original version. These activities continue to be available in LEI 6 and include: Admin-backup Creates a backup copy of the LEI Administrator database (decsadm.nsf) and optionally, the LEI Script Vault database (leivlt6.nsf). Admin-purge log Purges the LEI log database (leilog.nsf) of documents that are older than a specified number of days. Archive Used to reduce the number of documents in a specified database. The archive activity moves data from one database to another. As the records are moved into the target database, they are deleted from the source database. Command This activity allows you to execute an operating system command, a database command, or SQL commands. Direct transfer The direct transfer activity copies data from one database to another. The target database can be created during execution of the direct transfer. For example you could create a Domino database from a DB2 UDB database with this activity. Java Allows LEI to invoke a Java application. This Java application can utilize application logic outside of LEI, allowing you to perform more extensive manipulations on the data being transferred. Note: The LC Java classes have been withdrawn from the Domino 6 product and are not available to utilize through the Java activity in LEI 6. Polling Polling allows certain conditions to be monitored in a database. When the conditions are met, a subordinate activity is triggered. Replication Replication is a very powerful feature of LEI. It allows two different types of data sources to be synchronized. The replication activity is often used to synchronize a Domino database with a DB2 UDB database. For an example of a replication activity, see 9.2, “Replication activity” on page 264. Scripted A scripted activity provides the function of executing LotusScript Extensions for Lotus Connectors (LC LSX) commands. Using the LotusScript classes, you can extend the functionality available to other LEI activities such as direct transfer, polling, and replication. Scripted activities allow you to create customized routines that provide more control over source and destination data transfers. Note: The LEI LSX that was part of the previous LEI releases, has been merged with the LC LSX which comes with the Domino 6 server. All LEI-related LotusScript functionality is still available, you just have to use a different library. Chapter 1. Introduction to IBM Lotus Enterprise Integrator (LEI) 6 for Domino 7 For an example of a scripted activity, see 9.1, “Scripted activity” on page 256. Advanced RealTime activities Advanced RealTime activities are new to LEI 6. These new activities rely on the virtualization technology to provide real-time access to data external to Domino. The new Advanced RealTime activities available with LEI 6 include: Virtual agents Virtual agents are a new activity introduced in LEI 6 that enables stored procedures to be invoked and executed as if they were Domino agents. Virtual agents can be scheduled, triggered, or invoked manually. They can be run with or without parameters. Virtual documents Virtual documents are also new with LEI 6. They allow external records to appear to Domino as if they are actual documents stored in the Domino database. Virtual documents greatly expands the real-time capability that was provided in previous releases of LEI and DECS. This level of virtualization allows external data to participate in Domino views, greatly enhancing the functionality of Domino applications that are dependent on data stored in a back-end data source such as DB2 UDB. Virtual fields This activity provides the level of function that was previously available through DECS or LEI real-time activities. Virtual fields connect Domino forms to back-end data sources, allowing you to open, create, update, and delete external system data directly through the Domino application. The biggest difference between virtual documents and virtual fields is that virtual field activities require a key document to be stored in the Domino database. With virtual documents, no data is stored in the Domino database, it is 100% virtualized. For details and examples of using Advanced RealTime activities, see Chapter 8, “Advanced RealTime activities” on page 195. 1.3.3 Current limitations with using LEI 6 LEI 6 has come a long way in providing truly robust enterprise integration with the addition of virtual documents and virtual agents. The goal of virtualization is to provide seamless data transfers between Domino and external data sources such as DB2 UDB even when other applications external to Domino make changes to those external data sources. However, this ideal must give way somewhat to the realities of network and performance issues. To work efficiently with outside data, LEI must have a way to tell which records in the relational database were recently changed or deleted. To do this, and to store the header information that Notes requires as part of a document, a virtual document requires either additional fields, or a separate reference table, stored in the DB2 UDB alongside the records to be virtualized. Any outside process that updates the data, must also update the timestamp in the EIMODIFIED field; if not, LEI will not know that the record has been updated and the change will not be reflected in the Notes views until the view index is rebuilt. Likewise, when a record is deleted by an external process, the LEI accounting information must be updated in a specific way, or else the records will remain in the views. Refer to 8.1.4, “Deletion involving virtual documents” on page 199 for details of document deletion. Even if the LEI accounting information is not updated, updated records will be shown correctly when they are opened in a document window, and deleted records will give an error if users try to open them from a view. 8 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server If you require Notes views to be up to date and do not have the option of updating the timestamp, use Domino Designer to select the Notes view option to discard the index after every time it's used; that guarantees that the view will always be up to date. However, depending on the size of your database, this may be slow. 1.4 A comparison of DECS, DCRs, and LEI Figure 1-2 provides a summary of the functions that are available with DECS and LEI, depending on which release of Domino you are working with. As you can see, real-time access to back-end data was available in both DECS in Domino R4.6/R5.x and LEI 3.x. The LEI product, separately purchased, provides not only real-time access to back-end data, but also provides the rich functionality of data management activities such as replication, direct transfer, and the additional activities you see listed. In Domino 6, DECS continues to provide real-time access to back-end data with the core Domino server code, and additionally this real-time access can be accessed directly via field properties in the Domino Designer client through the new DCR technology support. The LEI 6 product continues to provide the batch data management activities that were provided with LEI 3.x. LEI has been enhanced significantly in Domino 6 to provide the new Advanced RealTime activities support for virtualizing fields, documents, and agents. These new activities also provide some Advanced RealTime features that include virtual attachments and integrated credentials. DECS R 4.6/R 5 LE I 3.x DECS D om ino 6 LE I 6 DCRs R eal-tim e R eal-tim e V irtual fields V irtual fields V irtual docum ents V irtual agents V irtual attachm ents Integrated credentials A dm in backup A dm in backup A dm in-purge log A rchive A dm in-purge log C om m and C om m and D irect transfer D irect transfer Java Java P olling P olling R eplication R eplication S crip t S crip ted A rchive D esig ner b as ed R eal-tim e acc ess C lassica l R eal-tim e activitie s Ad van ced R ealTim e activities Ad van ced R ealTim e feature s D ata m an ag em en t activities Figure 1-2 Feature comparison of DECS and LEI by release In Figure 1-2 we see that both virtual attachments and integrated credentials are Advanced RealTime features. This means you cannot create an LEI activity of a type virtual attachment or of a type integrated credentials. These features are additional enhancements available with the new virtualization technology added into LEI 6. You can only utilize the features of virtual attachments and integrated credentials through the three new Advanced RealTime activities of virtual fields, virtual documents, or virtual agents. Chapter 1. Introduction to IBM Lotus Enterprise Integrator (LEI) 6 for Domino 9 1.4.1 Advanced RealTime feature - virtual attachments The virtual attachment Advanced RealTime feature allows files and other objects to be stored in an external data source and appear as if they are Domino attachments. The actual attachment is stored in an external system but is indistinguishable from a native attachment to the end user and the developer. These attachments are stored as binary large object (BLOB) data types in DB2 UDB on the iSeries. Users and applications can perform any operation with virtual attachments that Domino supports for attachments it stores locally. This includes opening, saving, and also the new Domino 6 capability to edit attachments in place. Virtual attachments allow Domino databases to remain at a much more stable size because the attachments are stored in an external data storage device. They also make it easier to keep track of and organize attachments. For an example of using virtual attachments, see 8.10, “Example 5: Using virtual agents and virtual attachments” on page 237. 1.4.2 Advanced RealTime feature - integrated credentials The second Advanced RealTime feature available with LEI 6 is integrated credentials. This feature allows Domino IDs to be associated with back-end userids (credentials). In an LEI connection document, a userid and password are in essence hard coded into the connection document. This can create a few different problems: First, when the password for this userid expires, each connection document that contains this userid and password combination needs to be updated. A second issue that can be encountered is the lack of being able to track who really caused an update, delete, or insert to happen in a back-end database. This is a problem for businesses that as part of their security auditing practice, need to be able to track this level of detail. And finally, because there is only one userid and password provided in a connection document, the access level of that userid has to have the appropriate authority levels to perform all levels of data manipulation required against that file. This can be a security exposure because users who really only need read access to a back-end resource, will actually have update, insert, and delete authority to this file. Integrated credentials let you leverage your existing relational database security to prevent unauthorized viewing and editing via Notes. You must store user credentials in a Lotus Notes database, which uses document Reader access to prevent users from accessing the credential information of other users. You may let users update their own credential records, or you may use an LEI Replication activity to update the information from user tables in your relational database. Once the credentials database is in place, LEI can use the user's Notes ID as a key to look up their user ID and password in the external system, allowing them to view and edit only those records they are authorized to, without prompting them for an additional login. In addition, this lets the database system track which user made a revision. Additionally, when the password changes for a particular userid, there is only one database that needs to be updated, rather than needing to update each of the individual connection documents. There can be performance implications to using integrated credentials because connection pooling is less effective. Without integrated credentials, when a connection is made to a back-end DB2 UDB data source, multiple connections are created and placed in a pool. Any 10 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server users of the application are able to get faster access to the back-end resource because a connection can be taken from the connection pool. With integrated credentials, the ability to use connection pooling is somewhat limited. Because the userid and password used to connect into the back-end data source is changing from user to user, there is a reasonable chance that a connection in the pool does not match the credentials of the specific user who is requesting the connection. The overhead to establish the connection synchronously will have an impact on application and server performance, so keep this issue in mind when determining if integrated credentials is appropriate for your particular environment. For more details about integrated credentials, see 2.2.2, “Integrated credentials” on page 37. 1.5 What’s new with LEI 6.0 and LEI 6.0.1 LEI 6 was first introduced with Lotus Domino 6. The LEI product has received some enhancements in the follow-on release of LEI 6.0.1. The following section details what’s new with LEI 6 in general. We also include a section that details what is different for LEI 6.0.1 on the iSeries server. 1.5.1 What’s new in LEI 6 The information contained in this section is generic to all platforms that currently support the LEI 6.0.1 product. For details about what has changed specifically for the iSeries server, see 1.5.2, “LEI 6.0.1 on the iSeries server” on page 14. LEI product tied to release boundary Starting in Domino 6.0, the LEI product is bound to the release level. This is a change from past releases of LEI where the LEI 3.1 product for example would run on multiple releases of the Domino R5.x server. Starting in Domino 6.0, the level of LEI must match the release level. This means that LEI 6.0 will only work with Domino 6.0. Additionally, LEI 6.0.1 will only be able to be installed on a Domino 6.0.1 server, and so on. Addition of Advanced RealTime activities Advanced RealTime activities were first introduced in this chapter in 1.1, “A business case for LEI” on page 2 and are made possible through a new technology called virtualization. Virtualization allows data external to Domino to appear to the end user of the application as though it were native Domino data. There are three new Advanced RealTime activities: – Virtual documents – Virtual fields – Virtual agents Server-side browsing Previous versions of the LEI Administrator application used client-side browsing, which required LEI administrators to install back-end connectivity software on both the Domino server and their Notes workstation. For the iSeries, this meant installing a DB2 connect client on the PC where the LEI administration client used to create the connection and activity documents resided. This requirement goes away in LEI 6 due to server-side browsing. Development client retired Previous LEI versions also required developers to install a separate LEI Development client. Because of the server-side browsing and because the LC LSX (including the LEI LSX functions) is now a standard part of the Notes/Designer client, the LEI Development client is no longer required. Chapter 1. Introduction to IBM Lotus Enterprise Integrator (LEI) 6 for Domino 11 Improved user interface for LEI Administrator, activity documents, and connection documents For those of you that used both the DECS and LEI 3.x products, you were used to slightly different user interfaces, including which symbols were used to indicate the status of various activities. What you will find with LEI 6 is a user interface more similar to that available with DECS. As a result, the symbols used are more intuitive than those previously used by LEI. Additionally, the connection and activity documents have been modified to make them more intuitive as well. You will find these documents easier to fill out and more logically flowing. Retirement of the LEI.INI file Previous versions of LEI used a combination of the LEI.INI file and the NOTES.INI file for environment variable settings. The LEI.INI file has been retired in LEI 6 and all LEI-related variables now exist in the NOTES.INI file. Additionally, some LEI environment variable names have been changed and others have been retired. Following is a list of the variables that have been retired: – – – – – – LCINIDelete KitType LCINIGetString Directory LEIDirectory RemoteConsole LCTEST superseded by DCTEST Previous versions of LEI used a connectivity test tool called LCTEST. With the retirement of the LEI LSX, this connectivity test tool has been replaced with the new DCTEST tool. DCTEST is a client-side tool that verifies connectivity to a back-end data source. LotusScript changes The Scripted activity allows for manipulation of data sent to or returned from a connector. Previous versions of LEI provided a set of classes called the LEI LSX. This set of APIs is no longer available, all scripting needs to be done through the LC LSX classes. Any LotusScript code that contains the Uselsx “lsxlei” syntax will need to be updated to Uselsx “lsxlc”. Timestamp polling This is a new feature allowing polling to be based on a timestamp. This new feature is enabled in the Polling activity document by selecting to enable timestamp polling and then selecting a timestamp field associated with the connection the polling activity is configured to use. Retirement of EDA/SQL connector The EDA/SQL connector is no longer supported in the LEI 6 product. Retirement of Connection Broker metaconnector As a simplification of the LEI Administrator user interface, you no longer create a Broker metaconnection in the LEI Administrator. Instead, this capability can be enabled directly from the various activity documents using the Integrated Credentials option. The Broker metaconnector still exists for use from LC LSX code, however. For more details about integrated credentials see 2.2.2, “Integrated credentials” on page 37. 12 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Retirement of CGI interface The LEI CGI interface has been deprecated in LEI 6. The nleicgi.exe and leicgi files are no longer supported. LEI administrator file name change Past releases of LEI had an LEI administrator file name of leiadm.nsf by default. Users had the option of changing the file name to whatever they liked. In LEI 6, this is no longer the case. The name of the LEI administrator file has changed to decsadm.nsf, and the name of the file cannot be changed by the user. If the name of the file is changed, LEI 6 will not function correctly, it must remain as decsadm.nsf. The LEI template used to generate this file is leiadm.ntf. LEI script vault file name changes The LEI script vault name has changed as well. It is now leivlt6.nsf in LEI 6. The template used to generate this database is leivlt.ntf. Migration utility There is a migration utility built into the LEI 6 product. This utility is used to migrate LEI 3.x connection and activity documents to LEI 6. This migration is required for connection and activity documents created in previous versions of LEI to work with the LEI 6 product. The migration utility can be run during the installation and configuration of the LEI 6 product or it can be run separately at a later time of your choosing. This utility can also migrate scripts found in the Release 3.x LEI script vault (leivlt.nsf) to the LEI 6 script vault (leivlt6.nsf) in order to convert their format from using the LEI LSX classes to the LC LSX classes. For details about using the migration utility see Chapter 4, “Migrating from Lotus Enterprise Integrator 3.x” on page 87. Addition of browsing capabilities in metaconnectors Metaconnectors are special connections that can be built over connection documents. They wrap around a base connection document and provide additional functionality over the base connection. There are four metaconnectors available: – – – – Order Collapse/Expand Meter Trace Browsing functionality has been added to Metaconnectors in LEI 6. To use this new feature, you must select a metadata object (table, form, view, and/or procedure) in every connection that is used with the metaconnector. If connections referenced by the metaconnector do not have metadata selected, a message appears notifying you that no metadata has been selected in the connection reference in the metaconnector. Enable procedure output from stored procedures If your Advanced RealTime activity connects to a stored procedure instead of a table or view, then the stored procedure may return output values that you would like to store into the Notes document. For instance, a virtual fields activity might use the Create event to call a stored procedure that creates a record using the field values from the Notes document, and returns a sequential record identifier. Starting with LEI 6, some activity forms now contain an option, usually labeled ‘Enable Procedure Output’, which takes the stored procedure's output values and copies them to Notes fields. However, this capability is not yet programmed into all connectors. As of this writing, only the DB2 connector supports this option; it's planned for inclusion in the SAP R/3 Release connector. Chapter 1. Introduction to IBM Lotus Enterprise Integrator (LEI) 6 for Domino 13 Ability to e-mail activity log files as plain text Some of the previous versions of the LEI product allowed you to e-mail activity log files to designated recipients through a Notes rich text format as a doclink. In LEI 6, these activity log files can additionally be sent in plain text format. This is a nice feature for recipients who are receiving these messages from a pager or PDA device. Addition of integrated credentials database One of the Advanced RealTime features provided with LEI 6 is the usage of integrated credentials. Integrated credentials allows you to map a Domino user ID to a user ID and password on the back-end data source server. The lcired.ntf template is used to create this database. For more details about integrated credentials, see 2.2.2, “Integrated credentials” on page 37. 1.5.2 LEI 6.0.1 on the iSeries server LEI 6.0.1 is the first version of LEI 6 that is supported on the iSeries platform. There was a beta version of LEI 6.0 available for the iSeries, however the first official release of the product comes with LEI 6.0.1 on Domino 6.0.1. LEI is a separately purchased product. It does not come automatically with the Domino 6 server. The product installs on the iSeries server with the product ID of 5733-LEI. Because LEI is purchased through Passport Advantage® and not as an OS/400 licensed program product (LPP), the 5733-LEI product code is not an actual LPP. The 5733-LEI product ID is provided to identify LEI 6 product to the iSeries server and to allow program temporary fixes (PTFs) to be applied. There are very few changes to LEI 6.0.1 for the iSeries. The LEI 6 product is a cross-platform product, and therefore the support provided for the iSeries is nearly the same as that provided for other platforms. Let’s look at the few differences that do apply to LEI 6.0.1 on the iSeries server: IBM product family name changes The iSeries platform went through a name changes a few years ago. Previously the iSeries was known as the AS/400. The name change has been adopted in Domino 6 and LEI 6, so all references to the product name now reflect the iSeries name. Retirement of authority propagation activity The LEI 3.x product contained an activity that was only offered on the iSeries platform. This was the authority propagation activity. The authority propagation activity allowed authorities to be transferred between a DB2 UDB relational database and a Domino database. This activity was rarely used and thus has been withdrawn with the LEI 6.0.1 product. Deprecation of capture delete support in the replication activity Previous versions of LEI provided an iSeries specific function available with the replication activity called capture delete. Capture delete provided the ability to capture deleted documents or records being deleted and move them to a staging area (a table or a form) to be read and applied to the corresponding replica database the next time the replication activity was run. This function has been deprecated in LEI 6 and therefore any replication activity documents that contain capture delete function need to be modified before they will run on an LEI 6.0.1 server. 14 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 1.6 Terminology We have all found by working on different technologies that they each have their own unique descriptions and terms when describing different functions and features. This no exception when it comes to the terminology between DB2 UDB and Lotus Domino. This section will help to explain and correlate the terminology between native DB2 UDB files on the iSeries, SQL, LEI and Lotus Domino terminology. 1.6.1 iSeries relational database versus LEI verses Lotus Domino Relational databases can be created in one of two ways on the iSeries. iSeries DB2 UDB relational databases can be created from data description specification (DDS) source files or they can be created using the SQL command language. You will see these differences reflected in the explanation of the terminology differences in this section. Table 1-1 shows a side-by-side comparison of all four environments. Starting at the highest level of containment type of object going down to the lowest level of object, a comparison is made between these different environments. Table 1-1 Terminology across DB2 UDB for iSeries, LEI and Lotus Domino iSeries Relational Database iSeries SQL LEI Lotus Domino Library Collection Owner Database Record format Metadata Metadata Form Physical file Table Connection document View Logical file View Connection document View Record Row Record Document Field Column Field Field High level language program Stored procedure Stored procedure Agent Query Statement Statement Selection formula Let’s take each of the columns in Table 1-1 and examine them in more detail. Library, collection, owner, and database The top level of container is an object called a library in iSeries relational database terminology. A library is a holder of other objects. These objects could be physical files, logical files, program objects, stored procedures, and so on. In the context of this discussion the comparable terminology in the SQL world is a collection. Within the context of LEI, the terminology used is owner. The owner is the creator of the objects that will be specified to be connected to within an LEI connection document. The term owner is really the name of the person or userid that created the set of objects in a database. For Lotus Domino, the comparable structure is a Domino database. A Domino database is the highest level of container in the Domino world. Record format, metadata, and form An iSeries library will contain many different objects, including physical files. These physical files are created from DDS source files that contain one or more record formats. These record formats describe how the file will look, how many columns the table will have, the data types Chapter 1. Introduction to IBM Lotus Enterprise Integrator (LEI) 6 for Domino 15 for each column, and so on. The comparable terminology for SQL is metadata. The metadata is information that describes a table. LEI uses the same terminology to describe the data it is manipulating. In Lotus Domino, a form describes the metadata. A form contains a set of fields and their data types. Physical file, table, connection document, and view Going the next step down, we look at what results from the record format, metadata, and form. Here we find a physical file in iSeries terminology. You will find the term physical file used synonymously with file. Both are referring to files that contain data, for example a customer database. The comparable structure found in SQL is a table. The comparable item in LEI is a connection document. A connection document tells LEI which entity to connect to. In Lotus Domino terminology, the closest terminology is a view. A Domino view contains data that is specified by the view selection formula. A Domino view can contain any combination of documents that meet the view criteria. A view can be built over all documents in the Domino database, or it can be created using very specific selection criteria. Logical file, view, and connection document A logical file is a database file that describes how data records contained in one or more physical files are presented to a program. A logical file does not contain data records. The data records are contained in the physical files associated with the logical file. Logical files access physical file data records through one or more logical file members. Each logical file member describes the data contained in one or more physical file members, and each logical file member has its own access path to the data. The comparable terminology used in the SQL world is a view. A view is a table-like object that provides an alternative means to access data in one or more underlying tables. Views and logical files are often used to provide faster access to records in DB2 UDB relational databases. In LEI terminology, the comparable structure is a connection document. Connection documents can be created over logical files or views as well. The comparable structure in Domino is a view. Again, views can be built over all documents or a subset of documents in a Domino database. Record, row, and document Continuing down the levels of granularity, the next layer is called a record in iSeries relational database terminology and a row in SQL. This is very similar terminology to what we see in LEI. LEI refers to this level as a row. In Domino, the comparable terminology is a document of data or a row of data. Using a customer database as an example, at this level, a record of data or a document will provide details about a specific customer. Things that may be included are their customer number, first and last name, address, phone number, e-mail address, and so on. Field and column Using the customer example, the next level of granularity is an individual field or column of data. The iSeries relational database term for this level is a field. This terminology is consistent across the LEI and Lotus Domino environments. The comparable SQL terminology is a column. Examples of individual fields or columns of data would be the customer’s number or the customer’s name. High level language program, stored procedure, and agent The last two rows in the table list different ways to extract data from DB2 UDB or Lotus Domino. A high level language (HLL) program is a program written in any programming 16 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server language supported on the iSeries. The majority of the programs running today on the iSeries are RPG programs. These programs manipulate DB2 UDB databases by retrieving relative record numbers (RRN) for the data and manipulating that data as appropriate. These HLL programs can be turned into stored procedures and executed through SQL. A stored procedure is a program that has been transformed so it can be called from an SQL CALL statement. Stored procedures can also be used in LEI to manipulate DB2 UDB databases. The comparable application logic in a Lotus Domino environment is an agent. Query, statement, and selection formula Another way data is extracted, manipulated, added to, or removed from a relational database is through a query. In SQL a statement is used to select, update, insert, or delete data. SQL statements can be performed on either iSeries DB2 UDB relational databases or on iSeries SQL tables. LEI uses a statement to manipulate the back-end data as well. This statement is actually an SQL statement. The comparable terminology in Lotus Domino is selection formula. This selection formula can be provided through @functions, @commands, or a programming language such as LotusScript or Java. 1.6.2 DB2 UDB iSeries terminology differences Now that we have a basis for the terminology differences between Lotus Domino and relational databases on the iSeries defined, the next step is to explain how database terminology differs on the iSeries platform compared to other hardware platforms. Table 1-2 shows the correlation between iSeries relational database terminology and that found on other hardware platforms. You will find this table to be very helpful when filling out LEI connection documents. The terminology used in the connection documents when creating a DB2 data source matches the ‘Other platforms’ column in this table. Table 1-2 Correlation between iSeries database terminology and other platforms Other platforms iSeries platform Database Relational database directory entry Owner, schema Library or collection Name File or table Dot (.) for file separator Forward slash (/) for file separator Database and relational database directory entry What is referred to as a database on other platforms correlates to a relational database directory entry on the iSeries. Until very recently on the iSeries, you could not have two libraries or collections with the same name on a system. So the concept of a database for the iSeries is at a system level, which is a relational database directory entry. To display what the relational database directory entry is for a given iSeries, use the Work with Relational Database Directory Entries (WRKRDBDIRE) CL command. A relational database directory entry is synonymous to a label for your iSeries server. You will connect into a specific iSeries server and access any number of files residing in the multitude of libraries and collections on the system. A relational database directory entry can be created as *local or *remote. The *local entry will identify the iSeries server you are currently working on and a *remote entry will identify another iSeries server you would like to be able to access from this iSeries server. For more details about creating relational database directory entries see 5.2.3, “Creating a DRDA connection to a remote iSeries server” on page 109. Chapter 1. Introduction to IBM Lotus Enterprise Integrator (LEI) 6 for Domino 17 OS/400 Version 5 Release 2 added support for allowing multiple databases to reside on the same iSeries server. This support was enabled through independent disk pools. Independent disk pools can be setup as unique databases or schemas. For details about this new capability, see the iSeries Information Center at: http://www.ibm.com/eserver/iseries/infocenter Select the appropriate country (or region) and language and then click Database -> Administrative topics -> Work with multiple databases. Owner and library or collection Another term you will see when creating LEI connection documents is owner. Schema is a comparable term used on platforms that support databases such as Oracle. The comparable structure this relates to on the iSeries is a library or a collection. Name and file or table Once you have selected the library or collection, you will be asked to provide the name of the database you want to connect to. This name relates to a file or table on the iSeries server. File separators If you have an iSeries background, you are familiar with using a forward slash (/), to separate library and file values, this is the traditional iSeries naming syntax. Standard SQL naming syntax uses a dot (.), as the separator value. LEI uses the standard SQL naming syntax. The forward slash (/) file separator is not allowed when delineating collections and tables in connection documents or when forming SQL statements to manipulate the relational data in activity documents. 1.7 Data type conversions/mappings One of the most difficult parts of any enterprise integration project is understanding how data types in one data source map to data types in a disparate data source. The information in this section is here to provide you with information about what the different data types are for SQL data files and OS/400 native physical files in addition to the data types available within the Domino Designer client. We then provide tables that offer guidelines on common mappings between the various data types in DB2 UDB and comparable data types in Domino Designer. Important: The information in the data mapping guidelines in Table 1-6 on page 21 and Table 1-7 on page 23 are not absolute lists of every valid combination, rather they are meant to provide guidance on some common mappings you can use when exchanging data between Domino and DB2 UDB on the iSeries. The first set of tables, Table 1-3, Table 1-4, and Table 1-5, list the valid data types for iSeries SQL, iSeries native physical files, and Domino Designer data types. All valid data types are listed along with descriptions for each. 1.7.1 iSeries SQL data types The data types listed in Table 1-3 are all of the valid SQL data types available when creating an SQL table on the iSeries server. 18 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Table 1-3 iSeries SQL data types SQL data type Description INTEGER (INT) 4 byte integer SMALLINT Small integer, 2 bytes BIGINT Big integer, up to 19 digits FLOAT Floating-point number NUMERIC Zoned decimal number DECIMAL (DEC) Packed decimal number CHARACTER (CHAR) Fixed-length character string, up to 32,766 characters VARCHAR Variable-length character string, up to 32,740 characters DATE Three-part value (year, month, day) designating a point in time under the Gregorian calendar. TIME Three-part value (hour, minute, second) designating a time of day under a 24-hour clock. TIMESTAMP Seven-part value that designates a date and time under the Gregorian calendar. GRAPHIC Graphic data type VARGRAPHIC Variable-length graphic data type LONG VARGRAPHIC Variable-length graphic string, whole maximum length is determined by the amount of space available in the row. REAL Single precision floating-point DOUBLE PECISION (DOUBLE) Double precision floating-point CLOB Variable-length character string in the range of 1 byte through 2 gigabytes. BLOB Variable-length binary string in the range of 1 byte through 2 gigabytes DBCLOB Variable-length double-byte character string in the range of 1 byte through 1 gigabytes DATALINK Variable-length string which contains a Uniform Resource Locator (URL). 1.7.2 iSeries native physical file data types Table 1-4 lists all of the valid data types when creating an iSeries native physical file from data description specifications (DDS). Table 1-4 iSeries native physical file data types Native physical file data type Description Packed decimal Numeric data type that stores numbers using a representation of the number with one digit per half byte. Zoned decimal Numeric data type that stores numbers using a representation of the number with one byte per digit. Chapter 1. Introduction to IBM Lotus Enterprise Integrator (LEI) 6 for Domino 19 Native physical file data type Description Binary Numeric data type that stores numbers using a representation of the number in base 2. Floating point Numeric data type tat stores real numbers using a representation of the number as a mantissa and exponent. Character Character data up to 32766 bytes. Date Stores values for calendar dates. Time Stores values for time. Timestamp Stores values for system timestamps, a combination of date and time data types. Hexadecimal Stores data as encoded bits. DBCS-only Contains only DBCS data. DBCS-either Contains only DBCS or alphanumeric data. DBCS-open Contains both DBCS and alphanumeric data. DBCS data is distinguished from alphanumeric data with shift-control characters. DBCS-graphic Contains only DBCS data with no shift-control characters. 1.7.3 Domino Designer data types The information in Table 1-5 lists all of the data types you will find available in Domino Designer when working with the field properties of a particular field. Table 1-5 Domino Designer data types 20 Domino Designer data type Description Text Character data Date/Time Datetime Number Integer, float, currency, and numeric Dialog list Field containing a list of choices. Check box Field containing a list of choices, each with a box users click to select. Radio button Field containing a list of choices, only one choice can be selected by clicking the button next to that choice. Listbox Field containing a list of choices, each choice is displayed with an expandable list box. Combobox Choices are displayed with a drop-down list box. Rich text Can contain text, graphics, attachments, and objects. Authors Allows you to control who can edit specific documents. Names Use to display Notes user’s names. Reader Allows you to control who can read specific documents. Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Domino Designer data type Description Password A text field that maintains a user’s privacy by displaying each character a user enters as an asterisk on the screen. Formula Fields that contain formula language to provide customized or dynamic field values. Time zone Used to display a drop-down list of all available time zones in the world. Rich text lite Allows you to control which types of objects can be inserted into the rich text field. Color Field that lets you display a color picker on a form. 1.7.4 Data type mapping guidelines Table 1-6 shows how DB2 UDB data types are converted when they are manipulated by LEI. This information is shown in the middle column. The third column in the table provides guidance on comparable data types in Domino Designer when comparing how DB2 UDB data types map to Lotus Domino data types. Table 1-6 Data type conversion/mapping of DB2 UDB by LEI DB2 UDB data source Comparable LEI data type Lotus Domino Designer data type Integer (Int) Int Type = Number Number format = Decimal Decimal places = 0 fixed SMALLINT Int Type = Number Number format = Decimal Decimal places = 0 fixed BIGINT Numeric Type = Number Number format = Decimal Decimal places = 0 fixed Float Float Type = Number Number format = Decimal or scientific3 Decimal places = x fixed or varying Numeric Numeric Type = Number Number format = Decimal Decimal places = x fixed or varying Decimal Numeric Type = Number Number format = Decimal Decimal places = x fixed or varying Character Text Text or rich text2 Date Date Time Type = Date/Time Check Display Date Show = Only month, day and year Special = 4 digit year for 21st century Calendar = Gregorian Time Date Time Type = Date/Time Check Display Time Show = Hours, minutes, and seconds Chapter 1. Introduction to IBM Lotus Enterprise Integrator (LEI) 6 for Domino 21 DB2 UDB data source Comparable LEI data type Lotus Domino Designer data type TIMESTAMP Date Time Type = Date/Time Check Display Date Show = Only month, day and year Special = 4 digit year for 21st century Calendar = Gregorian Check Display Time Show = Hours, minutes, and seconds Graphic Binary Rich text VARGRAPHIC Binary Rich text LONG VARGRAPHIC Binary Rich text Real Float Type = Number Number format = Decimal or scientific Decimal places = varying Double Precision (DOUBLE) Float Type = Number Number format = Decimal or scientific Decimal places = varying CLOB Text Text or rich text2 BLOB Binary Rich text DBCLOB Binary Rich text Datalink Binary Text or rich text2 Packed decimal1 Numeric Type = Number Number format = Decimal Decimal places = x fixed or varying Zoned decimal1 Numeric Type = Number Number format = Decimal Decimal places = 0 fixed Binary1 Int Type = Number Number format = Decimal Decimal places = x Hexadecimal1 Text Text DBCS-only1 Text Text or rich text2 DBCS-either1 Text Text or rich text2 DBCS-open1 Text Text or rich text2 DBCS-graphic1 Binary Rich text 4 1 = These are data types available only from creating a field in DDS on the iSeries server. 2 = Data type selected depends on the size of data in the DB2 UDB data source. 3 = Decimal is a better choice for avoiding rounding errors. 4 = The precision level for the iSeries TIMESTAMP data type is 24 characters and the precision level for the Domino data field in 16 characters. The middle column shown in Table 1-7 shows how LEI interprets the different Domino Designer data types. Additionally, the third column provides some guidelines on data types in DB2 UDB that map to the specified Domino Designer data type. 22 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Table 1-7 Data type conversion/mapping of Domino by LEI Lotus Domino data type Comparable LEI data type DB2 UDB data type Text Text Character VARCHAR CLOB Date/Time Date Time TIMESTAMP Date Time Number Float Integer SMALLINT BIGINT FLOAT NUMERIC DECIMAL REAL DOUBLE Packed decimal Zoned decimal Binary Dialog list Text Character VARCHAR CLOB Check box Binary BLOB Graphic1 VARGRAPHIC1 LONG VARGRAPHIC1 DBCS-graphic1 Radio button Text Character VARCHAR CLOB Listbox Text Character VARCHAR CLOB Combobox Text Character VARCHAR CLOB Rich Text Binary BLOB DBCLOB1 Graphic1 VARGRAPHIC1 LONG VARGRAPHIC1 DBCS-graphic1 Authors Text Character VARCHAR Names Text Character VARCHAR Readers Text Character VARCHAR Password Text Character Chapter 1. Introduction to IBM Lotus Enterprise Integrator (LEI) 6 for Domino 23 Lotus Domino data type Comparable LEI data type DB2 UDB data type Formula Text Character VARCHAR CLOB Time zone Text Character VARCHAR Rich text lite Binary BLOB DBCLOB1 Graphic1 VARGRAPHIC1 LONG VARGRAPHIC1 DBCS-graphic1 Color Text Character VARCHAR CLOB 1= The data in these field types is stored as double-byte data even if single byte data is inserted. 24 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 2 Chapter 2. Architectural scenarios and considerations This chapter discusses different possible architectural scenarios for implementing Lotus Enterprise Integrator (LEI) 6. Considerations for security and performance when designing a solution based on LEI 6 are also covered. © Copyright IBM Corp. 2003. All rights reserved. 25 2.1 Architectural scenarios The architectural scenarios presented in this chapter are examples of how an LEI 6 infrastructure could be implemented. These scenarios are meant to present possible scenarios that address a specific need and are not a complete list of all permutations and combinations of designs. In order to have a solution based on LEI 6 that meets your specific environment, it is possible to mix different components of the scenarios presented here to produce one complete solution. 2.1.1 Scenario 1: Single iSeries server This scenario, as shown in Figure 2-1 is a simple example with all components on one iSeries server in a single OS/400 logical partition (LPAR). This type of architecture may be most practical for test or pilot environments. There is a performance advantage with this architecture because all components are on the same physical machine, which eliminates overhead from network communication. The one iSeries server hosts the Domino server, a Notes/Domino application, an LEI server, as well as the DB2 UDB data that is accessed by LEI. For virtual documents or virtual fields, when an end user accesses a Notes document through a Web browser or Notes client, the DB2 UDB data will be accessed in real time and displayed in the document. For data transfer activities, the data would either have been directly transferred or replicated between Domino and DB2 UDB. iSeries server Domino server LEI LEI connection document Notes/Domino application LEI connection document Application Read/Update files Line of business applications DB2 UDB Figure 2-1 Single iSeries server scenario Description of components The following describes the components in this scenario: End users: Users access the Notes/Domino application from a Web browser or Lotus Notes client. Domino 6.0.1 server: The Domino server hosting this Notes/Domino application. The LEI server runs as a set of tasks on the Domino server. 26 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server LEI 6.0.1: The LEI Administrator database is on the Domino server and is used to create and maintain LEI connection and activity documents. A connection document provides information allowing LEI to read and write to a particular data source, which may be a Notes database and form, a DB2 UDB database table or view, or any other supported database. Activity documents create correspondences between the data in different connections. There may be many different connection documents, and many different activities, relating different tables to different Notes forms (or even to the same form, if you need it to pull data from more than one table). For more information about connection documents, see Chapter 6, “Connection documents” on page 153. For more information about activity documents, see Chapter 8, “Advanced RealTime activities” on page 195 and Chapter 9, “Batch activities” on page 255. DB2 UDB: The data required by the Notes/Domino application may be distributed in different libraries and files on the iSeries server. Activities supported All the LEI activity types are supported in this environment. 2.1.2 Scenario 2: Remote database server The architectures discussed in this section are the most common in real world situations since there is normally a physical separation between LEI and DB2 UDB. These designs may be used when there is a business need to get data from various remote locations into one central point like a Notes/Domino application.The reverse may also be true where the data is initially entered into multiple Notes/Domino applications and is then moved to one or many DB2 UDB files. The examples in Figure 2-2, Figure 2-3 and Figure 2-4 are three different architectures that would allow for the access of remote database data. Domino, LEI and DB2 UDB do not need to be on the same platform which allows for greater flexibility. For example, in Figure 2-3 we show Domino and LEI on an xSeries server accessing DB2 UDB data on an iSeries server. There are many other permutations and combinations than the three scenarios presented here that would allow for remote data access. These scenarios are intended to give you an idea of the possibilities. Figure 2-2 shows accessing DB2 UDB data on an iSeries server from a Notes/Domino application on another iSeries server. See 5.2, “iSeries to iSeries” on page 104 for detailed information about how to configure the connection between the two iSeries server. Chapter 2. Architectural scenarios and considerations 27 iSeries server 1 iSeries server 2 Domino server LEI connection document Notes/Domino application LEI DRDA connection LEI connection document Application files Read/Update Line of business applications DB2 UDB Figure 2-2 iSeries server to a remote database on another iSeries server Figure 2-3 shows that data on an iSeries server could be accessed by a Notes/Domino application running on an xSeries server. See 5.3, “xSeries server to iSeries server” on page 120 for detailed information about how to configure the connection between an xSeries server and an iSeries server. xSeries server iSeries server Domino server LEI LEI connection document LEI connection document Notes/Domino application DRDA connection DB2 UDB Read/Update Application files Line of business applications Figure 2-3 xSeries server to a remote database on an iSeries server Figure 2-4 shows a Domino application running on a iSeries server accessing data in DB2 UDB on another platform (that is, pSeries). 28 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server iSeries server pSeries server Domino server LEI LEI connection document Notes/Domino application DRDA connection LEI connection document DB2 UDB Application files Read/Update Line of business applications Figure 2-4 iSeries server to a remote database on an pSeries server Description of components The following describes the components in these scenarios: End users: Users access the Notes/Domino application from a Web browser or Lotus Notes client. Domino 6.0.1 server: The Domino server hosts this Notes/Domino application. The LEI server runs as a set of tasks on the Domino server. LEI 6.0.1: The LEI Administrator database is on the Domino server and is used to create and maintain LEI connection and activity documents. A connection document provides information allowing LEI to read and write to a particular data source, which may be a Notes database and form, a DB2 UDB database table or view, or any other supported database. For more information about connection documents, see Chapter 6, “Connection documents” on page 153. Activity documents create correspondences between the data in different connections. There may be many different connection documents, and many different activities, relating different tables to different Notes forms (or even to the same form, if you need it to pull data from more than one table). For more information about activity documents, see Chapter 8, “Advanced RealTime activities” on page 195 and Chapter 9, “Batch activities” on page 255. A DRDA® connection is required between the LEI server and the DB2 UDB server(s). See Chapter 5, “Base connectivity” on page 103 for details about how to configure this. DB2 UDB: Different activities can access various databases on the one DB2 UDB server. The server shown in Figure 2-4 is a pSeries server but an xSeries server or zSeries server are also possibilities. Activities supported All the LEI activity types are supported in this environment. 2.1.3 Scenario 3: LEI 6 integration with Domino R5 applications This scenario is an example of how Domino R5 applications can be integrated with relational data using LEI 6. This design could be useful if you have an existing Domino R5 application and need to take data from the application and put it into DB2 UDB. The reverse is also possible where you take DB2 UDB data and put it into your Domino R5 application. Chapter 2. Architectural scenarios and considerations 29 The Advanced RealTime activities are not supported in this scenario, however the direct transfer and replication activities are. The Advanced RealTime activities require the Domino 6 on disk structure (ODS) in order to work. In this scenario the application is a Domino R5 application that runs on a Domino R5 server and uses the Domino R5 ODS. We show here how an existing Domino R5 application can use LEI 6 without making any changes or upgrading the existing application. This scenario has multiple Domino servers, on multiple platforms, as well as different versions of Domino (R5 and 6). LEI is used as middleware to access the data and put it into a single replica copy of the application. Domino replication would then take over to synchronize replicas of the database on other Domino servers. A copy of the Domino application does not need to exist on the LEI server. If a Domino application is distributed to multiple versions of Domino you will need to take the necessary steps to make sure that the application runs on the different servers and that the on disk structure (ODS) is not changed. In the scenario shown in Figure 2-5, we keep the Domino R5 application in the R5 ODS, but distribute it to a Domino 6 server. Domino applications can run on multiple platforms, therefore you can distribute your applications onto different platforms (iSeries, pSeries, xSeries, zSeries) and synchronize them using Domino replication. iSeries server 2 (USA) User accesses via Notes or Web application Domino 6.0.1 server Notes/Domino R5 application Domino replication (30 minutes) iSeries server (Australia) xSeries server (Australia) Domino 6.0.1 server LEI connection document LEI 6.0.1 pSeries server (Paris) Domino R5 server Domino R5 server Notes/Domino R5 application Notes/Domino R5 application Domino replication (hourly) LEI connection document Application Read/Update files Line of business applications User accesses via Notes or Web application zSeries server (New Delhi) Domino replication (daily) Domino R5 server Notes/Domino R5 application DB2 UDB User accesses via Notes or Web application Figure 2-5 Integrating Domino R5 applications with LEI 6 Description of components The following describes the components in this scenario: End users: Users access the Notes/Domino application from a Web browser or Lotus Notes client. 30 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Domino 6.0.1 server: The LEI server runs as a set of tasks on the Domino server. The Domino R5 application does not necessarily need to be on the LEI 6 Domino server. If the Domino R5 application is put onto any of the Domino 6 servers, the necessary steps to make sure that the ODS of the application is not changed will need to be done. Domino R5 server: The Domino R5 servers are used to host different replica copies of the Notes/Domino R5 application. In Figure 2-5, one R5 server is accessed by the LEI server, and a LEI direct transfer or LEI replication activity is done between DB2 UDB and this copy of the R5 application. LEI 6.0.1: Several connection documents can exist between various forms in the Domino application and various tables in DB2 UDB. For more information about connection documents, see Chapter 6, “Connection documents” on page 153. Several activity documents may also exist between the Domino application and DB2 UDB. DB2 UDB: Figure 2-5 shows the LEI server and DB2 UDB on the same physical system. However, the DB2 UDB data could be remote as in shown in 2.1.2, “Scenario 2: Remote database server” on page 27. Activities supported The following activities are supported in this environment: Direct transfer Replication Archive For an example of a replication activity see 9.2, “Replication activity” on page 264. 2.1.4 Scenario 4: Decentralized Advanced RealTime access This scenario is an example of an architecture that would allow for real time access to DB2 UDB data across distributed replicas of a Notes/Domino application. In this scenario all replicas access the same DB2 UDB data directly. All replicas would be instantly updated if a change is made in the DB2 UDB data. This scenario would be appropriate when there is a Notes form in an application that requires real time access to data. Because of the performance overhead, the form should be one that is accessed relatively infrequently. An example of this scenario would be an expense reporting application that has a form with current exchange rates approved by the company. The approved rates are stored in a DB2 UDB file. The distributed Notes/Domino application needs to have instant access to the approved exchange rates that are stored in the single DB2 UDB file. The exchange rate form is accessed as part of the bigger application, and is accessed relatively infrequently. This scenario, as shown in Figure 2-6, can be used to distribute an application that uses the virtual fields or virtual document activities. In this scenario all replicas of the database on every Domino server has real time access to the DB2 UDB data. This is opposed to a single server having live access to the data, and then using regular Domino replication to synchronize the data. With this scenario, all replicas would be instantly synchronized if data in the application on any server changes. In order to do this, every server needs to have a separate copy of LEI installed with its own copy of the LEI Administrator database (not a replica copy). Every server has a virtual field or virtual document activity running against it’s own replica copy of the Notes/Domino application. All replicas point back to the same DB2 UDB files. Chapter 2. Architectural scenarios and considerations 31 iSeries server 2 User accesses via Notes or Web application Domino 6.0.1 server LEI 6.0.1 iSeries server pSeries server Domino 6.0.1 server LEI 6.0.1 LEI connection document Domino 6.0.1 server Notes/Domino 6 application LEI connection document Application files LEI connection document Notes/Domino 6 application LEI 6.0.1 xSeries server LEI connection document Domino 6.0.1 server LEI connection document LEI connection document LEI connection document Notes/Domino 6 application LEI 6.0.1 LEI connection document Notes/Domino 6 application DB2 UDB User accesses via Notes or Web application Figure 2-6 Multiple Domino replicas using Advanced RealTime activities Description of components The following describes the components in this scenario: End users: Users access the Notes/Domino application from a Web browser or Lotus Notes client. Domino 6.0.1 server: The LEI server runs as a set of tasks on the Domino server. Each Domino server has a replica copy of the Notes/Domino application. Each server also has LEI 6.0.1 installed with a separate LEI Administrator database. LEI 6.0.1: All LEI servers have connection documents pointing back to the same DB2 UDB files. All LEI servers will also have a connection document that would point to their respective replica copy of the Notes/Domino application. For more information about connection documents, see Chapter 6, “Connection documents” on page 153. A virtual fields activity document would be setup in each LEI Administrator database. DB2 UDB: The diagram in Figure 2-6 shows the LEI server and DB2 UDB on the same physical system, however the DB2 UDB data could be remote as in 2.1.2, “Scenario 2: Remote database server” on page 27. Activities supported The virtual fields Advanced RealTime activity is supported in this environment. Using virtual document activities in this environment against the same data will interfere with each other. 32 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Note: In this scenario, the LEI Administrator databases and the application databases are created individually; they're not replicas of each other, though they may share the same design. If you use a virtual fields activity in this configuration, and you let Notes store any DB2 fields other than the key fields, you should have a timestamp column in the data and use a replication activity to keep the Notes documents in the different copies of the application up to date. For some examples of a virtual fields Advanced RealTime activity see Chapter 8., “Advanced RealTime activities” on page 195. 2.1.5 Scenario 5: Advanced RealTime in a hub and spoke environment This scenario is an example of how LEI Advanced RealTime activities can be combined with Domino replication to distribute an application that uses virtual documents or virtual fields. The major difference between this scenario and the scenario described in 2.1.3, “Scenario 3: LEI 6 integration with Domino R5 applications” on page 29, is that in this design both the Notes/Domino application and all of the Domino servers are version 6.0.1. With this design, one replica of the Notes/Domino application is virtualized, and all other replicas store the data natively. This architecture will be particularly useful if you have two groups of users, one group that needs real time access to DB2 UDB data through the Notes/Domino application, and the second group that needs access to the DB2 UDB data but not real time access. The second group of users will access the Notes/Domino application on the replica server while, the first group that needs real time access will use the replica of the application on the Domino server with LEI. As shown in Figure 2-7, only one LEI server is used and a single replica of the Notes/Domino application has real time access to DB2 UDB data. All other replicas of the application use regular Domino replication to synchronize. If changes are made on any of the replica copies of the application, those changes will be reflected in DB2 UDB when replication occurs with the replica copy of the application that is virtualized by LEI. In this scenario the main point of failure is the one LEI server. Precautions have to be taken to minimize the risk of the LEI server crashing. If the LEI server does crash, new documents added to replicas of the application may not get added to the DB2 UDB tables even after the LEI server is back on-line. For example, in Figure 2-7, if the LEI server crashes and documents are added to the replica of the Domino application on the xSeries server, if the xSeries Domino server and iSeries LEI Domino server replicate, these new documents will not get added into the DB2 UDB tables. The new documents will be regular Domino documents and not virtualized. Chapter 2. Architectural scenarios and considerations 33 pSeries server 1 iSeries server 2 Domino 6.0.1 server Domino 6.0.1 server Notes/Domino 6 application Notes/Domino 6 application iSeries server Domino replication Domino 6.0.1server LEI 6.0.1 Domino replication xSeries server 2 LEI connection document Notes/Domino 6 application Domino replication LEI connection document DB2 UDB Domino 6.0.1 server Notes/Domino 6 application Domino replication Read/Update Application files pSeries server 2 Line of business applications Domino 6.0.1 server Notes/Domino 6 application Figure 2-7 Advanced RealTime activities in a hub and spoke environment Description of components The following describes the components in this scenario: End users: Users access the Notes/Domino application from a Web browser or Lotus Notes client. Domino 6.0.1 server: The LEI server runs as a set of tasks on the Domino server. There is a replica copy of the Notes/Domino application on one server that has real time access to DB2 UDB data. All other replicas of the application do not have real time access to the DB2 UDB data, but use native Domino replication for updates. LEI 6.0.1: Several connection documents can exist between various forms in the Domino application and various tables in DB2 UDB. Several activity documents may also exist between the Domino application and DB2 UDB. DB2 UDB: The diagram in Figure 2-7 shows the LEI server and DB2 UDB servers on the same physical system, however the DB2 UDB data could be remote as shown in 2.1.2, “Scenario 2: Remote database server” on page 27. Activities supported The following Advance RealTime activities are supported in this environment: Virtual documents Virtual fields For more information and examples of Advance RealTime activities see Chapter 8, “Advanced RealTime activities” on page 195. 34 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 2.1.6 Scenario 6: Accessing multiple relational databases from iSeries This scenario is an example of the possibility of combining two LEI servers in order to access data in relational databases other than DB2 UDB. LEI 6.0.1 for iSeries does not currently support access to any relational databases other then DB2 UDB. Note: Future releases of LEI 6 for iSeries will have functionality to allow for access to Oracle, Microsoft SQL server, Sybase, and Informix®. If access to multiple relational databases is required with 6.0.1 on iSeries, two LEI servers could be configured. One LEI server on iSeries for access to DB2 UDB data and another on an xSeries server that would access other relational databases such as Oracle. In this scenario, as shown in Figure 2-8, both LEI on the iSeries server and LEI on the xSeries server have connection documents pointing to the same Notes/Domino application. They would also each have connection documents pointing to the various relational databases such as Oracle and DB2 UDB. xSeries server Domino 6.0.1 server LEI 6.0.1 LEI connection document LEI connection document iSeries server Domino 6.0.1 server LEI 6.0.1 LEI connection document Notes/Domino application LEI connection document DB2 UDB xSeries server 2 Oracle Application files Read/Update Line of business applications Application tables Figure 2-8 Accessing multiple relational databases using iSeries and xSeries Description of components The following describes the components in this scenario: End users: Users access the Notes/Domino application from a Web browser or Lotus Notes client. Domino 6.0.1 server: There are two Domino servers in this scenario, one on the iSeries server and the other on an xSeries server. Both Domino servers have LEI 6.0.1 installed. Only the Domino server on iSeries hosts the Notes/Domino application. LEI 6.0.1: There are two LEI servers, one on the iSeries server and the other on an xSeries server. The LEI server on iSeries is used to access data from DB2 UDB and the xSeries LEI server is used for access to data in other relational databases. Chapter 2. Architectural scenarios and considerations 35 The Oracle client would need to be installed on the xSeries LEI server in order to access the Oracle server natively. In this scenario there only needs to be one LEI Administrator database (that is, one replica, but may have multiple replica copies). The LEI Administrator database is a Notes application used to setup and maintain the two LEI servers. DB2 UDB: Figure 2-8 shows the LEI server and DB2 UDB servers on the same physical system, however the DB2 UDB data could be remote as discussed in 2.1.2, “Scenario 2: Remote database server” on page 27. Oracle: The Oracle server could be on any platform. LEI would access the Oracle data natively by using the Oracle client that is installed on the xSeries LEI server. Activities supported All the LEI activity types are supported in this environment. Note: The iSeries server can access the DB2 UDB data with all the different kinds of activities. However, the other LEI server on the xSeries server cannot use the Advanced RealTime activities because it is driving data to a remote Domino server. 2.2 Security considerations In order for LEI to connect to DB2 UDB for iSeries, the LEI server must pass a valid OS/400 user ID and password to the iSeries server. This profile must have access rights to select, insert, and delete data in certain DB2 UDB files. With LEI 6.0.1 there are two options on how this can be configured: Using a generic user ID and password in the connection document. Using integrated credentials. 2.2.1 Generic user ID and password in connection document The first option is to have a generic user ID and password in the DB2 UDB connection document. If this method is used, only one user ID is used for all connections to the DB2 UDB database. All activities that are done through that connection document will be done under the one generic user ID. It will be impossible to monitor in DB2 UDB what transactions were performed by individual users. Also, the access level of the generic user ID may be higher then what all users require. For example, you may have two sets of users, one set that needs only read access, while a second set needs update access. If both sets of users go though one connection document the generic user ID would need to have update access. This means that users only requiring read access connect to DB2 UDB with read and update access. The access control in this example would then have to be controlled though the Notes/Domino application. Another security consideration with this method is the generic user ID and associated password are typed into the connection document. Any users with access to the LEI Administrator database would have access to this information. It is possible to encrypt the password in the connection document. Encrypting the password allows only users who have the encryption key to see the password. Of course, the Notes ID used to run the LEI process must also have the encryption key. The access control list (ACL) of the LEI Administrator database should also be set to prevent unauthorized people from accessing this information. Normal users of LEI applications do not need any access to the LEI Administrator. 36 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server For more information about connection documents, see Chapter 6, “Connection documents” on page 153. 2.2.2 Integrated credentials Integrated credentials is a new feature in LEI 6. It allows for the mapping of Notes user ids to user ids and passwords on external systems such as DB2 UDB for iSeries. With integrated credentials there is an alternative to using a generic user ID and password for all the Advanced RealTime activities. Note: Integrated credentials is only supported for the Advanced RealTime activities (virtual agents, virtual documents, and virtual fields) and not for the batch LEI activities such as data transfer or replication. With integrated credentials, a user logs into a Notes/Domino application. When this user does a transaction that requires accessing DB2 UDB data, LEI first accesses the integrated credentials database specified in the activity document to find an appropriate match for the logged in Domino user. If a match is found, and there is an appropriate user ID and password for the external system, then that user ID and password will be used to log into the external system. Integrated credentials only works for the three Advanced RealTime activities (virtual agents, virtual documents, and virtual fields). The integrated credentials database is a Domino database created from the LEI Credentials template (leicred.ntf). It is possible to have multiple integrated credentials databases for a single LEI server and have different activity documents accessing different integrated credentials databases. It is also possible to distribute one integrated credentials databases to many LEI servers. The integrated credentials database must be manually managed by LEI administrators. LEI administrators have to setup and maintain a mapping of Domino users to external system users. Maintaining this mapping can be very time consuming, especially with password changes and user ID renames. Using integrated credentials may also result in a performance cost. An extra lookup is done before a connection is made to an external system. This extra lookup will effect performance. Connection pooling may not be as efficient as compared to using a generic user ID and password. Connection pooling checks to see if a connection exists for the specific user ID and password that wants to perform a transaction. If a connection that matches exists in the pool, then that connection is re-used eliminating the costly overhead of creating a new connection. In the case where a generic user ID is used, connection pooling will be very efficient since all connections will use the same user ID and password and therefore there is a very high likelihood that there is an existing connection in the pool. When integrated credentials is used, the likelihood of an existing connection that has the same user ID and password is lower. This is because every user logs into DB2 UDB using their own user ID and password. Configuring integrated credentials In order to use integrated credentials you first need to create a integrated credentials database and then add users to the database. Once this is done, you can then reference this integrated credentials database from the LEI Advanced RealTime activity documents. Perform the following steps to create and setup the integrated credentials database: 1. Create a new Domino database from the LEI Credentials template (leicred.ntf). See Figure 2-9. Chapter 2. Architectural scenarios and considerations 37 Figure 2-9 Creating an integrated credentials database from the integrated credentials template 2. Once the integrated credentials database has been created, open the database and click the Create Credentials Entry button to create user mappings for each user (Figure 2-10). Figure 2-10 Integrated credentials database 3. For each user mapping, you have to enter the Lotus Notes user ID, as well as the DB2 UDB user properties. These properties include the connector (that is, DB2 UDB, Oracle and so on) external database name, external user ID and password. The password is not visible in the document. See Figure 2-11. Figure 2-11 Completing the LEI integrated credentials form 38 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 4. When prompted for the external system password, as shown in Figure 2-12, enter the password for the external user ID. Notice the entered password is not visible. Figure 2-12 Setting the external system password 5. Once the integrated credentials document is complete, it is displayed in the main view of the integrated credentials database. This view is categorized by Lotus Notes username (Figure 2-13). Figure 2-13 Main integrated credentials database view Since each integrated credentials document contains a Readers field, users will not be able to see all the documents in the view — generally just their own. Category headings are still shown for categories that contain no documents that the current user can view. However, it is possible to see who has credentials recorded here even though you cannot see anything besides their name in the view. Normal users need access to this database only if they are expected to keep their own password information up to date. You may choose instead to populate this database automatically from information in the DB2 database, if you have a table that contains the needed information. Using integrated credentials in Advanced RealTime activity documents Once the integrated credentials database has been setup, you can use it in any of the three Advanced RealTime activity documents. In the Advanced RealTime activity document, under the Integrated Credentials tab, click the Lookup Credentials option. You then have to fill in the following options as shown in Figure 2-14: Missing Credentials: This field allows you to choose whether you want to use the generic user ID and password that is specified in the connection document if no match is found for the current user in the integrated credentials database. Credentials DB Filepath: Relative file path of the integrated credentials database. Connection Cache Size: This allows you to specific the maximum distinct connections that are active at any one time. Chapter 2. Architectural scenarios and considerations 39 Figure 2-14 Specifying integrated credentials in an Advanced RealTime activity document Considerations when implementing integrated credentials The following points are architectural considerations when using integrated credentials: Is a generic user ID and password a sufficient security mechanism for your application? Management overhead. Some one must create and maintain the user ID and passwords in the integrated credentials database. Performance overhead of integrated credentials. Optimum setting for the Connection Cache Size field in the LEI advanced realtime activity document 2.2.3 Fields and public key encryption If any field in a Notes document have been encrypted using Public Key Encryption then all corresponding fields in the DB2 UDB will be nulled. Notes users with the correct encryption key will be able to see the encrypted data as usual in Notes. It is important to make sure that any encrypted field does not have a constraint preventing null values, or uniqueness constraints. This features is also important to keep in mind if you want to have any programs directly accessing the data in the external system. For more information about this topic, see Chapter 13 of the LEI Activities and User Guide under the section titled ‘Virtual Documents and Public Key Encryption Key’. 40 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Note: In a virtual fields activity, the encrypted data is stored in the Notes document, even if the activity wouldn't ordinarily keep a copy of that field in Notes. In a virtual documents activity, the encrypted data is stored in the EINOTEPROPS field in the DB2 UDB database (since there's no Notes document, and they have to be stored somewhere). If your application uses encrypted fields, then when you create the LEI fields, be sure to allow sufficient space in the EINOTEPROPS field to store the encrypted information. 2.3 Performance considerations The performance of a Domino application is a very complex topic and the addition of LEI adds another layer of complexity. The following sections provide some tips and hints on what can be done to improve the performance of your LEI applications. We also point out items to lessen the impact to the performance of LEI applications. For information about general Domino application performance, refer to the redbook Performance Considerations for Domino Applications, SG24-5602. This redbook can be found at: http://www.redbooks.ibm.com 2.3.1 LEI considerations This section reviews performance considerations relative to LEI activities. Advanced RealTime activities Following are performance considerations for some of the Advanced RealTime activities, specifically virtual fields and virtual documents: Persistent connections: For Advanced RealTime activities, the Max Connections parameter in the activity document allows you to set the number of persistent connections. A larger number of connections may improve performance if there is a high amount of simultaneous access to a virtual document or virtual field. This parameter defaults to a setting of 2 which may be less than ideal in some production environments. Lotus recommends setting this parameter to 2 or 3, and if users experience significant delays then to increase the number. The differences between persistent connections and connection pooling in the Lotus connector Lotus Script extensions is explained in 2.3.4, “Connection pooling verses persistent connections” on page 45. Integrated credentials: If integrated credentials are used, there may be a performance cost because the user ID and password passed to the back-end data source is always changing. This lessens the performance improvement normally gained with persistent connections. See 2.2.2, “Integrated credentials” on page 37 for more details. Internal keys verses external key table: Virtual documents that use internal keys will perform better than those that use an external key table. If internal keys are used, the control fields are added to the DB2 UDB table that has a virtual document processing over it. In this case, only the table being virtualized needs to be access to perform the virtualization. If an external table is used to hold the control fields, a join must be performed each time data is virtualized in the Domino application. This requires extra processing and will perform less optimally than using internal keys. This is particularly true if the file that is being virtualized contains many records. Chapter 2. Architectural scenarios and considerations 41 For more information about virtual documents, see 8.1, “Virtual documents activity” on page 196. Index the three internal key fields: If internal keys are used you should index the EINOTEID, EIUNID, EIMODIFIED fields. Indexes will not automatically be created over these control fields, you need to create these indexes manually. Index keys for external key table: If an external key table is used for a virtual document activities, the join key fields in both the external key table, as well as key fields in the data table should be indexed. Every time a virtual document is accessed a SQL join is done on the two tables, indexing the key fields that the join operation is done on may substantially improve performance. If you use the built-in ‘Create external key table’ utility in the virtual document activity to create the external table, indexes will automatically be created over the control fields. First time start on virtual document activity: Initial population of the internal keys or the external key table may be slow and make the application appear to be slow. Note: If the virtual document activity is accessing a larger DB2 UDB table it is highly recommended to perform the first start of the virtual document activity during non-production hours. Remote database server: Accessing a remote database over a network will be slower then accessing a database that is local to the LEI server. Local database access removes all network overhead. When architecting your application solution, you need to keep in mind the how much data will be transferred and at what rate to determine if the network bandwidth will be a concerning factor. Batch activities Following are performance considerations for the batch activities, specifically direct transfer and replication: Direct transfer, Number of Records to Transfer Concurrently: This parameter is set to 1 by default. This parameter enables the buffering of records before a transfer is done. Setting this number higher then 1 will improve performance for direct transfer activities. A rule of thumb is to set this to be 10% of the number of total expected rows of data you expect to transfer. For example if you expect to transfer 1000 rows of data, you can set this parameter to 100. Timestamp replication: For the replication activity, using timestamp replication will normally be faster then using primary key replication. Timestamp replication enables fewer records to be examined on both the source and the target data sources. When using timestamp replication, only those records that have a timestamp greater than the last time the replication activity ran will be examined. This greatly reduces replication times for most environments. If primary key replication is used, LEI needs to examine each record in both the source and target data sources and then compares them for differences. Only the records that have changed will then be replicated. Remote database server: Accessing a remote database over a network will be slower then accessing a database that is local to the LEI server. Local database access removes all network overhead. When architecting your application solution, you need to keep in mind the how much data will be transferred and at what rate to determine if the network bandwidth will be a concerning factor. 42 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 2.3.2 Performance spectrum scenarios To help pull all of this information together in a graphical sense, Figure 2-15 and Figure 2-16 show how performance may be affected depending on the type of application and the different LEI components that are used. In Figure 2-15 we examine the performance spectrum for using virtual field activities. The scenario defined in the left most portion of the diagram indicates the scenario combinations for producing the worst performance. These items include a Web application using a remote DB2 UDB database and using integrated credentials. This scenario receives a performance boost by simply removing integrated credentials as we move one step to the right. Continuing on to the right side, we gain another performance boost by changing the Domino application from being Web browser based to Notes client based. This will place less load on the server because Notes clients are typically 2 to 3 times less CPU intensive than Web browser users. At the far right side of the diagram, we see the scenario combinations that will provide the best performance. Here we have a Notes client based application accessing the DB2 UDB data locally on the same iSeries server using a generic ID so we can take full advantage of connection pooling. Note: Figure 2-15, and Figure 2-16 are not drawn to scale. The gradient of performance improvement will be significantly higher for virtual documents then compared to virtual fields for each move to the right on the two diagrams. Performance Spectrum for Virtual Field Activity Best Worst Web application Remote database Integrated credentials Web application Remote database Generic user ID Notes application Remote database Generic user ID Notes application Local database Generic user ID Figure 2-15 Performance spectrum for virtual field activity Figure 2-16 provides a graphical representation of how performance can vary when working with virtual document activities. Starting at the left side with the worst case scenario we have a Domino Web based application accessing data on a remote server using integrated credentials and an external key table. This scenario is improved by replacing integrated credentials with a generic user ID to gain the performance benefit of connection pooling. Going one more step to the right we again improve performance by replacing the Domino Web based application with a Notes client based application. As noted in the discussion regarding the virtual fields activity performance spectrum, Notes client based users are typically 2 to 3 times less expensive for CPU consumption than Web based users. Chapter 2. Architectural scenarios and considerations 43 Continuing to the right, we now replace the remote database access with a local database on the same iSeries server where the Domino application is running. The ultimate solution scenario defined at the far right involves a Notes client based application accessing DB2 UDB databases locally on the same iSeries server using a generic user ID and replacing the external key table with internal keys. This scenario will provide the best performance. Performance Spectrum for Virtual Document Activity Best Worst Web application Remote database Integrated credentials External keys Web application Remote database Generic user ID External keys Notes application Remote database Generic user ID External keys Notes application Local database Generic user ID External keys Notes application Local database Generic user ID Internal keys Figure 2-16 Performance spectrum for virtual document activity This is not to say that an application that chooses all the slowest options will necessarily have unacceptable performance. Much depends on other factors, such as how many users there are, network speeds, database optimization or lack thereof, and number of records in database. You may trade off performance versus timeliness of information. If your remote DB2 database is accessed over a slow connection, your users will get much better performance if you use a Replication activity to migrate changes between DB2 UDB and Notes, instead of using virtual fields or virtual documents over that connection. However, the Notes information may be out of date if other applications are making changes to the DB2 UDB data. Also, the design of your Notes application may also have significant effect on performance. 2.3.3 DB2 UDB considerations In addition to looking at the overall architecture of the Domino LEI application as we did in 2.3.1, “LEI considerations” on page 41, there are DB2 UDB performance tips you should take into consideration as well. Indexes: Indexing fields that are queried often, or that SQL joins are done on can significantly improve performance. For more information about how to best utilize indexing refer to the white paper, Indexing Strategies for DB2 UDB for iSeries. This paper can be found at: http://www.ibm.com/servers/eserver/iseries/developer/bi/documents/strategy/strategy.html Views verses tables: Logical views may perform better then accessing a table directly. For example, in a scenario where there is a table with 20 columns and 500 rows, but you only require LEI to access 5 columns and 100 rows, you will most likely get better performance if you access a view that contains only the 5 columns instead of all 20 columns in table. 44 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server For more detailed information about DB2 UDB performance factors, you can reference the following iSeries performance resources Web page at: http://www.ibm.com/servers/eserver/iseries/perfmgmt/resource.htm 2.3.4 Connection pooling verses persistent connections The differences between connection pooling and persistent connections in Advanced RealTime activities is explained below. Connection pooling The LotusScript Extensions for Lotus Connectors (LC LSX) provides a simple programmatic interface to connection pooling. The LCSession class exposes a property called ConnectionPooling. Setting this property to ‘True’ enables connection pooling. Figure 2-17 graphically shows the connection pooling process. Is connection pooling enabled? No Is this a pooled connection? Yes Does a connection in the pool have the same connectivity properties as the 'stored' ones? Connect Return No Allocate a connection. Assign the 'stored' properties. Yes Will the pool help another connection of this type? Mark the pooled connection 'in use'. No Yes Add to pool, mark 'unavailable' and connect. Return Figure 2-17 Connection pooling process A typical operation consists of three major parts: Connecting to the data source. Identifying information of interest, retrieving and or updating the information. Disconnecting from the data source. The middle step is the processing step. When you work with large amounts of information or when you are performing complex operations, processing becomes the most significant time consideration. Many applications have a very short processing step. In these applications, a much greater percentage of total time is associated with connecting to and disconnecting Chapter 2. Architectural scenarios and considerations 45 from the external data source. The connect/disconnect time is amplified when it must occur for each processing request. The LC LSX provides a connection pooling property that makes it possible to retain discarded connections for later use. The pooling functionality is controlled by the LCSession property, ConnectionPooling, which is a Boolean with a default value of FALSE. When this property is set to TRUE, subsequent requests for new connections are processed through the connection pool. With connection pooling, creating a new connection is serviced first by checking the pool for an existing compatible connection and then if one is not available, creating a new connection. A compatible connection is determined by the external system and all of the system’s required connectivity properties. This prevents a connection originally established for one user, later being used by another. As an example, a connection to DB2 UDB which was originally created using John’s user name and password, and then release to the connection pool would not be issued if a new connection was requested using Jane’s user name and password. A connection is removed from the pool when the ‘Connect’ method occurs. A connection is returned to the pool when the ‘Disconnect’ method occurs. If no explicit disconnect occurs, an automatic disconnect is performed when the object is deleted. Note: In LotusScript, if no explicit ‘delete’ occurs on an object, it is automatically deleted when it falls out of the scope of the function, subroutine, or script. Keep in mind that a connection that is returned to the pool does not disconnect from the external system. Code that takes advantage of connection pooling must anticipate this behavior. The important issues to remember are related to what may happen automatically during a normal disconnect from an external system. For example, disconnecting from an RDBMS may trigger a commit of records inserted, updated, or deleted, since the connection was first established. Likewise, there may be rollback or other database operations that take place automatically as a result of disconnecting. When connection pooling is enabled, these events do not take place because the connection is not actually dropped. Therefore, if you expect and want these types of operations to take place, the processing portion of the script must explicitly perform them. The life span of a pooled connection is dependent on the LC LSX. Within Notes and Domino, an LC LSX is loaded when the execution of the Uselsx statement occurs in a script. The LC LSX is not unloaded until the Notes or Domino process terminates. Once a connection is pooled, it remains available until the associated process terminates. The connection pool defaults to a maximum of 20 pooled connections for a given external system. When the maximum number of connections have been created and are already in use, a request for an additional connection will be granted but the connection will not be pooled. The default may be overridden using settings in the notes.ini file. The syntax for configuring the connection pools is a list of comma-delimited Lotus Connector names, the pool size, and an optional data source maximum. The default pool size for all connectors is 20. The optional data source maximum value indicates the limit of allowed connections to a single database. This value cannot be greater than the total pool size for a given connector. For example, a DB2 UDB pool size of 10 and a data source maximum of 5 indicates the pool will hold no more than 10 connections to DB2 UDB and of the 10, no more than 5 will be to any one database. If you do not specify a data source maximum, it is the same as the pool size. 46 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 2.3.5 Persistent connections in Advanced RealTime activities After an Advanced RealTime activity starts up, the first time someone requests data through that activity, LEI creates a connection to the data source for that activity. LEI keeps this connection open for as long as the activity is running, to more quickly process subsequent requests. LEI supports some parallelism, to process multiple requests of the same activity simultaneously. Processing an Advanced RealTime operation can involve significant I/O waits; while waiting, there's no reason LEI can't be setting up and sending out a request for data for another user. However, that requires a second connection. Advanced RealTime activity forms contain a setting for ‘Max Connections’. This controls how many requests can be processed simultaneously by the activity. If the existing connections are already in use, LEI creates an additional connection to the same data source, up to the limit you specify. None of these will be disconnected until the activity shuts down. If 'Max Connections' is reached for a DECS/LEI Advanced Realtime activity and all connections are already in use or reserved, the new request enters a wait loop, and checks for availability of a connection every 250 milliseconds. The wait loop has no time-out. Certain expensive virtual document functions like view building, use a slightly different connection search and lock routine to find a persistent connection. This special routine does have a retry count of 40, which if reached, will report that it failed to get a connection. This routine also guarantees that at least two free connections exist before an expensive Virtual Document request is granted a connection. This is an attempt to keep virtual document view building and virtual document searches from holding out ordinary virtual field or virtual document requests. If using integrated credentials, the activity maintains an active connection for each user, from when they first request information from the database, until the activity shuts down. The idea of persistent connections is related to, but not the same as, the connection pooling feature used by the LC LSX. The connection pool collects unused connections that originate from any script, not just from a single activity. Chapter 2. Architectural scenarios and considerations 47 48 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 3 Chapter 3. Installation and configuration on the iSeries platform To have Lotus Enterprise Integrator (LEI) 6.0.1 in a state that allows you to start working with it, LEI has to be prepared for use. To configure LEI on the iSeries server, you must have an understanding of the following topics: Prerequisites for operating LEI on the iSeries server Pre-installation activities Installation of the LEI product code Administration of LEI on the iSeries © Copyright IBM Corp. 2003. All rights reserved. 49 3.1 Prerequisites for operating LEI on the iSeries server Prior to installation of LEI on the iSeries, the hardware and software levels need to be verified to confirm that they are in accordance with the prerequisites. The prerequisites ensure the installation process will operate correctly and that LEI will perform as expected on the iSeries server. Previous releases of LEI on the iSeries were installed through the OS/400 CL command of Load and Run (LODRUN). Moving toward a standard installation process across all platforms, reducing confusion, LEI on the iSeries no longer utilizes the LODRUN command. The installation process for LEI is now performed through a Java-based program operated on Win32-based workstations. This Java environment now provides a graphical process, that is fairly standard for all platforms, through which to install the LEI 6 software. 3.1.1 Hardware The minimum hardware requirements for both server and workstation environments are listed in this section. It must be stressed that these are the minimum requirements for the installation of LEI and are in addition to requirements of the Domino for iSeries server. For the latest recommendations, visit the Lotus Enterprise Integration Web site for updates and suggestions: http://www.lotus.com/ei iSeries server The minimum hardware requirements for LEI on iSeries are: iSeries RISC platform 128MB of memory or greater 80MB of disk space or greater Installation workstation The minimum hardware requirements for installation from a Win32 based workstation are: Intel based workstation 128MB of memory or greater 90MB of disk space or greater 3.1.2 Software The software requirements for the installation and operation of the LEI 6 software, reviewed in this section, primarily identifies the necessary base software to be installed. This section does not deal with the required Program Temporary Fixes (PTF) files on the iSeries, which is reviewed in 3.1.3, “Required PTFs for OS/400” on page 52. The software recommendations listed here are the minimum requirements for LEI 6 to install and operate correctly. iSeries server The minimum software requirements for LEI 6.0.1 on the iSeries platform are as follows: OS/400 V5R1 or later JDK 1.3.1 Domino for iSeries 6.0.1 Starting with Domino 6.0, the LEI product is now bound to the release level. This is a change from past releases of LEI where the LEI 3.1 product for example would run on multiple releases of the Domino R5.x server. Starting with Domino 6.0, the level of LEI 50 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server must match the Domino release level. This means that LEI 6.0 will only work with Domino 6.0. Additionally, LEI 6.0.1 will only be able to be installed on a Domino 6.0.1 server, and so on. LEI 6.0.1 is the first version of LEI 6 that is supported on the iSeries platform. Determining what software resources installed on an iSeries server can be performed through the OS/400 CL command of Display Software Resources (DSPSFWRSC). This command displays all software resources that have been installed on the iSeries server. Figure 3-1 displays the output from this command indicating that both the Java Developer Kit 1.3 (JDK), 5722-JVM, option 5 and Lotus Domino 6.0.1 for iSeries, 5733-LD6, are installed. Note: While DSPSFWRSC displays the software resources installed on the iSeries server, in relation to the 1.3.x version of the JDK it only displays Java Developer Kit 1.3 regardless of version installed. This indicates that option 5 of the IBM Developer Kit for Java has been installed. To identify the version being used, Group and individual PTFs have to be identified. See 3.1.3, “Required PTFs for OS/400” on page 52 for details. Display Software Resources System: Resource ID 5722JV1 5722JV1 5722JV1 5722JV1 5722JV1 5722JV1 ..... ..... 5733LD6 5733LD6 5733LD6 AS08 Option Feature Description *BASE 5050 IBM Developer Kit for Java *BASE 2924 IBM Developer Kit for Java 3 5103 Java Developer Kit 1.2 4 5104 Java Developer Kit 1.1.8 5 5105 Java Developer Kit 1.3 6 5106 Java Developer Kit 1.4 *BASE *BASE 1 5050 2924 5050 Lotus Domino 6 for iSeries Lotus Domino 6 for iSeries C API Release 6 More... Press Enter to continue. F3=Exit F11=Display libraries/releases F19=Display trademarks F12=Cancel Figure 3-1 Display Software Resources (DSPSFWRSC) command Chapter 3. Installation and configuration on the iSeries platform 51 Attention: The IBM Lotus Enterprise Integrator for Domino (LEI) Installation Guide indicates the following options are installed with the installation of Lotus Domino 6 for iSeries and will be displayed with the DSPSFWRSC command: 5733LD6 *BASE 5050 Lotus Domino 6 for iSeries 5733LD6 1 5050 iSeries Integration 5733LD6 3 5050 C API 5733LD6 4 5050 C++ API 5733LD6 5 5050 LotusScript Extension ToolKit 5733LD6 7 5050 Advanced Services This information is incorrect, as the only options now installed with Domino 6 are the two displayed in Figure 3-1: 5733LD6 *BASE 5050 Lotus Domino 6 for iSeries 5733LD6 1 5050 C API Workstation for LEI installation and administration The following software requirements are for the workstation being used to install and administer the LEI software: Windows, 32 bit operating system Lotus Notes 6.0 or higher LEI software – iSetupInstall.exe – iSetupMigration.exe – iSetupUninstall.exe Note: The Lotus Notes client software is not required for the installation process. It is required if it is desired to then move straight into administrating the LEI server. 3.1.3 Required PTFs for OS/400 System updates and fixes on the iSeries server are applied through a Program Temporary Fix (PTF). PTFs required to be loaded depend on the version and release level of the OS/400 being used and the software products loaded on the system. This section covers the minimum required PTFS to install LEI 6 and how to verify the current PTF levels applied on your iSeries server. LEI 6 on iSeries requires PTFs for both the Java environment and the operating system. This section lists the minimum prerequisites that are required to be applied for LEI 6.0.1 to successfully install and operate. To review details of the latest PTFs for LEI and associated software, visit the following Web sites to verify appropriate levels required to be installed: LEI http://www.lotus.com/ei Domino 6 for iSeries http://www.ibm.com/eserver/iseries/domino/support DB2 UDB http://www.ibm.com/eserver/iseries/db2 52 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server OS/400 V5R1 Following are the PTFs that are required for LEI 6.0.1 to install and operate on OS/400 V5R1: Java group PTF for V5R1 is SF99069-11 or later. The minimum individual PTF levels for V5R1 are: – 5722-SS1 • • • SI05470 SI04435 SI01807 – 5722999 • • MF29381 MF26987 – 5722JV1 • • • • • SI01804 SI02659 SI03638 SI04768 SI04847 Note: If it has been identified that Java group PTF SF99069-11, or a later one, has not been applied, ensure that the Java Developer Kit 1.3 has already been loaded. If the group PTF is applied prior to installing option 5 of the JDK, the PTF will need to be reapplied. To verifying group PTF levels that are applied to an OS/400 V5R1 iSeries server, run the CL command of Display Data Area (DSPDTAARA). The DSPDTAARA CL command provides the details displayed in Figure 3-2. Display Data Area System: Data area Library Type . . Length . Text . . Offset 0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . : : : : : AS22 SF99069 QJAVA *CHAR 50 Value *...+....1....+....2....+....3....+....4....+....5 'Group PTF#: SF99069-16 V5R1M0 April 21, 2003 ' Bottom Press Enter to continue. F3=Exit F12=Cancel Figure 3-2 Display Data Area (DSPDTAARA) command To verify that individual PTFs are installed, use the CL command of Display PTF (DSPPTF) as follows: DSPPTF LICPGM(productcode) Chapter 3. Installation and configuration on the iSeries platform 53 The DSPPTF command displays the individual PTFs that have been applied against a specific licensed program represented by the product code. Figure 3-3 displays the individual PTFs applied against the Java software using the CL command DSPPTF LICPGM(5722JV1). Display PTF Status System: Product ID . . . . . . . . . . . . . : IPL source . . . . . . . . . . . . . : Release of base option . . . . . . . : Type options, press Enter. 5=Display PTF details 6=Print cover letter PTF Opt ID SI01804 SI01683 SI01642 SI01629 SI01573 SI01025 SI00959 SI00819 SI00367 Status Superseded Permanently Superseded Temporarily Superseded Temporarily Temporarily Temporarily Permanently AS22 5722JV1 ##MACH#B V5R1M0 8=Display cover letter IPL Action None None None None None None None None None applied applied applied applied applied applied More... F3=Exit F11=Display alternate view F17=Position to F12=Cancel Figure 3-3 Display PTF (DSPPTF) command OS/400 V5R2 Following are the PTFs that are required for LEI 6.0.1 to install and operate on OS/400 V5R2: Java group PTF for V5R2 is SF99169-1 or later. The minimum individual PTF levels for V5R2 are: – 5722-SS1 • • • SI04767 SI04848 SI05485 – 5722999 • MF29354 To verify the level of group PTFs on OS/400 V5R2, you use the Work with PTF Groups (WRKPTFGRP) CL command. The WRKPTFGRP command, as shown in Figure 3-4, displays the group PTF files that have been installed on the iSeries server. Entering option 5 (Display) beside any group PTF will displayed the individual PTFs that comprise it. 54 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Work with PTF Groups System: Type options, press Enter. 4=Delete 5=Display 6=Print Opt PTF Group SF99502 SF99271 SF99246 SF99245 SF99169 SF99148 SF99098 Level 6 7 1 1 8 4 8 AS08 9=Display related PTF groups Status Installed Installed Installed Installed Installed Installed Installed Bottom F3=Exit F6=Print F11=Display descriptions F22=Display entire field F12=Cancel Figure 3-4 Work with PTF Groups (WRKPTFGRP) command The initial display presented by the WRKPTFGRP command, as displayed in Figure 3-4, provides limited information. For a more descriptive display of the information that you are looking at, press F11 and a description of the software being viewed is displayed, as shown in Figure 3-5. Work with PTF Groups System: Type options, press Enter. 4=Delete 5=Display 6=Print Opt PTF Group SF99502 SF99271 SF99246 SF99245 SF99169 SF99148 SF99098 AS08 9=Display related PTF groups Text DB2 UDB FOR ISERIES WEBSPHERE APPLICATION SERVER - EXPRESS V5.0 WEBSPHERE APP SERVER V5.0 ND 5733WS5 WEBSPHERE APP SERVER V5.0 5733WS5 JAVA PTF GROUP WEBSPHERE ADV. EDITION 4.05 5733WA4 IBM HTTP SERVER FOR ISERIES Bottom F3=Exit F6=Print F11=Display status F22=Display entire field F12=Cancel Figure 3-5 WRKPTFGRP command, F11- Display descriptions As explained in the previous section on OS/400 V5R1, to verify which individual PTF files have been applied against a licensed program, you use the Display PTF (DSPPTF) CL command. 3.1.4 Domino Enterprise Connection Services (DECS) If the LEI 6 installation process detects a configured DECS Administrator database on the Domino server, the operator is prompted to provide a backup file name for the DECS Administrator database, decsadm.nsf. The new LEI Administrator database will be named decsadm.nsf. If the old DECS Administrator database is not backed up, it will be overwritten. Chapter 3. Installation and configuration on the iSeries platform 55 The process of LEI installation automatically migrates connection and activity documents from a DECS Administrator database into the new LEI Administrator database. 3.2 Pre-installation activities To provide the required level of access for LEI to function correctly, modifications to the Domino server document and Domino server ID are required for the Domino servers on which LEI will operate. 3.2.1 Domino server document changes Perform the following steps to modified the Domino server document before installing and configuring LEI. 1. As displayed in Figure 3-6, modify the Programmability Restrictions section, located under the Security tab, of the Domino server document to add the user Enterprise Connector Products/Lotus Notes Companion Products to the following fields: – Run unrestricted methods and operations – Run restricted LotusScript/Java agents This enables the LEI agents to function as designed on the Domino server without requiring to sign the design elements of the databases and templates. If it was neglected to perform this step, the LEI agents would fail and a ‘You are not authorized to perform this operation’ message would appear in the Domino server console. Figure 3-6 Domino server document - Security tab - Programmability restrictions section 2. To provide access for the user Enterprise Connector Products/Lotus Notes Companion Products to operate on the LEI server, modifications to the Server Access section, also located under the Security tab, of the Domino server document is also required to be performed. Figure 3-7 displays the required addition to the Access server field. Ensure the user name Enterprise Connector Products/Lotus Notes Companion Products and the Domino server name of the LEI server are both included in this field. 56 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 3-7 Domino server document - Security tab - Server access section 3. The last thing to verify in the Domino server document of the LEI server is that the address entered in the Net Address field, located under the Ports tab -> Notes Network Ports sub-tab. This can be either a host name that can be resolved to the correct IP address, or the IP address itself is entered. See Figure 3-8. Figure 3-8 Domino server document - Notes network ports 3.2.2 ID modifications During installation, and while LEI is functioning after configuration, certain operations will be performed using the authority of the user, Enterprise Connector Products/Lotus Notes Companion Products, as noted above. To prevent the server from prompting for authorization to continue the operation, the following is required to be undertaken on the ID that is identified in the KeyFilename parameter in the Domino server’s Notes.ini file. If you are installing LEI on multiple servers, the following process is to be performed on all ID files on the servers that LEI will be operating on. Perform the following steps: 1. Download the ID file that is identified in the KeyFilename parameter in the Domino server’s Notes.ini file from the Domino server’s data directory in the OS/400 Integrated File System (IFS) to your PC workstation. 2. On the Notes client switch to this ID using the pull down menu options of File -> Security -> Switch ID. 3. Open the User Security for the ID file using the pull down menu options of File -> Security -> User Security. 4. On the User Security window, under the Security Basics tab, as displayed in Figure 3-9, select Don’t prompt for a password from other Notes-based programs (reduces security checkbox. Chapter 3. Installation and configuration on the iSeries platform 57 Figure 3-9 User Security - Security Basics 5. Click the What Others Do tab and then the sub tab Using Workstation. 6. Click the Add button and enter Enterprise Connector Products/Lotus Notes Companion Products. 7. For this new entry select the following options as displayed in Figure 3-10: – Allow access to: • • • • File system External code Current database Environment variables – Allow ability to: • • 58 Read other databases Modify other databases Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 3-10 User security - What others do 8. Click OK. 9. Switch back to the initial Lotus Notes user ID using the pull down menu options of File -> Security -> Switch ID. 10.Upload the modified server ID file back to the Domino server’s data directory on the OS/400 IFS replacing the existing ID file. Note: It is recommended to verify the ownership of the ID file that is copied back to the Domino server’s data directory on the OS/400 IFS using the Work with Authority (WRKAUT) CL command. Under certain circumstances the ID file may no longer have the ownership of QNOTES. To change the ownership of the file, you use the Change Owner (CHGOWN) CL command. 11.Restart the Domino server. 3.2.3 TCP/IP configuration For the LEI installation process to operate correctly, the iSeries server must have TCP/IP configured and operational. To ensure TCP/IP is configured, enter the Configure TCP/IP (CFGTCP) CL command on your iSeries server and select option 12, Change TCP/IP domain information. Ensure proper entries for Host Name, Domain Name, and Domain Name Server exist. If you do not specify the Internet address of a Domain Name Server in your TCP/IP domain information (CFGTCP option 12), you must add the fully qualified server name of your system and the system's IP address to the TCP/IP host table (CFGTCP option 10) for the LEI installer to work properly. Chapter 3. Installation and configuration on the iSeries platform 59 3.3 Installation of LEI During installation, you are asked to provide the system name for the iSeries server that LEI is being installed onto and a login name and password. For the installation to complete successfully, the OS/400 user profile for the login name is required to have the following authorities on the iSeries server: All object access (*ALLOBJ) System configuration (*IOSYSCFG) Job control (*JOBCTL) Security administration (*SECADM) 3.3.1 Installation Checklist Prior to installing LEI, review and confirm that all the following items have been completed: Review the readme documentation that is available with the LEI product. Confirmed that the iSeries server and Win32 workstation satisfy the hardware requirements identified in 3.1.1, “Hardware” on page 50. Confirm that the software requirements for the iSeries server and Win32 workstation, identified in 3.1.2, “Software” on page 50, are satisfied. Confirm that the appropriate PTFs, identified in 3.1.3, “Required PTFs for OS/400” on page 52, have been applied. Confirm that the appropriate access to the servers, through the Domino server document identified in 3.2.1, “Domino server document changes” on page 56 have been granted. Confirm that the required modifications to the ID file discussed in 3.2.2, “ID modifications” on page 57 have been applied. Confirm that the Domino server has been restarted and is running on the iSeries server that LEI is being installed. Verify that TCP/IP is correctly configured on the iSeries server as discussed in 3.2.3, “TCP/IP configuration” on page 59. Confirm that DECS is disabled. You can do this by issuing the following command from the Domino server console: tell decs stop Also, if a earlier version of LEI is installed and running you need to confirm that it is also disabled by issuing the following command from the Domino server console: tell lei quit 3.3.2 Process of Installation The installation process has five distinct stages. When the install program is run the outer installer wrapper is run, which then seeks to connect to the iSeries server. Once a connection is established the RAWT daemon is launched, the jar files for the inner installer wrapper are loaded onto the iSeries server. Finally the inner wrapper is launched presenting screens back to the initiating PC for configuration information to be entered. Perform the following steps to install LEI on the iSeries server: 1. On the PC workstation run the program file iSetupInstall.exe. A screen appears, displayed in Figure 3-11, indicating that the InstallShield Wizard is being loaded. 60 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 3-11 Java Virtual Machine informational message 2. Once the Java Virtual Machine (JVM) has been initialized, the a welcome screen is displayed as shown in Figure 3-12. Click Next to continue. Figure 3-12 Setup wizard - Welcome 3. The next screen that appears, displayed in Figure 3-13, is to verify the IP address of the PC workstation from which you are running the installation process. Verify that the IP address is correct and click Next to continue. Chapter 3. Installation and configuration on the iSeries platform 61 Figure 3-13 Setup wizard - PC Workstation IP address Important: This is verifying the IP address to be used of the PC workstation, not the iSeries server. The IP address is verified here as workstations may have multiple network cards providing access to different network segments. 4. A window indicating the progress of installation, displayed in Figure 3-14, is next to appear. Do not click any buttons or close the screen unless intending to cancel the installation. 62 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 3-14 Setup wizard - Status of setup 5. A window prompting you to sign on to the iSeries server, as shown in Figure 3-15, appears. Enter the host name of the iSeries server into the System field, the OS/400 user profile that has the required security access, and the password for that user ID. Click OK. Figure 3-15 iSeries sign on Note: Once you click OK, the setup wizard will load the LEI software on the iSeries server and initiate a Java program for the configuration purposes. Be patient, it can take a while for the next window which requires interaction to be loaded. 6. Next a series of windows, as displayed in Figure 3-16, are displayed. These windows include: – The Remote AWT Daemon controlling the connection between your PC workstation and the iSeries server. – A DOS screen which is used to Launch the Remote AWT Daemon. – The installation progress window (displayed as a grey window). – The installer window (displayed as a white window). Chapter 3. Installation and configuration on the iSeries platform 63 Note: It is important that none of these windows are closed unless they are closed by the program itself or a prompt has indicated that it is okay to close a window. Figure 3-16 Workstation desktop - series of windows displayed during LEI 6 installation Note: The Installer window (displayed as a white window in Figure 3-16) is placed directly on top of the progress window (displayed as a grey window) when it appears. It has also been know to appear directly behind the progress window. It is sometimes necessary to move the progress window to access the launched Installer window. 7. The Welcome window detailing the application that is about to be installed, as shown in Figure 3-17, should now be displayed. Click Next to continue. 64 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 3-17 InstallShield - Welcome 8. A window displaying the Software License Agreement appears, as displayed in Figure 3-18. Read the agreement that is being asked to be accepted. If terms of the agreement are acceptable, select I accept the terms in the license agreement and click Next to continue. Figure 3-18 InstallShield - License agreement Chapter 3. Installation and configuration on the iSeries platform 65 9. The next window to appear asks for confirmation as to where the Notes.ini file can be found, as shown in Figure 3-19. During installation the Installer modifies the Notes.ini file, adding parameters required for LEI 6 to operate. By default the field comes up blank, click the Browse button to locate the directory on the iSeries server that contains the Domino server’s Notes.ini file. Click Next to continue. Figure 3-19 InstallShield - Domino server’s Notes.ini path Note: If the path is known it may be faster to type the path into the field as it has been identified that the Browse button may be slow. 10.A reminder, displayed in Figure 3-20, appears informing the installer that the ID file that will be used is the one in the KeyFileName parameter located in the Domino server’s Notes.ini file, and is now displayed in the window. The installer is reminded that both the ID file and the Domino server document has to be modified prior to installation, as discussed in 3.2, “Pre-installation activities” on page 56. Click Next to continue. Note: If the required changes listed in Figure 3-20 have not been completed they can be attended to now. Minimize the window and complete the changes described in 3.2, “Pre-installation activities” on page 56. 66 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 3-20 InstallShield - Informational message 11.A window appears displaying the LEI server name and the Domino server name that the LEI Administrator database will be located (Figure 3-21). It defaults with the information of the Domino server on which LEI is being loaded. Note: Currently the entry in the Domino Server Name field must matched what is listed in the Mail Server field located at the bottom of the Basics tab in the Domino server document. This applies to LEI versions 6.0 to 6.0.2 and is fixed in 6.0.3. For details about this limitation, refer to the following technotes: http://www.ibm.com/support/docview.wss?rs=203&q=1107988&uid=swg21107988&loc=en_US&cs=utf-8&lang=en+en http://www.ibm.com/support/docview.wss?rs=203&q=1107264&uid=swg21107264&loc=en_US&cs=utf-8&lang=en+en If you are setting up this server as part of an existing LEI cluster, refer to “LEI clustering” on page 83 before continuing. Click Next to continue. Chapter 3. Installation and configuration on the iSeries platform 67 Figure 3-21 InstallShield - LEI server identification and LEI Administrator database location 12.The additional managers screen, displayed in Figure 3-22, provides a mechanism for names or groups to be added to the LEI databases. Separate multiple entries with semicolons. Click Next to continue. Figure 3-22 InstallShield - Additional LEI database managers 68 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Note: Manager level access is the default access granted to databases created during LEI installation. By adding in standard group names at this step, will simplify the process of securing the LEI databases. 13.Advanced RealTime access can be enabled from time of installation or at a later time. As displayed in Figure 3-23 select whether to enable RealTime activities or not and click Next to continue. Figure 3-23 InstallShield - RealTime activities 14.The documentation window, as shown Figure 3-24, provides the ability to select whether to install the optional documentation and script vault. Select your choices and click Next to continue. Chapter 3. Installation and configuration on the iSeries platform 69 Figure 3-24 InstallShield - Optional install of documentation, samples and script vault Note: If migrating from LEI 3.x, selecting the Create script vault option must be selected. 15.The next window to appear, Figure 3-25, describes the location to which the documentation will be installed if selected in the previous window. Click Next to continue. 70 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 3-25 InstallShield - Documentation location 16.The next window to appear, as shown in Figure 3-26, informs the installer about the progress of the installation. This window will disappear when the copying of files is complete. Figure 3-26 InstallShield - Status of installation Chapter 3. Installation and configuration on the iSeries platform 71 17.The next window, displayed in Figure 3-27, provides the option to launch the migration utility at this time. Click Next to continue. Figure 3-27 InstallShield - Migration of LEI 3.x Note: The migration of connection documents, activity documents and LEI LSX scripts can be undertaken now or at a later point in time. If this process will be upgrading the environment from LEI 3.x to LEI 6.0.1 and the migration facilities will be used to migrate connection documents, activity documents and script files, refer to Chapter 4, “Migrating from Lotus Enterprise Integrator 3.x” on page 87 for information about migration. 18.Figure 3-28 reminds the installer that after completion the Domino server that has had LEI installed is to be restarted before LEI can be used. Click Next. 72 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 3-28 InstallShield - Informational reminder 19.The completion window, shown in Figure 3-29, indicates the process of installing LEI on the iSeries server has now completed. Click Finish. Figure 3-29 InstallShield - Completion of installation Chapter 3. Installation and configuration on the iSeries platform 73 Note: This completes the physical installation of the files and configuration of the LEI server on the iSeries. There is still a few more screens to complete before the installation process is complete. 20.The default Web browser will launch pointing to the product registration, as displayed in Figure 3-30, on completion close the Web browser to continue. Figure 3-30 Product registration 21.The next window to appear provides the option to load the readme text, see Figure 3-31. This is optional, select if it is desired to review the file. Click Next to continue. 74 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 3-31 Setup wizard - Readme 22.If the migration utility has been launched, the window displayed in Figure 3-32 provides a reminder not to progress any further. Click Next to continue. Figure 3-32 Setup wizard - Informational message 23.Setup for LEI on iSeries has now completed as shown in Figure 3-33. Click Finish to complete. Chapter 3. Installation and configuration on the iSeries platform 75 Figure 3-33 Setup wizard - Completion of setup 24.If the Remote-AWT window displayed in Figure 3-34 is still running at this point, it is now safe to close it. This also is true for any other windows launched during the installation process. Figure 3-34 Remote-AWT daemon Note: Prior to using LEI on the Domino server for the first time, ensure that the Domino server has been restarted since the LEI software has been installed. 3.4 Administration of LEI on the iSeries LEI on the Win32 and UNIX platforms is installed as an application in its own right with the option during installation to install as a Domino addin task. When LEI has been installed to run as a Domino addin task the LEI console is suppressed. On the iSeries server, LEI is installed only as a Domino addin task. This being the case, the LEI console is suppressed and does not display as a separate console on the iSeries. LEI console commands can be performed by using the tell command from the Domino server console to instruct LEI to perform a console operation. 76 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server The command has the following format: tell lei <command> Commands that can be issued are displayed in Table 3-1. Table 3-1 LEI console commands LEI command Domino server console command Description Help tell lei help Displays a brief description of the LEI server commands. List tell lei list Displays a list of activities that are currently being executed by this LEI server. The number associated with each Activity name must be used with the Close and Kill commands issued from the LEI Administrator. Status tell lei status Displays basic configuration information about this LEI server, as well as server time and status. Quit tell lei quit Shuts down the LEI server and all LEI Activities 3.4.1 LEI Administrator database The LEI Administrator database, decsadm.nsf, enables the operator to: Configure: – Connection documents to external sources – Activities operating on the defined connectors – LEI servers controlled by that LEI Administrator Activate and deactivate configured activities View which servers and activities are operating Stop the operation of an LEI server controlled by that LEI Administrator View logs for servers or activities controlled by that LEI Administrator Access reference material Figure 3-35 displays the LEI Administrator database used to control the operation of the LEI server. The administrator has three distinct areas of activity: Navigator frame Working frame Active View frame Chapter 3. Installation and configuration on the iSeries platform 77 Figure 3-35 LEI Administrator database Navigator frame The Navigator enables administrators to configure and control the operational LEI environment. Broken down into five areas, as displayed in Figure 3-36, the administrator has the ability to: View configuration documents The top section provides the administrator a mechanism to view, create, modify or delete configuration documents for LEI. Organize projects The second section in the navigator enables the administrator to create folders for each project controlled through that LEI Administrator. This allows administrators to drag and deposit configuration documents of servers, connectors and activities associated with those projects. View reference material The help section provides a place where the administrator is able to quickly access the: – – – – – 78 User Guide LotusScript Extension Guide Lotus Connectors Guide Installation Guide About this Database Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server User assistance User assistance can be enabled for Advanced RealTime activities and connection documents. To enable or disable user assistance click the button Turn User Assistance On/Turn User Assistance Off. When turned, on user assistance prompts a user through the creation of an Advanced RealTime activity. With connection documents explanatory information is displayed at the top of the connection document when being created or edited. Access log entries The bottom section provides a link to the LEI log file that displays log entries for the LEI servers being controlled and the activities that have previously been run or are presently active. Figure 3-36 LEI Administrator database, Navigation frame Working frame The working frame, shown in Figure 3-37, displays the contents of the view selected in the navigator frame. At the top of the working frame is an action bar that is present regardless of what is displayed in the body of the frame. The action bar provides access to create new connection and activity documents. Chapter 3. Installation and configuration on the iSeries platform 79 Figure 3-37 LEI Administrator database, Working frame Active View frame The Active View frame, displayed in Figure 3-38, provides the administrator the ability to view all live servers and activities controlled by LEI. Through the action bar the administrator can stop live activities or view the associated log entries. Figure 3-38 LEI Administrator database, Active view frame 3.4.2 Configuration Clicking on Configuration in the Navigation frame enables you to configure certain aspects of the LEI server and administrator by accessing both the LEI Server Configuration document and the LEI Administrator Configuration document. Figure 3-39 displays the LEI Server Configuration document. 80 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 3-39 LEI Server Configuration document Note: If Advanced RealTime is being enabled after completion of the installation process by selecting the Advanced RealTime checkbox displayed in Figure 3-39, review the Domino server’s Notes.ini file. If not present, the entry, EXT_ADDINS=DECSEXT must be added. Table 3-2 reviews the parameters in the LEI Server Configuration document and how the values modifies operation of the server. Table 3-2 LEI Server Configuration document parameters Field Description Current Status Specifies the status of the server. This information cannot be modified directly. The status is Active or Inactive. Last Broadcast Specifies the date and time that the Administrator last received a status update from the server. Like the Current Status, this information cannot be modified. The frequency of broadcasts is the one entered in the LEI Administrator Configuration document. See Figure 3-40. Server Name Specifies the name of the LEI server given at install time. This information cannot be modified. Poll Interval Specifies the interval at which the LEI server polls the Administrator database to see if there are any activities that it needs to execute. Chapter 3. Installation and configuration on the iSeries platform 81 Field Description Maximum Number of Activities Specifies the greatest number of concurrent activities that the server will run. Once the server is running the maximum number of activities, it postpones additional activities until existing activities are concluded. Zero stands for no maximum. Maximum Duration of Activities Specifies the longest duration, in minutes, that the server will run any single activity. The server automatically closes any activity that exceeds this duration. Zero stands for no time out. Maximum Consecutive Failures Specifies the greatest number of consecutive failures that a single activity can have before the server no longer schedules it for execution. Zero stands for no disabling Activity Shutdown Request TimeOut Specifies the amount of time in seconds that an activity has to respond to a close command before it is terminated. Zero stands for no time out. Domino Server Name of the server that hosts Domino. It may be the same as or different from the server that LEI has been installed on. Advanced RealTime Enabled Select this checkbox to notify LEI that the specified Domino server can run Advanced RealTime activities. The parameters in the LEI Administrator Configuration document, displayed in Figure 3-40, modifies how the LEI Administrator operates. Figure 3-40 LEI Administrator Configuration document How these parameters modify the operation of LEI Administrator are documented in Table 3-3. Table 3-3 LEI Administrator configuration parameters 82 Field Description Log Database Specifies the file path and name of the LEI log database on the Domino server, relative to the Domino server’s data directory. Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Field Description LEI Help Database Specifies the file path and name of the LEI help databases on the Domino server, relative to the Domino server’s data directory. Scripted Agent Database Specifies the file path and name of the optional repository for Scripted Agents, relative to the Domino server’s data directory. Status Broadcast Interval Specifies the interval, in minutes, at which each running LEI server must notify the Administrator database of its status. Any LEI server that fails to update its status in three of these time periods is assumed to have terminated abnormally. The interval value must be entered in minutes and defaults to a value of 60. The status of the server is reported in the LEI Server Configuration document along with the date and time of the last broadcast received. See Figure 3-39. LEI clustering An LEI clustered environment is when you have one LEI Administrator controlling multiple LEI servers. This is distinct from a Domino cluster that keeps replica databases on clustered Domino servers synchronized for load balancing and fail over. The benefit of an LEI cluster is the ability to have a single point of administration for multiple LEI servers. Note: To refer to the administration of servers that are in an LEI clustered environment and their LEI Administrator database is stored on a remote server, the term remote administration is often employed. This is to reduce confusion between LEI clustering and Domino clustering. LEI servers that are remotely administered are unable to be used for Advanced RealTime activities. In an LEI clustered environment the only server that is able to operate Advanced RealTime activities is the LEI server that hosts the LEI Administrator database, decsadm.nsf, operating locally. If a remotely administered server has the Advanced RealTime checkbox enabled, displayed in Figure 3-39, all Advanced RealTime activity documents are likely to have difficulty being started. The only method of configuring an LEI cluster is through the installation procedure. In the installation process for LEI, step 11 on page 67 displays a window requesting the name of this LEI server and which Domino server to create the LEI Administrator database. If this is the first LEI server being established, and will be the server from which to administer the LEI servers then fill out the fields in the window as displayed in Figure 3-21 on page 68. If this is an additional LEI server in an already existing cluster, perform the following steps: 1. Enter the new LEI server name in the field labeled LEI Server Name. In the field labeled Domino Server Name, enter the name of the Domino server that hosts the LEI Administrator database. See Figure 3-41. Click Next to continue. Note: Currently the entry in the Domino Server Name field must matched what is listed in the Mail Server field located at the bottom of the Basics tab in the Domino server document. This will be rectified in a future release of LEI. For details about this current limitation, refer to the following technotes: http://www.ibm.com/support/docview.wss?rs=203&q=1107988&uid=swg21107988&loc=en_US&cs=utf-8&lang=en+en http://www.ibm.com/support/docview.wss?rs=203&q=1107264&uid=swg21107264&loc=en_US&cs=utf-8&lang=en+en Chapter 3. Installation and configuration on the iSeries platform 83 Figure 3-41 InstallShield - LEI server identification and LEI Administrator database location 2. The next window that appears, displayed in Figure 3-42, informs the user that it has detected that there is already an LEI Administrator on the server listed. This is to be expected as we are telling it to add the new LEI server configuration details to an already existing LEI Administrator in the cluster. Click Next to continue. Figure 3-42 InstallShield - Informational message 84 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 3. You are now asked if the Domino server is on the machine that we are installing to. Click No to continue with the installation process at step 12 on page 68. Figure 3-43 InstallShield - Confirmation message 4. With completion of the LEI installation process and the initial starting of the LEI server, the LEI Administrator Active View frame will display multiple operational servers as shown in Figure 3-44. Figure 3-44 Active View frame showing an LEI clustered environment 3.4.3 Starting and stopping the LEI server There are a number of ways to start and stop the LEI server. This section reviews how to control the operation of the LEI server through: Notes.ini file, providing automatic loading The Domino server console The LEI Administrator database Automatic loading The installation process automatically places LEI in the ServersTasks line of the Domino server’s Notes.ini file on the iSeries platform. If LEI is not to be loaded automatically, then the Notes.ini file should be edited and the LEI entry removed from the ServersTasks= line. Similarly if LEI has been removed and it is desired to load LEI automatically, edit the Domino server’s Notes.ini file and add the LEI entry to the ServersTasks= line. Domino server console To start LEI via the Domino server console enter the following command: load lei To stop the LEI server via the Domino server console enter the following command: tell lei quit LEI Administrator database Through the LEI Administrator there are two options for stopping the selected LEI server. Both are located under the Actions menu, as displayed in Figure 3-45. Selecting the Chapter 3. Installation and configuration on the iSeries platform 85 pull-down menu options Actions -> LEI Server Administration -> Shutdown Server stops the selected LEI server after all live activities have successfully shutdown. Selecting the pull-down menu options Actions -> LEI Server Administration ->Stop Server stops the selected LEI server immediately, without waiting for live activities to successfully shutdown. Figure 3-45 Lotus Administrator, stopping the LEI server 86 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 4 Chapter 4. Migrating from Lotus Enterprise Integrator 3.x All existing LEI 3.x connection and activity documents must be migrated in order to be recognized by LEI 6. LEI 6 provides a migration utility to perform this task. The migration utility also enables you to migrate multiple DECS Administrators to a single LEI Administrator. In addition, it enables you to migrate the contents of the LEI 3.x Script Vault (LEI LSX scripts) to LotusScript Extensions for Lotus Connectors (LC LSX) format to the target LEI 6 Script Vault. This chapter provides an overview of migrating from Lotus Enterprise Integrator (LEI) 3.x to LEI 6.0.1and discusses the following topics: Considerations to address when migrating to LEI 6.0.1. What pre-migration activities need to be addressed. The process of migration. © Copyright IBM Corp. 2003. All rights reserved. 87 4.1 Migration considerations With LEI, migration is often synonymous with upgrading from the a previous release. While they are often talked about as being the same activity it is important to separate the two tasks, that is the task of upgrading the LEI server and the task of migrating activity documents, connection documents and LotusScript agents. The process of upgrading the LEI server is taken care of by installing the new LEI code, this is discussed in Chapter 3, “Installation and configuration on the iSeries platform” on page 49. This process is only performed once and replaces the 3.x version of LEI with LEI 6.0.1. The new LEI Administrator database is decsadm.nsf which is different to the DECS Administrator database. The leiadm.nsf is no longer used in LEI 6.0.1 but is not removed during the installation process, which makes it available for the process of migration. After the LEI server has been upgraded, the migration of the LEI 3.x documents can take place. The migration process can be performed multiple times, though care is required to be taken for documents with duplicate names as discussed in 4.1.4, “Duplicate connection and activity documents” on page 89. As discussed in 3.1.4, “Domino Enterprise Connection Services (DECS)” on page 55, existing activity and connection documents are automatically migrated as part of the process of installation. The LEI migration utility can also be run separately. For general considerations pertinent to migrating from the LEI Administrator or Script Vault, see the Migration chapter of the LEI Installation Guide supplied with the LEI product and also available on the Lotus Developers Domain Documentation Library at: http://www.lotus.com/ldd 4.1.1 Migrating scripted documents The process of migration also migrates agents stored in the script vault (leivlt.nsf) to the LEI 6.0.1 script vault (leivlt6.nsf). The LEI LSX used in scripts for LEI 3.x was retired and now the standard LotusScript Extensions for Lotus Connectors (LC LSX) is used in scripted agents. The process of migration will alter the entry Uselsx “*lsxlei” to Uselsx “*lsxlc”. The migration will only migrate agents that are stored in a script vault named leivlt.nsf. If the site has scripted activity documents calling scripts stored in vaults named differently it is important to copy the agents to the script vault that is named leivlt.nsf prior to migrating them. After the process of migration has completed they can be copied back to the vault they came from at a later time if desired. The process of migration will not migrate scripts stored in a script library. These script files must be copied and altered manually. The agent that uses the script file in a script library but the library itself will not be migrated. If you operate the process of migration multiple times, duplication of script names are not checked so be careful. Important: Ensure that the LEI 3.x script vault that is being used for the script migration is named leivlt.nsf. 88 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 4.1.2 Migrating metaconnection documents Metaconnection documents in LEI 3.x did not require that the underlying connection document to have metadata selected. With LEI 6.0.1 it is required that the underlying connection document of a meta connector has metadata selected. This new requirement will prevent migrated metaconnection documents from operating properly. To correct the issue, after migration, open the underlying connection documents of all metaconnection documents and define the metadata. Note: If you have existing activities that are already working, adding metadata to a connection document will not break them, since the metadata specified in the activity will override this. 4.1.3 LEI clustering and remote administration An LEI clustered environment can cause complexities in relation to the process of migration. If the server that is being upgraded is being made part of an LEI cluster where the LEI Administrator database resides on a remote server, it is recommended to complete the installation prior to performing the process of migration outlined in 4.3, “Process of migration” on page 92. If the LEI Administrator database resides on the same LEI 6 server, the migration process is straight forward and can be undertaken without additional activity. When the LEI 6 Administrator database is on a remote server to the one being migrated, perform the following steps: 1. From a Notes client, click the pull-down menu options of File -> Replication -> New Replica to create a replica of the remote decsadm.nsf database on the server being migrated. Call the new replica decsadm.nsf. 2. Invoke the migration tool as described in 4.3, “Process of migration” on page 92. 3. From a Notes client, click the pull-down menu options of File -> Replication -> Replicate to send the changes made by the migration tool back to the remote administration server. Make sure to replicate with options. 4. Open the LEI Administrator and select the pull-down menu options of Actions -> RefreshAllDocuments. Step 4 is used to re compute all the computed fields from the documents that have been migrated. Before the migrated documents are used for the first time these computed fields are required to be updated. 4.1.4 Duplicate connection and activity documents As the process of migration can be performed after LEI 6.0.1 has been in operation for some time, when time presents itself to perform the migration the operator may be faced with connection and activity documents in the 6.0.1 LEI Administrator that have the same names as those that are in the 3.x LEI Administrator. Additionally as the migration tool may be run multiple times duplicate names are again likely to occur. If it occurs during migration that duplicate names of activity and connection documents should exist, then the operator will be requested to respond on how to proceed with these duplicates as displayed in both Figure 4-12 on page 97 and Figure 4-13 on page 98. There are three options presented: Rename the connection or activity document being migrated with a suffix that the operator enters in the field available. Chapter 4. Migrating from Lotus Enterprise Integrator 3.x 89 Overwrite the existing document in the 6.0.1 LEI Administrator with the document in the 3.x LEI Administrator. Skip duplicate documents from the 3.x LEI Administrator, not adding them at all to the 6.0.1 LEI Administrator. If renaming the documents by adding a suffix, the operator must be careful if the migration process has been performed more than once. The migration document will continue migrating the documents, as it has been instructed to, without further checking naming conflicts. The outcome could end up with multiple documents holding the same name and suffix. 4.2 Pre-migration activities Prior to performing the process of migration, the activities discussed in this section are required to be addressed. Domino server’s data directory If the process of migration is performed after the installation of LEI 6 has completed, the operator will be asked to enter the path of the Domino server’s data directory. The path can be identified prior to installation through either the iSeries Navigator or through the CL interface on the iSeries server. Perform the following steps to identify the Domino server’s data directory using iSeries Navigator: 1. Open the iSeries server that has the Domino server installed. 2. Click Network -> Servers -> Domino, as displayed in Figure 4-1. Figure 4-1 iSeries Navigator - Domino Servers 3. Right-click the Domino server that you are performing the migration on and click Properties from the popup menu. 4. The Properties window will be displayed, as shown in Figure 4-2, where you are able to identify the data directory under the Basics tab. 90 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 4-2 iSeries Navigator - Domino server properties, Basics tab Perform the following steps to identify the Domino server’s data directory using the OS/400 CL command interface: 1. On the iSeries server 5250 emulation screen, enter the Work with Domino Servers (WRKDOMSVR) CL command and press Enter. 2. On the Work with Domino Servers display, press the F11 key twice to display the data directory paths of the Domino servers listed. See Figure 4-3. Work with Domino Servers System: AS06 Type options, press Enter. 1=Start server 2=Change server 5=Display console 6=End server 7=Submit command 8=Work console 9=Work server jobs 11=Change current directory 12=Work object links 13=Edit NOTES.INI Domino Opt Server LEIDOMSVR Subsystem LEIDOMSVR Path /domino/leidomsvr Bottom Parameters or command ===> F3=Exit F4=Prompt F5=Refresh F11=Display status F12=Cancel F9=Retrieve F17=Top F10=Sort by name F18=Bottom F24=More keys Figure 4-3 Work with Domino Servers display, showing the data directory path Chapter 4. Migrating from Lotus Enterprise Integrator 3.x 91 Backup environment Prior to the upgrade of any software a complete backup of the environment should be undertaken to enable the possibility of restoring should the upgrade not perform as planned. In particular with migrating LEI it is important to make backups of the LEI Administrator and Script Vault databases prior to performing any actions on those database files. Upgrade Domino Before the upgrade of the LEI server can be undertaken, ensure the Domino server has been upgraded from Domino R5.x to Domino 6.0.1. For details about upgrading from Domino for iSeries R5.x to 6.0.1 see the redbook IBM Lotus Domino 6 for iSeries Implementation, SG24-6592. Install LEI 6.0.1 Once the Domino server has been upgraded and is operational, the upgrade of the LEI server from LEI 3.x to LEI 6.0.1 can be addressed. Chapter 3, “Installation and configuration on the iSeries platform” on page 49 addresses the requirements for installing LEI 6.0.1 and the process of installation. 4.3 Process of migration The process of migration can be performed at the time of installation or after installation is complete and LEI is operational. To perform the migration process on an iSeries LEI server, after the installation process has completed, perform the following steps. The Domino server must be running, but LEI does not need to be active. If the migration is to be undertaken as part of the installation process, Figure 4-11 on page 96 will be the first screen presented in the process of migration. In that instance begin following the process of migration from step 8 on page 96. Note: Support recommends the migration process be launched on it own instead of being done as part of the LEI installation process. The reason being is that the LEI log file is unreadable when migration is done as part of the installation process. 1. To initiate the migration process on the workstation, run the program file iSetupMigration.exe. A screen appears, displayed in Figure 4-4, indicating that the InstallShield Wizard is being loaded. Figure 4-4 InstallShield - Java Virtual Machine 2. Once the Java Virtual Machine (JVM) has been initialized a welcome screen is displayed, as shown in Figure 4-5. Click Next to continue. 92 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 4-5 Install Shield - Migration welcome page 3. The next screen that appears, displayed in Figure 4-6, is to verify the IP address of the PC workstation from which you are running the migration process. Verify that the IP address is correct and click Next to continue. Figure 4-6 Install Shield - PC workstation IP address Chapter 4. Migrating from Lotus Enterprise Integrator 3.x 93 4. During migration, the process accesses a number of files in the data directory of the Domino server. The operator will be requested to provide the path to the Domino server data directory on the iSeries server, as displayed in Figure 4-7. By default the field comes up blank, enter the Domino server’s data directory path. Click Next to continue. Figure 4-7 Migration Install Shield - Domino server’s data directory 5. A window indicating the progress of installation is displayed, as shown in Figure 4-8. Do not click any buttons or close the screen unless intending to cancel installation. 94 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 4-8 Migration Install Shield - Progress indicator 6. A prompt for the operator to log onto the iSeries server, as shown in Figure 4-9, appears. Enter the host name of the iSeries server into the System field, the OS/400 user profile that has the required security access, and the password for that user ID. Click OK. Figure 4-9 iSeries sign on 7. The Remote-AWT program file displayed in Figure 4-10 is loaded, with a number of other screens. Be patient and do not close any windows. Figure 4-10 Remote-AWT Daemon Chapter 4. Migrating from Lotus Enterprise Integrator 3.x 95 8. When the Migration Utility welcome screen appears, as displayed in Figure 4-11, the operator will have to enter relevant information as to the server performing the migration. The window requests that the following information be provided: – – – – – Domino server name of the server performing the migration. The file name of the LEI 3.x Administrator database. The name of the Domino server that performs the Advanced RealTime activities. Is it desired to backup the present LEI 6 Administrator database. Is it desired to migrate the ACL entries across from the 3.x LEI Administrator database. Click Migrate to continue. Figure 4-11 Migration Utility - Welcome screen 9. Should a conflict exist between the names of connection documents used in the LEI 3.x Administrator database and the names use in existing connection documents in the LEI 6.x Administrator database, the operator will be presented with the display shown in Figure 4-12. The operator has the opportunity to select one of the following options: – Rename the LEI 3.x connection documents appending the suffix of their choosing to all conflicted documents by entering a value in the Chose Conflict Suffix box. – Overwrite existing LEI 6.x connection documents with the LEI 3.x versions of the connection documents. – Skip migrating the connection documents that have a conflict with their names. 96 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server The option selected applies to all conflicts, there is no option to modify a subset of the connection documents. Click Continue Migration. Figure 4-12 Migration Utility - Conflict with connection document names Note: If there are no conflicts between names of connection documents, Figure 4-12 will not be displayed. 10.Should a conflict exist between the names of activity documents used in the LEI 3.x Administrator database and the names use in existing activity documents in the LEI 6.x Administrator database, the operator will be presented with the display shown in Figure 4-13. The operator has the opportunity to select one of the following options: – Rename the LEI 3.x activity documents appending the suffix of their choosing to all conflicted documents by entering a value in the Chose Conflict Suffix box. – Overwrite existing LEI 6.x activity documents with the LEI 3.x versions of the activity documents. – Skip migrating the activity documents that have a conflict with their names. The option selected applies to all conflicts, there is no option to modify a subset of the activity documents. Click Continue Migration. Chapter 4. Migrating from Lotus Enterprise Integrator 3.x 97 Figure 4-13 Migration Utility - Conflict with activity document names Note: If there are no conflicts between names of activity documents, Figure 4-13 will not be displayed. 11.The next window to be displayed, as shown in Figure 4-14, is the progress monitor for the migration utility. 98 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 4-14 Migration utility - progress indicator 12.If a scripted activity document was found in the LEI 3.x Administrator database, the window displayed in Figure 4-15 is shown. It will appear for the first agent in the script vault then depending on the response selected will decide whether it is displayed again. If Migrate is clicked, it will migrate that agent and prompt again when the next agent is being processed. If Don’t Migrate is clicked, it will not migrate that agent and then will prompt for the next agent to be processed. If Migrate All is clicked, then all agents will be processed and the migration utility will not prompt with this window again. Chapter 4. Migrating from Lotus Enterprise Integrator 3.x 99 Figure 4-15 Migration Utility - migrating the script vault 13.If an agent uses script stored in a script library a window as shown Figure 4-16 is displayed, indicating that agents in script libraries will have to be migrated manually. This is just an informational window indicating that after the migration is completed any scripts located in a script library, as discussed in 4.1.1, “Migrating scripted documents” on page 88, will have to be migrated manually. Click OK to continue. Figure 4-16 Migration Utility - Script library detected 14.Upon completion, Figure 4-17 is displayed. Click Finish to complete the migration. 100 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 4-17 Migration Utility - Completion window 15.After migration has completed, the first time the LEI Administrator is opened, click the pull-down menu options of Actions -> RefreshAllDocuments. As mentioned earlier, this is done to recompute all the computed fields from the documents that have been migrated. Before the migrated documents are used for the first time these computed fields are required to be updated. 16.Also upon completion of migration, all windows associated with the migration utility will close. If the process of migration was part of the installation process you will return to the step 18 on page 72. Otherwise if the migration utility was performed after the process of installation, the operator is now complete. 17.Any scripts that are stored in the LEI 3.x script vault should now be manually copied to the new script vault, leivlt6.nsf. Do not forget to modify where appropriate. 18.Test all migrated activity documents to verify a successful migration has been performed. 4.4 Troubleshooting If migration is not operating as expected, review the following areas: LEI 6.0.1 has been successfully installed and operating as expected. Confirm that the LEI Administrator is on the server being migrated. Chapter 4. Migrating from Lotus Enterprise Integrator 3.x 101 Confirm the user profile used to sign on to the iSeries server has the appropriate access rights as discussed in 3.3, “Installation of LEI” on page 60. If the LEI 3.x Administrator has been copied using a Notes client, was the process of creating a new copy told to copy the ACL? It is important not to delete ACL entries prior to migration. Review the Domino server’s log.nsf file. Review migration log (migration.log). This is discussed in the next section. 4.4.1 Migration log file To review how the migration process has performed, review the migration log file (migration.log). This file is located on the iSeries server under the following Integrated File System (IFS) path: /QIBM/ProdData/LOTUS/NOTES This file, displayed in Figure 4-18, displays the actions undertaken by the process of migration. For instance if the operator was seeking if there was a difficulty with the transfer of a connection document, this log file would display the connection documents name and whether the transfer was successful. Migration Log 05/30/2003 04:47:40 The LEI administrator has been backed up to decsadm_1.nsf Migration Log 05/30/2003 04:47:40 Duplicate ACL entry, -Default-. ACL entry will not be added Migration Log 05/30/2003 04:47:40 Duplicate ACL entry, OtherDomainServers. ACL entry will not be added Migration Log 05/30/2003 04:47:40 Duplicate ACL entry, CN=Ian Barrack/O=ITSO. ACL entry will not be added Migration Log 05/30/2003 04:47:40 Duplicate ACL entry, LocalDomainServers. ACL entry will not be added Migration Log 05/30/2003 04:47:40 Duplicate ACL entry, CN=Enterprise Connector Products/O=Lotus Notes Companion Products. ACL entry will not be added Migration Log 05/30/2003 04:47:40 Duplicate ACL entry, CN=LEI3DomSvr/O=ITSO. ACL entry will not be added Migration Log 05/30/2003 04:47:41 Connection AS06 DB2 Employee has been transferred Migration Log 05/30/2003 04:47:41 Connection DB2 Connection has been transferred Migration Log 05/30/2003 04:47:41 Connection Employee Profile has been transferred Migration Log 05/30/2003 04:47:41 Connection Notes Connection to Casefile.nsf has been transferred Migration Log 05/30/2003 04:47:41 Activity Direct Emp has been transferred Migration Log 05/30/2003 04:47:42 Activity Direct Transfer of Case Files has been transferred Migration Log 05/30/2003 04:47:42 Activity Employee has been transferred Migration Log 05/30/2003 04:47:43 Scripts not migrated -- Unable to open LEI 6 Script Vault (leivlt6.nsf) Migration Log 05/30/2003 04:47:43 Scripts not migrated, unable to open Source R5 script vault Figure 4-18 Migration.log file 102 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 5 Chapter 5. Base connectivity This chapter provides information about connecting your iSeries to other iSeries servers and to other eServers. The specific scenarios that will be detailed include: Connecting from iSeries server to iSeries server. Connecting from xSeries server to iSeries server. Connecting from iSeries server to pSeries server. © Copyright IBM Corp. 2003. All rights reserved. 103 5.1 Distributed Relational Database Architecture (DRDA) Distributed Relational Database Architecture™ (DRDA) is the underlying architecture that makes connectivity between various systems possible. This architecture defines the rules, protocols, and semantics for implementing distributed data access. All the platforms participating in this architecture must comply with these rules and definitions. DRDA allows you to access data in a distributed relational database environment by using SQL statements to access data. The architecture has been designed to allow distributed data access for systems in like and unlike operating environments. This means applications can access data residing on homogenous or heterogeneous platforms. SQL has become the most common data access language for relational databases in the industry. SQL was chosen as part of DRDA because of its high degree of standardization and portability. In a distributed environment, where you want to access data at remote locations, the SQL requests are routed to the remote system and executed remotely. Prior to sending the remote SQL request, a DRDA application must establish a connection with the remote relational database where the data is located. This is the purpose of the CONNECT SQL statement provided by DRDA. There are three main components that comprise DRDA: Application Requester (AR) Application Server (AS) Database Server (DS) The Application Requester is the system running the application and sending the SQL requests across the network. Any remote system that executes SQL requests coming from the application requester is known as the Application Server. The iSeries server can be both an AR and an AS. In most scenarios, the AS is also the Database Server. Keep in mind that with the iSeries server, because DB2 UDB support is built into the operating system, both the AR and the AS are Database Servers. For more information about DRDA, see the redbook Advanced Functions and Administration on DB2 Universal Database for iSeries, SG24-4249. 5.2 iSeries to iSeries Now that we have a basic understanding of how DRDA works, let’s look at how to set up the environment for the Domino for iSeries integration functions to access a remote DB2 UDB database on another iSeries server. Remote DB2 connectivity is done through DRDA. All DRDA support is part of the base OS/400 operating system. DRDA defines the protocols by which an SQL application can access remote tables and data. DB2 UDB on iSeries participates in this architecture, the same as all products in the DB2 family. An additional product, called DB2 Information Integrator, provides support for non-IBM relational sources, such as Oracle, Sybase, SQL Server, and other RDBMSs in a DRDA environment. Note: The DB2 Information Integrator product was formerly known as the DB2 Data Joiner product. You may still find references on the Web sites to the DB2 Data Joiner product. 104 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server More information about DRDA and DB2 Information Integrator can be found at the Web site: http://www.ibm.com/eserver/iseries/db2 5.2.1 Connecting from an iSeries server to an iSeries server Figure 5-1 provides a graphical representation of the connectivity detailed in this section. The AR iSeries server hosts the LEI 6.0.1 server. This LEI server will connect to the AS iSeries server and manipulate the DB2 UDB databases residing on this remote server. For this to be possible, DRDA and DDM need to be active on both the AR and AS servers. Additionally, the AS server needs to have a *local RDBDIRE and the AR server needs to not only have a local RDBDIRE, but it also needs to have a remote RDBDIRE that points to the AS server. AS iSeries server - AS08 AR iSeries server - AS06 DB2 UDB Domino 6.0.1 LEI 6.0.1 Data files DRDA server DDM DRDA DRDA server DDM DRDA DRDA over TCP/IP using ports 446 and 447 RDBDIREs: AS08 *local RDBDIREs: AS06 *local AS08 10.4.86.105 Figure 5-1 iSeries to iSeries DRDA connectivity example 5.2.2 Creating a local relational database directory entry The first step to setting up connectivity to be able to connect from one iSeries server to another is to create a local relational database directory entry (RDBDIRE) on both the AR and AS systems. Setup a local RDBDIRE for the AR system Each system in the network that has a relational database directory must have a unique RDBDIRE name. In this example we are showing the AR system has a local RDBDIRE called AS06. The name that is used here does not matter, it could match the name of the iSeries server or be a completely different name. Perform the following steps to create a local RDBDIRE for the AR system: 1. To see if a RDBDIRE entry exists for the AR system, issue the OS/400 CL command of Work with Relational Database Directory Entries (WRKRDBDIRE). If a local entry does not exist, use the OS/400 CL command of Add Relational Database Directory Entry (ADDRDBDIRE) or select option 1 (Add) from the Work with Relational Chapter 5. Base connectivity 105 Database Directory Entries display to create one. See Figure 5-2. The only parameters you need to be concerned with are the following: – Relational database Provide a name that will identify this system distinctly in the network. In the example shown in Figure 5-2, the relational database name provided is AS06. Note: It is important to provide a name that is able to be resolved through TCP/IP on your network. It is highly recommended that you provide the same name for the RDBDIRE name as what the TCP/IP name is for the system. – Name or address The correct value for this parameter is *local. This will identify the RDBDIRE as local to this system. – Type This parameter specifies the communication protocol you with to use. The default is *SNA, you will most likely want to change this to *IP to use TCP/IP. You should leave all of the remaining parameters set to their default values. Note: There is no comparable function in the iSeries Navigator graphical interface to create a relational database directory entry. Add RDB Directory Entry (ADDRDBDIRE) Type choices, press Enter. Relational database . . . . . . > AS06 Remote location: Name or address . . . . . . . > *local Character value Type . . . . . . . . . . . . . > *IP Text . . . . . . . . . . . . . . *BLANK *SNA, *IP Port number or service program Remote authentication method: Preferred method . . . . . . . Allow lower authentication . . *DRDA F3=Exit F4=Prompt F24=More keys F12=Cancel F5=Refresh *ENCRYPTED *ALWLOWER *USRID, *USRIDPWD... *ALWLOWER, *NOALWLOWER Bottom F13=How to use this display Figure 5-2 Adding the *local RDBDIRE on the application requester 2. Now that you have created the local RDBDIRE, you should verify the relational database directory entry was added correctly. If you do not still have the Work with Relational Database Directory Entries display open, issue the WRKRDBDIRE CL command to verify the local RDBDIRE has been added successfully. Any system in the distributed relational database network that acts as an AS does not need to include the RDBDIRE names of other remote relational databases in its directory. 106 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 3. Figure 5-3 illustrates what the local RDBDIRE will look like when you have finished creating it. Work with Relational Database Directory Entries Position to . . . . . . Type options, press Enter. 1=Add 2=Change 4=Remove Option 5=Display details 6=Print details Relational Database Remote Location Text AS06 *LOCAL Local RDBDIRE entry for Bottom F3=Exit F5=Refresh F6=Print list F12=Cancel Figure 5-3 Local RDBDIRE for the application requester Setup a local RDBDIRE for the AS system In order to access the data on the remote AS system, you first need to ensure there is a RDBDIRE entry created for *local on that system. Perform the following steps to create a *local RDBDIRE on the AS system: 1. To see if a RDBDIRE entry exists for the AS system, issue the OS/400 CL command of Work with Relational Database Directory Entries (WRKRDBDIRE). If a local entry does not exist, use the OS/400 CL command of Add Relational Database Directory Entry (ADDRDBDIRE) or select option 1 (Add) from the Work with Relational Database Directory Entries display to create one. See Figure 5-4. The only parameters you need to be concerned with are the following: – Relational database Provide a name that will identify this system distinctly in the network. In the example shown in Figure 5-4, the relational database name provided is AS08. Note: It is important to provide a name that is able to be resolved through TCP/IP on your network. It is highly recommended that you provide the same name for the RDBDIRE name as what the TCP/IP name is for the system. – Name or address The correct value for this parameter is *local. This will identify the RDBDIRE as local to this system. – Type This parameter specifies the communication protocol you with to use. The default is *SNA, you will most likely want to change this to *IP to use TCP/IP. You should leave all of the remaining parameters set to their default values. Note: There is no comparable function in the iSeries Navigator graphical interface to create a relational database directory entry. Chapter 5. Base connectivity 107 Add RDB Directory Entry (ADDRDBDIRE) Type choices, press Enter. Relational database . . . . . . > AS08 Remote location: Name or address . . . . . . . > *local Character value Type . . . . . . . . . . . . . > *IP *SNA, *IP Text . . . . . . . . . . . . . . Local RDBDIRE entry for system AS08 Port number or service program Remote authentication method: Preferred method . . . . . . . Allow lower authentication . . *DRDA F3=Exit F4=Prompt F24=More keys F12=Cancel *ENCRYPTED *ALWLOWER F5=Refresh *USRID, *USRIDPWD... *ALWLOWER, *NOALWLOWER Bottom F13=How to use this display Figure 5-4 Adding the *local RDBDIRE on the application server 2. Now that you have created the local RDBDIRE, you should verify the relational database directory entry was added correctly. If you do not still have the Work with Relational Database Directory Entries display open, issue the WRKRDBDIRE CL command to verify the local RDBDIRE has been added successfully. Any system in the distributed relational database network that acts as an AS does not need to include the RDBDIRE names of other remote relational databases in its directory. 3. Figure 5-5 illustrates what the local RDBDIRE will look like when you have finished creating it. Work with Relational Database Directory Entries Position to . . . . . . Type options, press Enter. 1=Add 2=Change 4=Remove Option 5=Display details 6=Print details Relational Database Remote Location Text AS08 *LOCAL Local RDBDIRE entry for Bottom F3=Exit F5=Refresh F6=Print list F12=Cancel Figure 5-5 Local RDBDIRE for the application server At this point we are now ready to proceed in setting up the remote DRDA connection to the AS server. 108 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 5.2.3 Creating a DRDA connection to a remote iSeries server Before any connection to the remote database can be activated, the following is an outline of the steps that must be performed: Make sure TCP/IP is active on both the application requester and application server systems. Ensure the communication line used to connect to each iSeries server is active. Ensure both Distributed Data Management (DDM) and DRDA are active on the servers. On the AR system, create a *remote RDBDIRE that identifies the target system and communications protocol which will be used to connect to the AS system. Now that we have outlined the steps involved, let’s examine each step in more detail. In our example the AR iSeries server and the AS iSeries server already have a *local RDBDIRE created. These local entries were created in 5.2.2, “Creating a local relational database directory entry” on page 105. The information provided in this section will show you how to create the connectivity between the AR and AS servers, in particular how to start the DDM and DRDA servers and also how to create an *remote RDBDIRE entry on the AR server for accessing the AS server. Ensure TCP/IP is active on both the AR and AS servers The ping utility is the best way to test connectivity to an iSeries server. 1. Ping either the TCP/IP address of the system or the system name if you have DNS setup in your network. If the ping is successful, you have verified connectivity to the system and can skip the next section. 2. If you are unable to ping the iSeries servers, either TCP/IP is not active on the system or the communication line associated with the iSeries server is not active. To start TCP/IP, enter the following OS/400 CL commands: strtcp strhostsvr *all By issuing the Start TCP/IP (STRTCP) CL command, the TCP/IP communication services will be started. The Start Host Server (STRHOSTSVR) CL command starts all host server daemons including the database server daemon in the QSERVER subsystem. Make sure TCP/IP communication lines are active If you are unable to ping the iSeries server, chances are either TCP/IP is not active on the system or the communication line associated with the TCP/IP address of the system is not active. In the previous section, you were asked to start TCP/IP if it was not active, so we do not need to repeat that step here. Perform the following steps: 1. To check the status of a communication line, issue the OS/400 CL command Configure TCP/IP (CFGTCP) and enter option 1 (Work with TCP/IP interfaces) from the Configure Configure TCP/IP menu. The resulting screen is shown in Figure 5-6. Chapter 5. Base connectivity 109 Work with TCP/IP Interfaces System: Type options, press Enter. 1=Add 2=Change 4=Remove Internet Opt Address 10.1.1.18 10.1.1.59 10.1.1.73 10.1.1.74 10.1.1.75 10.1.1.76 10.1.1.78 127.0.0.1 5=Display 9=Start Subnet Mask Interface Status 255.255.255.128 255.255.255.128 255.255.255.128 255.255.255.128 255.255.255.128 255.255.255.128 255.255.255.128 255.0.0.0 Active Active Active Active Active Active Active Active AS06 10=End Bottom F3=Exit F12=Cancel F5=Refresh F17=Top F6=Print list F18=Bottom F11=Display line information Figure 5-6 Work with TCP/IP Interfaces screen to see interface status of a communication line 2. Press the F11 key to see the Interface Status column shown Figure 5-6. 3. If the status is Active, the line is okay. However, if the status of the communication interface is Inactive, select option 9 (Start) next to the interface and press Enter. This will start the TCP/IP interface. Alternatively you can use iSeries Navigator to see the status of the TCP/IP interface. Perform the following steps: 1. Start iSeries Navigator and expand the iSeries server you are verifying the interface on. 2. Expand Network -> TCP/IP Configuration -> IPV4. 3. Click Interfaces. A listing of all IP addresses defined on your iSeries server is listed. 4. If the interface is not active, right-click the specific interface and click Start. Verify that DDM and DRDA are active Perform the following steps to verify that DDM and DRDA are active: 1. Enter the Work with TCP/IP Network Status (NETSTAT) CL command. See Figure 5-7. 110 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Work with TCP/IP Network Status System: AS06 Select one of the following: 1. Work with TCP/IP interface status 2. Display TCP/IP route information 3. Work with TCP/IP connection status Selection or command ===> F3=Exit F4=Prompt F9=Retrieve F12=Cancel Figure 5-7 Work with TCP/IP Network Status display 2. From the Work with TCP/IP Network Status menu, enter option 3 (Work with TCP/IP connection status) and press Enter. This will show all of the ports that are active on the iSeries server. If DDM and DRDA are active, you will see both of them listed. See Figure 5-8. Work with TCP/IP Connection Status System: Type options, press Enter. 3=Enable debug 4=End 5=Display details 8=Display jobs Remote Opt Address * * * * * * * * * * * * Remote Port * * * * * * * * * * * * Local Port ftp-con telnet smtp netbios netbios netbios netbios ldap cifs drda ddm ddm-ssl F3=Exit F5=Refresh F9=Command line F15=Subset F22=Display entire field AS06 6=Disable debug Idle Time > 002:50:57 002:52:27 195:37:10 > 410:41:19 > 000:00:15 > 000:00:12 > 013:18:28 000:30:24 005:30:56 000:04:28 410:42:31 410:42:31 State Listen Listen Listen Listen *UDP *UDP Listen Listen Listen Listen Listen Listen F11=Display byte counts F24=More keys More... F12=Cancel Figure 5-8 List of all ports active on the iSeries server 3. By pressing the F14 key, the port number associated with the running application service will be listed, as shown in Figure 5-9. The port number for DDM is 447 and the port number for DRDA is 446. Note: To find if DDM and DRDA are active through iSeries Navigator, you need to know the port numbers associated with the application service. Chapter 5. Base connectivity 111 Work with TCP/IP Connection Status System: Type options, press Enter. 3=Enable debug 4=End 5=Display details 8=Display jobs Remote Opt Address * * * * * * * * * * * * Remote Port * * * * * * * * * * * * Local Port 21 23 25 137 137 138 139 389 445 446 447 448 Idle Time 005:55:25 003:31:45 337:24:17 337:24:17 000:00:34 000:00:27 004:30:41 000:26:54 013:09:36 046:18:26 770:45:45 770:45:45 F3=Exit F5=Refresh F9=Command line F14=Display port names F15=Subset AS06 6=Disable debug State Listen Listen Listen Listen *UDP *UDP Listen Listen Listen Listen Listen Listen More... F11=Display byte counts F12=Cancel F17=Position to F24=More keys Figure 5-9 Displaying port numbers 4. If DDM or DRDA are not active, issue the following OS/400 CL commands: STRTCPSVR SERVER(*DDM) STRHOSTSVR SERVER(*DATABASE) CHGDDMTCPA AUTOSTART(*YES) To verify that DDM and DRDA are active using iSeries Navigator, follow the following steps: 1. Start iSeries Navigator and expand the iSeries server you want to verify the DDM and DRDA activity on. 2. Next expand Network -> TCP/IP Configuration -> IPV4. 3. Click Connections. If DDM is active you will see port 447 listed and if DRDA is active you will see port 446 listed. See Figure 5-9. 112 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 5-10 Displaying the DDM and DRDA ports through iSeries Navigator 4. If you need to start DDM through iSeries Navigator, right-click TCP/IP Configuration and then click Properties. 5. From the TCP/IP Configuration Properties window, as shown in Figure 5-10, click the Servers to Start tab and click to check DDM. Chapter 5. Base connectivity 113 Figure 5-11 Start DDM through TCP/IP configuration properties 6. Click OK and the DDM and DRDA servers will be started. Create a remote RDBDIRE on the AR system The system that will act as the application requester needs to have both a local RDBDIRE and a remote RDBDIRE. The relational database directory entry allows an AR to accept a relational database name from the application and translate this name into the appropriate TCP/IP address or host name and port for the AS system. Alternatively you can use the appropriate Systems Network Architecture (SNA) network identifier and logical unit (LU) name values for communications processing. As of OS/400 V5R2, the RDBDIRE also is used to specify the user’s preferred outbound connection security mechanism. The relational database directory entry allows associating an AR program with a relational database name. Each iSeries server in the distributed relational database network must have a RDBDIRE configured. Each AR in the distributed relational database network must have an entry in it’s RDBDIRE for its local relational database and one for each remote relational database the AR system accesses. Perform the following steps to create a remote RDBDIRE on the AR system: 1. Issue the Work with Relational Database Directory Entries (WRKRDBDIRE) CL command to display the RDBDIRE for the system. 2. On the AR system, you will need both a local RDBDIRE entry and a remote entry for the system that contains the distributed relational data. The local entry should already exist on 114 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server the AR system. If it does not exist see section 5.2.2, “Creating a local relational database directory entry” on page 105 for details about creating a local RDBDIRE. 3. To add a remote RDBDIRE entry, issue the Add RDB Directory Entry (ADDRDBDIRE) CL command and either press the F4 key to prompt or press Enter. Either option will take you to the Add RDB Directory Entry (ADDRDBDIRE) display. 4. On the Add RDB Directory Entry display, press the F9 key to show all parameters. The result is displayed in Figure 5-12. Add RDB Directory Entry (ADDRDBDIRE) Type choices, press Enter. Relational database . . . . . . > AS08 Character value Remote location: Name or address . . . . . . . > '10.4.86.105' Type . . . . . . . . . . . . . > *IP *SNA, *IP Text . . . . . . . . . . . . . . > 'RDBDIRE to remote server AS08' Port number or service program Remote authentication method: Preferred method . . . . . . . Allow lower authentication . . *DRDA F3=Exit F4=Prompt F24=More keys F12=Cancel F5=Refresh *ENCRYPTED *ALWLOWER *USRID, *USRIDPWD... *ALWLOWER, *NOALWLOWER Bottom F13=How to use this display Figure 5-12 Add RDB Directory Entry command 5. The name of the remote RDBDIRE entry must match the name the AS uses to identify itself. In our example this is AS08. Let’s examine the contents required for each parameter. – Relational database For the Relational database parameter, provide the local RDBDIRE for the remote system. In this example, the system that will be access remotely has a local RDBDIRE of AS08, so we need to create the remote RDBDIRE to be AS08. – Name or address Enter the IP address of the remote system or provide the name of the system as it is known in the DNS network. – Type The type is either SNA or IP. We show you IP here as that is the most common protocol used in the industry today. – Text Use the text field to provide a description of the RDBDIRE you are creating. – Port number or service program This parameter will default to *DRDA. This is the option we want because we are connecting into a remote system and will need the DRDA architecture to do so. Chapter 5. Base connectivity 115 – Preferred method The preferred method specifies the preferred remote authentication method on a DDM/DRDA TCP/IP connection request. Here are some brief details about the available options that will help you to choose the best option for your particular environment. • *Encrypted The userid and associated encrypted password are sent on the DDM connection request. Cryptographic support is required on both systems for this authentication method to work. This value is the default option for this parameter. • *Kerberos Kerberos was introduced to OS/400 in V5R2. This option allows authentication to occur using Kerberos. The RDBDIRE name must map to a target principal name in the Enterprise Identity Mapping (EIM) environment and Kerberos needs to be configured on both systems. • *Usrid Only the userid is sent on the DDM connection request. • *Usridpwd With this option, both the userid and the password are sent on the DDM connection request. Passwords are not encrypted if this authentication method is chosen. – Allow lower authentication This parameter specifies whether an authentication method lower than what was specified for the Preferred Method element of this parameter will be accepted during negotiation with the AS system. Press Enter to create the remote RDBDIRE on the AR system. For more details about the ADDRDBDIRE command and any of the parameters, refer to the iSeries Information Center at: http://www.ibm.com/eserver/iseries/infocenter After selecting the appropriate country (or region) and language, type ADDRDBDIRE in the search box. All of the parameters are detailed in this documentation. 6. The AR system should now have both a local and a remote RDBDIRE. Use the WRKRDBDIRE CL command to display the relational database directory entries configured on the iSeries server. Figure 5-13 shows both a local and a remote RDBDIRE entry on the AR system. 116 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Work with Relational Database Directory Entries Position to . . . . . . Type options, press Enter. 1=Add 2=Change 4=Remove Option 5=Display details Relational Database Remote Location AS08 AS06 10.4.86.105 *LOCAL 6=Print details Text RDBDIRE to remote server Bottom F3=Exit F5=Refresh F6=Print list F12=Cancel Figure 5-13 Local and remote database entries required on the application requester system 5.2.4 Test connectivity using the DCTEST utility You are now ready to test connectivity to the remote system. This can be done using the LEI DCTEST utility. The DCTEST utility ensures that proper connectivity has been configured to access a specific data source. The DCTEST utility is a program that resides in the QNOTES library on the iSeries server. Note: If you are familiar with the LEI Windows environment, the comparable test on that platform is NDCTEST. Perform the following steps to test the connectivity between the AR and AS systems: 1. To invoke the DCTEST utility use the following OS/400 CL command: call qnotes/dctest Calling this program will invoke the screen shown in Figure 5-14. Chapter 5. Base connectivity 117 Lotus Connector Server Connection Verification Test Copyright 2001 Lotus Development Corporation -------------------------------------------This utility will verify connectivity from this machine to the selected type of server. At the prompt, enter the number of the test you would like to run, or enter 0 to exit. 0 - Exit this program 1 - Lotus Notes 6 - DB/2 Run test number: [0] ===> F3=Exit F4=End of File F6=Print F9=Retrieve F17=Top F18=Bottom F19=Left F20=Right F21=User Window Figure 5-14 The DCTEST utility 2. On this screen, enter option 6 (DB/2) and press Enter to test connectivity to the remote AS server. 3. You will be prompted to provide the RDBDIRE of the remote server you want to test connectivity to. In our example, this is AS08. 4. Press Enter to advance to the next required parameter which is the username. Provide a valid OS/400 user profile. 5. Press Enter to continue. The final prompt asks for the password associated with the user ID you specified. 6. After providing the password, press Enter to continue. See Figure 5-15. Note: The input for these three parameters are NOT case sensitive. 118 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server DB2 Connection Verification Copyright 2000 Lotus Development Corporation -------------------------------------------This utility will verify connectivity from this machine to the specified DB2 server. At the prompts, enter a valid DB2 database, username, and password loaded library QSYS/QSQCLI Database (must be registered in RDB Directory, see WRKRDBDIRE): > as08 Username: > kgreene Password (may be case sensitive for remote database): ===> F3=Exit F4=End of File F6=Print F9=Retrieve F17=Top F18=Bottom F19=Left F20=Right F21=User Window Figure 5-15 Providing the RDBDIRE, user ID, and password to connect to the remote AS server 7. After completing the information for the three prompts, you will see these messages as shown in Figure 5-16 indicating that you were able to successfully connect to the remote iSeries AS server. At the prompts, enter a valid DB2 database, username, and password loaded library QSYS/QSQCLI Database (must be registered in RDB Directory, see WRKRDBDIRE): > as08 Username: > kgreene Password (may be case sensitive for remote database): > itso1 Attempting to connect to DB2 AS08 as KGREENE Successfully Connected Successfully Disconnected Connectivity to DB2 Verified. Try Again?: [N] ===> F3=Exit F4=End of File F6=Print F9=Retrieve F17=Top F18=Bottom F19=Left F20=Right F21=User Window Figure 5-16 Confirmation the connectivity test to the remote AS system was successful 8. To exit the DCTEST utility, press Enter at the Try Again?: [N] prompt. You will see the screen shown in Figure 5-17. Chapter 5. Base connectivity 119 > itso1 Attempting to connect to DB2 AS08 as KGREENE Successfully Connected Successfully Disconnected Connectivity to DB2 Verified. Try Again?: [N] > At the prompt, enter the number of the test you would like to run, or enter 0 to exit. 0 - Exit this program 1 - Lotus Notes 6 - DB/2 Run test number: [0] ===> F3=Exit F4=End of File F6=Print F9=Retrieve F17=Top F18=Bottom F19=Left F20=Right F21=User Window Figure 5-17 Exiting the DCTEST utility 9. On this screen, enter option 0 (Exit this program) to exit the DCTEST utility and press Enter. You will need to press Enter again to exit the terminal session. 10.You have now confirmed connectivity to the remote AS server and are ready to proceed with creating LEI connection and activity documents. For details, see chapters Chapter 6, “Connection documents” on page 153, Chapter 8, “Advanced RealTime activities” on page 195, and Chapter 9, “Batch activities” on page 255. 5.3 xSeries server to iSeries server The information in this section describes how to configure and test connectivity from an xSeries workstation or server to a remote DB2 UDB database on a iSeries server. In order to configure this connectivity you need to install a DB2 UDB client on the xSeries machine. Version 8.1 of the DB2 client was used for the example described below. LEI uses the DB2 client code that is installed on the xSeries server to connect to the remote database. For this reason it is important to have the client setup and configured correctly. The steps below outline an example of the steps to configure and test the DB2 client setup on the xSeries server. This configuration is only an example and not all options or features are explored in detail. For more detailed information about the options when configuring the DB2 client, refer to the DB2 Information center that is installed with the DB2 client. 5.3.1 Required software and setup Following are the requirements for the iSeries server: OS/400 version V5R1 or later 120 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server DRDA, DDM activated and a RDB Directory entry on the iSeries server configured. See.5.2.1, “Connecting from an iSeries server to an iSeries server” on page 105 for details. Following are the requirements for the xSeries server: DB2 UDB Connect Client for Windows version 8.1 was used for this example. Network connectivity and ability to ping the iSeries server from the xSeries server. In order to facilitate the setup you should have knowledge of the following: – TCP/IP address or the Host Name of the iSeries server. If a hostname is used then it must be able to be resolved from the xSeries server either by DNS Lookup or an entry in the local Host file. – Port number for DRDA. The default is 446. – Database name. This is the RDB Directory Entry name on the iSeries server. See 5.2.2, “Creating a local relational database directory entry” on page 105 for details. – OS/400 user ID and password. The user ID should have sufficient access to the library and tables you intend to access. This access may need to be raised during the BIND step of the configuration, and can be reduced after the BIND is complete. – Library name and table/file names of the tables you want to access on the iSeries server. – Constraints (Primary Key, Foreign Key) on any of the tables you will insert or update data to. 5.3.2 iSeries DB2 UDB client configuration Perform the following steps to configure the DB2 UDB client to access the iSeries server: 1. After installing the DB2 Connect™ client on the xSeries workstation or server, launch the DB2 Connect Configuration Assistant by clicking Start -> Programs -> IBM DB2 -> Set-up Tools -> Configuration Assistant. If prompted to add a new database, click Yes. 2. From the Add Database Wizard window, click Manually configure a connection to a database. Click Next to continue (Figure 5-18). Chapter 5. Base connectivity 121 Figure 5-18 Configuring a new DB2 client configuration 3. You are now prompted to select a communications protocol. Click TCP/IP. Make sure to also click the check box The database physically resides on a host or OS/400 system. and also click Connect directly to the server (Figure 5-19). Click Next. 122 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 5-19 Selecting a communication protocol 4. You are now prompted to specify the TCP/IP communications protocol (Figure 5-20). Enter the following values: Host name and Service name: Enter either the host name or the TCP/IP address of the iSeries server. If a host name is entered it must be resolvable by the xSeries server, either through a DNS Entry or a Hosts file entry. Port number: The default port for DRDA is 446. Port information should be verified with the iSeries administrator. See “Verify that DDM and DRDA are active” on page 110 for more information. Click Next. Chapter 5. Base connectivity 123 Figure 5-20 Specifying TCP/IP communication parameters 5. You are now prompted to specify the name of the database to which you want to connect (Figure 5-21). The database name is the *Local RDB Directory Entry name on the iSeries server. The database alias is how the database will be known to the local machine. See “Setup a local RDBDIRE for the AS system” on page 107 for more details. Note: As of OS/400 V5R2 there could be several RDB Directory entries on one iSeries server. Click Next. 124 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 5-21 Specify the name of the database to connect to 6. On the Register this database as a data source window (Figure 5-22), this step can be skipped. You could choose not to register the database as an ODBC data source. You should choose to register the database as an ODBC data source if: – You may want to use ODBC connection documents to connect to the DB2 UDB on the iSeries server. – ODBC provides tracing facilities that may help you to debug connection problems. Click Next. Chapter 5. Base connectivity 125 Figure 5-22 Register the database an ODBC data source 7. On the Specify the node options window, specify the operating system (OS/400) as well as the remote instance name (DB2). See Figure 5-23. Click Next. 126 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 5-23 Specify the node options 8. You are now prompted to specify the system options. You must specify the system name where the remote database is located, as well the system’s host name. OS/400 should be specified as the operating system. See Figure 5-24. Click Next. Chapter 5. Base connectivity 127 Figure 5-24 Specify the system options 9. On the Specify the security options window (Figure 5-25), click Server Authentication (SERVER). Click Next. 128 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 5-25 Specify the security options 10.In this example we did not configure any of the optional settings on (Optional) Specify the DCS options for the database (Figure 5-26). Click Finish. Chapter 5. Base connectivity 129 Figure 5-26 Specify optional DCS options Binding DB2 Utilities In order to run SQL select statements it was required that we BIND the correct DB2 utilities. For this process it was required that the user that will be used with DB2 Connect client have the following sufficient privileges (System Administrative (SYSADM) and Database Administrative (DBADM)) or Bind Add (BINDADD) authority on the database in order to perform the bind. Perform the following steps to do the bind: 1. Open the DB2 Client Configuration assistant by clicking Start -> Programs ->IBM DB2 -> Set-up Tools -> Configuration assistant. 2. From the Configuration Assistant window, highlight the database, right-click on it and click Bind. See Figure 5-27. 130 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 5-27 Binding utilities for iSeries access 3. On the Bind window shown in Figure 5-28, select all the utilities listed in the Select utilities or files to bind section. 4. Enter the OS/400 user ID and password that will be used to connect to DB2 UDB on the iSeries server. Click Bind. It may take a few minutes before you see results. Chapter 5. Base connectivity 131 Figure 5-28 Specify binding parameters 5. Once the bind is done, the results screen should look like Figure 5-29. If you see any errors, you will need to debug the problem with the iSeries database administrator. Make sure to wait until you get a message Bind Completed. This may take a few minutes to run. 132 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 5-29 Succesfull bind 5.3.3 Testing connectivity To test that the DB2 UDB Connect client is setup and configured correctly you should test the following items: Connect to the DB2 UDB database on the iSeries server. Do a SQL Select against the library and tables you want to access. Do an insert into the library and tables that you want to access. Run the LEI DCTEST utility. Connect to the database The first test you should do is to confirm that you can simply connect to the DB2 UDB database on the iSeries server that you have just configured. To do this, perform the following steps: 1. Open the DB2 Connect client configuration assistant by clicking Start -> Programs -> IBM DB2 -> Set-up Tools -> Configuration assistant. 2. From the Configuration Assistant window, highlight the database, right-click on it and click Test Connection. See Figure 5-30. Chapter 5. Base connectivity 133 Figure 5-30 Testing connectivity 3. On the Test Connection window (Figure 5-31), select a connection type of CLI and enter the OS/400 user ID and password you want to connect with. Click Test Connection. Figure 5-31 Specify connectivity parameters 4. The results of the test should look like the window in Figure 5-32. If there are any errors, you will need to debug the problem with help from the iSeries administrator. 134 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 5-32 Successful connection SQL Select test The next test confirms that we can run a SQL Select statement against the tables that we want to access on the iSeries server. This test confirms that we have the ability to do more then just connect to the database, but have the required security access levels to access the library and file/tables we want. Perform the following steps: 1. Open the DB2 UDB Command Center by clicking Start -> Programs -> IBM-DB2 -> Command Line Tools -> Command Center. 2. In the DB2 UDB Command Center, click the Interactive tab. 3. In the Command section type the following command: Connect to <database name> user <user name> The database name is the database or database alias that was configured in the DB2 Connect client configuration. The user is the OS/400 user profile that you will use to access DB2 UDB on the iSeries server. 4. To execute the command press the CTRL and Enter keys at the same time. You will be prompted for a password. The results should look like Figure 5-33. Chapter 5. Base connectivity 135 Figure 5-33 Connecting to the iSeries database through DB2 Command Center 5. Once connected to the database, you can type a SQL Select command to confirm that you can do queries on the database. In the Command section, type the following command: Select * from <library.file> To execute the command, press the CTRL and Enter keys at the same time. See Figure 5-34 for an example. 136 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 5-34 Entering a SQL Select command in DB2 Command Center 6. The results of the query should look like Figure 5-35 under the Query Results tab. Figure 5-35 SQL Select results SQL insert test This tests also confirms that our DB2 UDB client configuration is correct, by inserting a row of data into a file on the iSeries server. See Figure 5-36 for an example. Chapter 5. Base connectivity 137 As in the test above, make sure you are in the DB/2 Command Center. In the Command section, type in a SQL insert command and press the CTRL and Enter keys at the same time to execute. Figure 5-36 Entering a SQL insert command through DB2 Command Center Note: Make sure that tables/files you want to access are journaled or the isolation level of the tables is set to none. If this is not done you will get an error when trying to do an insert or updates to the tables from the Command center. LEI will still work correctly as long as you set the journal parameter in connection document correctly. Running DCTEST Once LEI has been installed, you can confirm that it can connect to the iSeries server by running the DCTEST utility. This will confirm that everything is configured correctly so that LEI can connect to DB2 UDB on the iSeries server. Perform the following steps. 1. Run the program called ndctest.exe. This program is stored in the Domino server program directory (that is, C:\Lotus\Domino) on the PC workstation. 2. From the Command Prompt - ndctest window, enter option 6 (DB/2) from the DCTest menu (Figure 5-37). Press Enter. 138 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 5-37 Testing connectivity through the DCTest utility 3. When prompted, enter the database name as configured in the DB2 UDB Connect client configuration (see Figure 5-21 on page 125). Press Enter. 4. Then enter the OS/400 user profile and password when prompted. See Figure 5-38 for an example of a succesfull test. Figure 5-38 Successful test using the DCTest utility 5.3.4 Errors encountered This section describes some of the errors and their resolutions that we encountered when setting up the DB2 UDB Connect client. These errors are specific to the DB2 UDB Connect client and not to LEI. This is not a conclusive list of all errors that may occur when setting up the DB2 UDB Connect client. To help with debugging other errors refer to the information center that is installed with the DB2 Connect client. Chapter 5. Base connectivity 139 Error Message: SQL7008N REXX variable "<varaible>" contains inconsistent data Resolution: If the <variable> is a file on the iSeries, and the SQLState=55019, then this error is given because the iSeries file being accessed is not journaled. The file needs to be added to the journal on the iSeries server. Note: DB2 SQLState 55019 = The table is in an invalid state for the operation.The SQL7008 indicates that your table on the iSeries is not journaled/logged. You need to start journaling the table on the iSeries or specify NC/*NONE for the isolation level. Error Message: Package error when doing a Select on the tables Resolution: Make sure you have correctly done the bind from DB2 UDB Connect client using the right user name. Error Symptom: Some test fields in the DB2 UDB tables do not show up when queried There is a value in the alphanumeric field, however from DB2 UDB Connect client the column appears blank. LEI inserts will insert unusual characters into the field. Resolution: Check the CCSID of the columns that do not show up. This can be checked in the database script used to create the tables. 5.4 iSeries to pSeries connectivity The final section of this chapter shows you how to connect from an iSeries server to a pSeries server. In this scenario, we have the Domino server hosting LEI running on the iSeries server. The DB2 UDB data resides on a pSeries server. We will cover the steps involved to get the appropriate connectivity setup between the iSeries and pSeries servers to allow the LEI server running on the iSeries to manipulate data in DB2 UDB on the pSeries server. The steps involved include: 1. Determining what port the remote database server is using on the pSeries server. 2. Creating a RDBDIRE entry on the iSeries server using the port found in step 1. 3. Ensure the iSeries server is not using the default CCSID value of 65535. 4. Running the LEI DCTEST connectivity test. 5. Creating a connection document to DB2 UDB on the pSeries server. 5.4.1 Determining pSeries remote database server port The remote database server port used by the pSeries server is 50000 by default. This may not be the port used by the database instance you are using on the pSeries server because each DB2 UDB instance needs to have it’s own unique port. The process of finding the remote database server port used by the pSeries server is detailed below. We will show you how to display the database manager configuration information as a mechanism for finding the port. If you have access to a pSeries server database administrator that can tell you the remote database server port number, you can bypass the steps in this section and go directly to the next section, 5.4.2, “Creating a remote RDBDIRE entry to the pSeries server” on page 145. 1. Telnet into the pSeries server. From a DOS Command Prompt window, enter the following telnet command: telnet 10.5.98.267 140 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server You must use either the TCP/IP address of the pSeries server, or you need to provide a name that is resolvable in your DNS network. An example of using the telnet utility is shown in Figure 5-39. Microsoft Windows 2000 [Version 5.00.2195] (C) Copyright 1985-2000 Microsoft Corp. C:\>telnet 10.5.98.267 Figure 5-39 Telnet to the pSeries server using the TCP/IP address 2. You will be prompted to provide a valid user ID and password to access the pSeries server. 3. Next you need to switch to the user ID for the DB2 UDB instance you need to access. To do this issue the su command specifying the name of the user. The example we show is switching to user db2test. su db2test 4. Now change to the directory associated with the DB2 UDB instance owner’s home directory. In our example, this directory is /home/db2test. cd /home/db2test 5. Issue the source db2cshrc command to set up the DB2 UDB environment variables such as PATH. 6. Optionally you can issue db2 to avoid having to type db2 at the beginning of each command. 7. Issue the DB2 command get dbm cfg to see the database manager configuration information. See Figure 5-40 for an example of using this command. # su db2test % cd /home/db2test % source db2cshrc % db2 (c) Copyright IBM Corporation 1993,2001 Command Line Processor for DB2 SDK 7.2.4 You can prompt. db2 db2 issue database manager commands and SQL statements from the command For example: => connect to sample => bind sample.bnd For general help, type: ?. For command help, type: ? command, where command can be the first few keywords of a database manager command. For example: ? CATALOG DATABASE for help on the CATALOG DATABASE command ? CATALOG for help on all of the CATALOG commands. To exit db2 interactive mode, type QUIT at the command prompt. Outside interactive mode, all commands must be prefixed with 'db2'. To list the current command option settings, type LIST COMMAND OPTIONS. For more detailed help, refer to the Online Reference Manual. db2 => get dbm cfg Figure 5-40 Using the get dbm cfg command to find the remote database server port Chapter 5. Base connectivity 141 8. The result of issuing this command is shown in Figure 5-41. SPM SPM SPM SPM name log size resync agent limit log path TCP/IP Service name APPC Transaction program name IPX/SPX File server name IPX/SPX DB2 server object name IPX/SPX Socket number Discovery mode Discovery communication protocols Discover server instance (SPM_NAME) (SPM_LOG_FILE_SZ) (SPM_MAX_RESYNC) (SPM_LOG_PATH) (SVCENAME) (TPNAME) (FILESERVER) (OBJECTNAME) (IPX_SOCKET) = k6lsys5e = 256 = 20 = = DB2_db2test = = = = 879E (DISCOVER) = SEARCH (DISCOVER_COMM) = TCPIP (DISCOVER_INST) = ENABLE Directory services type Directory path name Directory object name Routing information object name Default client comm. protocols (DIR_TYPE) (DIR_PATH_NAME) (DIR_OBJ_NAME) (ROUTE_OBJ_NAME) (DFT_CLIENT_COMM) = NONE = /.:/subsys/database/ = = = Maximum query degree of parallelism Enable intra-partition parallelism (MAX_QUERYDEGREE) = ANY (INTRA_PARALLEL) = NO Figure 5-41 Result of issuing the get dbm cfg command 9. Find the line ‘TCP/IP Service name’. Note the value for this entry. In our example, the value we need to remember is DB2_db2test. 10.Now that we know which service name to look for, we can browse the services file in the /etc directory. To do this, we first need to exit the DB2 UDB environment, do this by typing quit at the DB2 prompt. See Figure 5-42 for an example. 11.Now issue the AIX® command pg /etc/services in the telnet window as shown in Figure 5-42. 142 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Discover server instance (DISCOVER_INST) = ENABLE Directory services type Directory path name Directory object name Routing information object name Default client comm. protocols (DIR_TYPE) (DIR_PATH_NAME) (DIR_OBJ_NAME) (ROUTE_OBJ_NAME) (DFT_CLIENT_COMM) Maximum query degree of parallelism Enable intra-partition parallelism (MAX_QUERYDEGREE) = ANY (INTRA_PARALLEL) = NO No. of Number Number Number int. communication buffers(4KB)(FCM_NUM_BUFFERS) of FCM request blocks (FCM_NUM_RQB) of FCM connection entries (FCM_NUM_CONNECT) of FCM message anchors (FCM_NUM_ANCHORS) = NONE = /.:/subsys/database/ = = = = = = = 4096 2048 (FCM_NUM_RQB * 0.75) (FCM_NUM_RQB * 0.75) Node connection elapse time (sec) (CONN_ELAPSE) = 10 Max number of node connection retries (MAX_CONNRETRIES) = 5 Max time difference between nodes (min) (MAX_TIME_DIFF) = 60 db2start/db2stop timeout (min) (START_STOP_TIME) = 10 db2 => quit DB20000I The QUIT command completed successfully. % pg /etc/services Figure 5-42 Issuing the pg /etc/services command 12.If you use the pg command to browse this file, you will need to enter a number like ‘999’ to scroll to the end of the file. See Figure 5-43 for details. # @(#)27 1.27 src/bos/etc/services/services, cmdnet, bos510 2/22/01 10: 6:27 # # COMPONENT_NAME: (CMDNET) Network commands. # # FUNCTIONS: # # ORIGINS: 26 27 # # (C) COPYRIGHT International Business Machines Corp. 1988, 1989 # All Rights Reserved # Licensed Materials - Property of IBM # # US Government Users Restricted Rights - Use, duplication or # disclosure restricted by GSA ADP Schedule Contract with IBM Corp. # # # Network services, Internet style # tcpmux 1/tcp # TCP Port Service Multiplexer tcpmux 1/udp # TCP Port Service Multiplexer compressnet 2/tcp # Management Utility compressnet 2/udp # Management Utility compressnet 3/tcp # Compression Process :999 Figure 5-43 Entering a number such as 999 to reach the end of the file Chapter 5. Base connectivity 143 13.At the bottom of the listing, you should see the port number listed for DB2_db2test. The port number in this example is 50011 as shown in Figure 5-44. afs3-bos 7007/tcp # Basic Overseer Process afs3-bos 7007/udp # Basic Overseer Process afs3-update 7008/tcp # Server-To-Server Updater afs3-update 7008/udp # Server-To-Server Updater afs3-rmtsys 7009/tcp # Remote Cache Manager Service afs3-rmtsys 7009/udp # Remote Cache Manager Service graPHIGS 8000/tcp # graPHIGS Remote Nucleus x_st_mgrd 9000/tcp # IBM X Terminal man 9535/tcp man 9535/udp isode-dua 17007/tcp isode-dua 17007/udp sco_printer 70000/tcp sco_spooler # For System V print IPC sco_s5_port 70001/tcp lpNet_s5_port # For future use #dtspc 6112/tcp ipsec_sk_master 1011/udp ipsec_sk_engine_s 4001/udp #isakmp 500/udp #tmd_isakmpd 54687/tcp #tmd_app 54688/tcp #wsmserver 9090/tcp # DB2 V7 entries DB2_db2test 50011/tcp # DB2 Primary instance DB2_db2testi 50012/tcp # DB2 Back level instance (EOF): Figure 5-44 Locating the port number associated with the DB2 instance 14.With the DB2 instance port number located, we can exit the telnet session.You need to press Enter first to return to a prompt. 15.Now type quit to end the telnet session as shown in Figure 5-45. 144 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server afs3-bos 7007/udp # Basic Overseer Process afs3-update 7008/tcp # Server-To-Server Updater afs3-update 7008/udp # Server-To-Server Updater afs3-rmtsys 7009/tcp # Remote Cache Manager Service afs3-rmtsys 7009/udp # Remote Cache Manager Service graPHIGS 8000/tcp # graPHIGS Remote Nucleus x_st_mgrd 9000/tcp # IBM X Terminal man 9535/tcp man 9535/udp isode-dua 17007/tcp isode-dua 17007/udp sco_printer 70000/tcp sco_spooler # For System V print IPC sco_s5_port 70001/tcp lpNet_s5_port # For future use #dtspc 6112/tcp ipsec_sk_master 1011/udp ipsec_sk_engine_s 4001/udp #isakmp 500/udp #tmd_isakmpd 54687/tcp #tmd_app 54688/tcp #wsmserver 9090/tcp # DB2 V7 entries DB2_db2test 50011/tcp # DB2 Primary instance DB2_db2testi 50012/tcp # DB2 Back level instance % exit Figure 5-45 Exiting the telnet session to the pSeries server We are now ready to continue with the next step. 5.4.2 Creating a remote RDBDIRE entry to the pSeries server You now need to create a relational database directory entry on the iSeries to identify the location of the remote pSeries database. To do this, go to an OS/400 command line prompt and perform the following steps: 1. Issue the ADDRDBDIRE command and either press the F4 key to prompt or press Enter. Either option will take you to the Add RDB Directory Entry (ADDRDBDIRE) screen. 2. On the Add RDB Directory Entry screen, press the F9 key to show all parameters. The result is displayed in Figure 5-46. 3. The following parameters must be enter: – Relational database For the Relational database parameter, provide the local RDBDIRE for the remote system. In this example, the database we are connecting into on the pSeries server is DEMODB. Note: DEMODB is the name of the DB2 UDB database that has been created on the pSeries that we want to connect into. You may want to refer to 1.6, “Terminology” on page 15 for details about differences in terminology between iSeries and other platforms related to the database name. – Name or address Enter the IP address of the remote system or provide the name of the system as it is known in the DNS network. Chapter 5. Base connectivity 145 – Type The type is either SNA or IP. We show you IP here as that is the most common protocol used in the industry today. – Text Use the text field to provide a description of the RDBDIRE you are creating. – Port number or service program This parameter will default to *DRDA. We need to replace this value with the port number we located in 5.4.1, “Determining pSeries remote database server port” on page 140. Press Enter to create a remote RDBDIRE entry to the pSeries server. Add RDB Directory Entry (ADDRDBDIRE) Type choices, press Enter. Relational database . . . . . . > DEMODB Remote location: Name or address . . . . . . . > '10.5.98.267' Type . . . . . . . . . . . . . > *IP *SNA, *IP Text . . . . . . . . . . . . . . > 'RDBDIRE entry to remote pSeries database' Port number or service program Remote authentication method: Preferred method . . . . . . Allow lower authentication . Device: APPC device description . . Local location . . . . . . . . F3=Exit F4=Prompt F24=More keys 50011 . . *ENCRYPTED *ALWLOWER *USRID, *USRIDPWD... *ALWLOWER, *NOALWLOWER . . *LOC *LOC Name, *LOC Name, *LOC, *NETATR F5=Refresh F12=Cancel More... F13=How to use this display Figure 5-46 Use the ADDRDBDIRE command to add an entry for the remote pSeries database 4. The iSeries system (AR) will now have a RDBDIRE entry for accessing the remote database on the pSeries system (AS). 5.4.3 Ensure the iSeries server is not using the default CCSID The default coded character set identifier (CCSID) for an iSeries server is 65535. This default value means that no character conversion is done. If you have not changed your iSeries server to use a CCSID other than 65535, you will have problems connecting into the pSeries server. The reason this is so important is because when running applications, data is not converted when it is sent to another system; it is sent as tagged along with its CCSID. The receiving job automatically converts the data to its own CCSID if it is different from the way the data is tagged. In our case, the receiving job is the pSeries database server. Perform the following steps to view the current value for the CCSID of your iSeries server, and if necessary, how to change it to a different value. 146 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 1. Issue OS/ 400 CL command WRKSYSVAL QCCSID on an OS/400 command line. You will see the screen shown in Figure 5-47. Work with System Values System: AS06 Starting characters of system value F4 for list Position to . . . . . . Subset by Type . . . . . Type options, press Enter. 2=Change 5=Display Option System Value QCCSID Type Description *SYSCTL Coded character set identifier Bottom Command ===> F3=Exit F4=Prompt F12=Cancel F5=Refresh F9=Retrieve F11=Display names only Figure 5-47 Work with QCCSID system value screen 2. Select option 5 (Display) on this screen and press Enter. You now see the display shown in Figure 5-48. If the value of the CCSID is 65535, you will need to change this value to match the CCSID for the primary language on your system. As an example, the CCSID for a US English language installed system is 37 and a system in Denmark will use a CCSID of 277. For more information about CCSID values, see the iSeries Information Center at: http://www.ibm.com/eserver/iseries/infocenter Display System Value System value . . . . . : Description . . . . . : QCCSID Coded character set identifier Coded character set identifier . . . . . : 65535 1-65535 Press Enter to continue. F3=Exit F12=Cancel Figure 5-48 Display the current setting of the QCCSID system value 3. If the value is set to 65535, you will need to select option 2 (Change) on the Work With System Values screen shown in Figure 5-47. 4. Enter the correct CCSID value for your system and press Enter. 5. The change to the system value takes affect immediately. Any new jobs that are started now will start with the new CCSID. Chapter 5. Base connectivity 147 Note: For this change to take affect for your Domino server, you must stop and restart the server. 5.4.4 Perform the DCTEST connectivity test You are now ready to test connectivity to the remote system. This can be done using the LEI DCTEST utility. The DCTEST utility ensures that proper connectivity has been configured to access a specific data source. The DCTEST utility is a program that resides in the QNOTES library on the iSeries server. Note: If you are familiar with the Windows environment, the comparable test on that platform is ndctest.exe. 1. To invoke the DCTEST utility use the following OS/400 CL command: call qnotes/dctest Calling this program will invoke the screen shown in Figure 5-49. Lotus Connector Server Connection Verification Test Copyright 2001 Lotus Development Corporation -------------------------------------------This utility will verify connectivity from this machine to the selected type of server. At the prompt, enter the number of the test you would like to run, or enter 0 to exit. 0 - Exit this program 1 - Lotus Notes 6 - DB/2 Run test number: [0] ===> F3=Exit F4=End of File F6=Print F9=Retrieve F17=Top F18=Bottom F19=Left F20=Right F21=User Window Figure 5-49 The DCTEST utility 2. On this screen, enter an option 6 (DB/2) and press Enter to test connectivity to the remote AS server. 3. You will now see the screen shown in Figure 5-50. You are prompted to provide the RDBDIRE of the remote server you want to test connectivity to. In our example, this is DEMODB. 4. Press Enter to advance to the next required parameter which is the username. Provide the database owner for this parameter. 5. Press Enter to continue. The final prompt asks for the password associated with the database owner you specified. In our example, this is db2test. Press Enter. 6. After providing the password for the database owner, press Enter to continue. 148 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Note: The input for these three parameters is NOT case sensitive. DB2 Connection Verification Copyright 2000 Lotus Development Corporation -------------------------------------------This utility will verify connectivity from this machine to the specified DB2 server. At the prompts, enter a valid DB2 database, username, and password loaded library QSYS/QSQCLI Database (must be registered in RDB Directory, see WRKRDBDIRE): > demodb Username: > db2test Password (may be case sensitive for remote database): ===> F3=Exit F4=End of File F6=Print F9=Retrieve F17=Top F18=Bottom F19=Left F20=Right F21=User Window Figure 5-50 Connecting to the remote AS on the pSeries server 7. After completing the information for the three prompts, you will see the messages as shown in Figure 5-51 indicating that you were able to successfully connect to the remote pSeries AS server. At the prompts, enter a valid DB2 database, username, and password loaded library QSYS/QSQCLI Database (must be registered in RDB Directory, see WRKRDBDIRE): > demodb Username: > db2test Password (may be case sensitive for remote database): > red2book Attempting to connect to DB2 DEMODB as DB2TEST Successfully Connected Error connecting to DB2 data source. SQL statement cannot be run. Connectivity test Fails. Try Again?: [N] ===> F3=Exit F4=End of File F6=Print F9=Retrieve F17=Top F18=Bottom F19=Left F20=Right F21=User Window Figure 5-51 Confirmation that the connectivity test to the remote AS system was successful Chapter 5. Base connectivity 149 Note: In our testing we were unable to cleanly connect to the pSeries as shown in Figure 5-51. Development was looking into the problem at the time of writing this redbook. See 5.4.5, “Creating a connection document to DB2 UDB on the pSeries server” on page 151 for a tip on how to successfully create a connection document to a database on the pSeries server. 8. To exit the DCTEST utility, press Enter at the Try Again?: [N] prompt. You will see the screen shown in Figure 5-52. > itso1 Attempting to connect to DB2 AS08 as KGREENE Successfully Connected Successfully Disconnected Connectivity to DB2 Verified. Try Again?: [N] > At the prompt, enter the number of the test you would like to run, or enter 0 to exit. 0 - Exit this program 1 - Lotus Notes 6 - DB/2 Run test number: [0] ===> F3=Exit F4=End of File F6=Print F9=Retrieve F17=Top F18=Bottom F19=Left F20=Right F21=User Window Figure 5-52 To exit the DCTEST utility select option 0 - Exit this program 9. Enter an option 0 (Exit this program) and press Enter to exit the DCTEST utility. You will need to press Enter again to exit the terminal session. 10.You have now confirmed connectivity to the remote AS server and are ready to proceed with creating LEI connection and activity documents. For details, see chapters Chapter 6, “Connection documents” on page 153, Chapter 8, “Advanced RealTime activities” on page 195, and Chapter 9, “Batch activities” on page 255. 11.If you receive the error shown in Figure 5-53, you have most likely provided an incorrect port number for the PORT parameter of the ADDRDBDIRE command. See 5.4.1, “Determining pSeries remote database server port” on page 140 to determine the correct port number to use. 150 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server specified DB2 server. At the prompts, enter a valid DB2 database, username, and password loaded library QSYS/QSQCLI Database (must be registered in RDB Directory, see WRKRDBDIRE): > demodb Username: > db2test Password (may be case sensitive for remote database): > red2book Attempting to connect to DB2 DEMODB as DB2TEST Error connecting to DB2 data source. Communication error occurred during distributed database processing. Connectivity test Fails. Try Again?: [N] ===> F3=Exit F4=End of File F6=Print F9=Retrieve F17=Top F18=Bottom F19=Left F20=Right F21=User Window Figure 5-53 Problem connecting to remote server because wrong port was specified 5.4.5 Creating a connection document to DB2 UDB on the pSeries server Even though the DCTEST fails without a clean connect, you can successfully create a connection document to the database on the pSeries server and perform data manipulations. There is a trick to getting this to work that we will show you. Perform the following steps: 1. When you create the DB2 connection document, you will receive the following error when you browse to fill in the Owner field. The error is shown in Figure 5-54. Chapter 5. Base connectivity 151 Figure 5-54 SQL error when browsing Owner 2. The way you can get around this error is to click the Manual button and provide the owner and name of the table you wish to connect to. An example is shown in Figure 5-55. Figure 5-55 Manually provide the database and table name 3. The columns in the table will now be populated in the DB2 connection document. 4. You will be able to successfully use this DB2 connection document to perform manipulations through LEI against the database files residing on the pSeries server. 152 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 6 Chapter 6. Connection documents Connection documents define the data sources that are involved in the functionality defined in the activity documents. Depending on the activity, some LEI activities, such as replication, require both a source and destination connection document. Others, such as virtual fields, require only one. The information provided in a connection document includes the type of data source being connected to, appropriate user authentication information for connecting to that data source, the data source name, and connector specific information, such as whether the data source is being journaled or not in the case of DB2 UDB. There are a core set of connectors that ship with the Domino server code that allow for the source and destination data sources to correspond. Connectors provide the strategic ‘plumbing’ for enterprise integration. They deliver native connectivity, via a consistent object model, to external data sources. Connectors allow Domino applications to connect, authenticate, and translate data that resides within relational databases, enterprise resource planning, and transaction processing systems. Not all connection documents that are available in the LEI Administrator database are supported by LEI 6.0.1 on the iSeries server. When creating a connection document you may see all of connections that are available for LEI, however only the following five base connection documents are currently supported on iSeries server: DB2 Notes File system Text Metaconnectors – Collapse/Expand – Meter – Order – Trace Note: Future releases of LEI on the iSeries server will support additional base connectors. © Copyright IBM Corp. 2003. All rights reserved. 153 6.1 DB2 connection document To create a connection to DB2 UDB on either a local iSeries or remote iSeries database, you need to create a DB2 connection document. Before creating the connection document you should confirm that all the base connectivity to the iSeries server is configured correctly by running the DCTEST utility as discussed in 5.2.4, “Test connectivity using the DCTEST utility” on page 117. To create a DB2 connection document, open the LEI Administrator database (decsadm.nsf) on the LEI server. Click the Add Connection button and click DB2. See Figure 6-1. Figure 6-1 Creating a DB2 connection document In the DB2 connection document there are three sections that can be filled in. These are: Connectivity - which includes the connection parameters for the database as well as transaction options, table creation options, logging options, and map nulls options. Table selection - This is where you define the exact library/owner, table, and columns the connection will access. This table selection can be a DB2 table, a logical view or a stored procedure. Other - This section allows you to categorize your connection documents in the LEI Administrator database, as well as add descriptive comments about the connection. These sections and the fields in the sections are described in detail below. 6.1.1 Connectivity section The Connectivity section of the DB2 connection document allows you to enter all data required to connect to a DB2 database. See Figure 6-2 for an example. The fields in this section include: Name: This is any name you want to give to your connection document. Database: This is the name of the database that you want to connect to. For iSeries this is the RDB directory entry name. See 5.2.2, “Creating a local relational database directory entry” on page 105 for details. User Name: The user name must be a valid OS/400 user profile. This user should have access to the DB2 UDB files you want to access. Password: This field is the associated password for the OS/400 user profile that will be connecting to the database. The password will appear in clear text in the connection document but can be encrypted. In order to encrypt the password field, click the key icon, 154 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server and choose the secret encryption key. For more information about creating secret encryption keys, see ‘Creating secret encryption keys’ in the Domino Designer help. Data Journaling: This radio button allows you to select if the DB2 UDB files that will be accessed by this connection document are journaled or not. You should check with the database administrator to see if the files are journaled and set this parameter accordingly. Note: The Data Journaling radio button does not turn journaling on or off on the DB2 UDB tables. The selection in the connection document should represent if journaling is on or off on the tables that you will access. Figure 6-2 DB2 connection document, Connectivity section Under the Transaction Options tab (Figure 6-3) there are two settings that define how database updates and inserts are handled. The two fields are: RollBack: The RollBack upon error check box tells LEI that if any error occurs when inserting or updating data in DB2 UDB, the state of the database should be put back to what it was after the last commit was done. For example if you are inserting 20 rows into a table and you do a database commit after every 5 inserts, and on the 7th insert you encounter an error. The database after disconnection will be put back to the state it was in after the 5th insert and the commit. Commit: This field allows you to configure when commits to the database will be done. There are three options: – Commit at Disconnect: This option is to commit only after you disconnect. This means that every row of data would be inserted or updated and only after all rows are complete then a commit is done. The danger in using this setting is that if an error is encountered then the database would be rolled back to before the activity was started and good data would not have been added to the database. You would have to fix the error and re-start the activity from the beginning. For large data transfers this setting may become problematic. Chapter 6. Connection documents 155 – Commit Every N Operations: This option allows you specify the number of transactions after which you want to commit. The setting of this field would be dependant on how many rows of data are projected to be inserted or updated. – Commit Every Operation: This option is to commit after every operation. This would commit changes to the database after every insert or update. Using this setting may have a negative impact on performance if a large number of records are being put into the database (that is, a direct transfer activity). Figure 6-3 DB2 connection document, Transactions Options tab The Table Creation Options tab (Figure 6-4) is used if you want LEI to automatically create a target table in DB2 UDB for you. For example if you want to transfer a set of data from a Notes application to a new DB2 UDB table you can allow LEI to create the target table for you. The fields names and data types in the new DB2 UDB table will be based on the field names and types of the Notes fields. There is one option in the Table Creation Options tab: Size Cutoff for Create NOT LOGGED COMPACT: This setting allows you to enter a size cutoff for large object data types (LOB), where if a column exceeds this size it will be created with the NOT LOGGED COMPACT option. Note: When LEI creates tables it will use the most generic data mapping. These mappings may not be the most efficient. For example, LEI will map all Notes text fields to CLOB in DB2 UDB. All number fields in Notes will be mapped to floats in DB2 UDB and all binary fields will be mapped to BLOBS. Creating the DB2 tables manually may be more efficient. Figure 6-4 DB2 connection document, Table Creation Options tab The Logging Options tab (Figure 6-5) allows you to specify whether you want the SQL statements that LEI is passing to DB2 UDB to be put into the LEI log. This setting is very useful when trying to debug errors. Figure 6-5 DB2 connection document, Logging Options tab The Map Nulls Option tab (Figure 6-6) facilitates iSeries DB2 UDB access and allows for fields which resolve to a null value to be mapped to a default value. This is particularly useful on the iSeries server since columns by default are not null enabled. 156 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 6-6 DB2 connection document, Map Nulls Option tab 6.1.2 Table selection section The Table Selection section (Figure 6-7) allows you to enter the library and file that you want to access. There are two fields: Owner: This is the name of the library that you want to access. Name: This is the table/file name that you want to access. The Column(s) field is automatically filled. Figure 6-7 DB2 connection document, Table Selection section 6.1.3 Other section The Other section (Figure 6-8) allows you to enter a category that you would like the DB2 connection document to display under as well as a comment field that allows you to describe the purpose of the DB2 connection document. This section is designed to help make LEI administration simpler. The fields in this section include: Category(s): Category where you want the DB2 connection document to appear in the LEI Administrator By Category view. Comments: Comments describing the purpose and relevant details about the DB2 connection document. Figure 6-8 DB2 connection document, Other section 6.2 Notes connection document There are certain activities where it's convenient to treat Notes as if it were a relational database. Activities that move data around between different types of databases, can work with any pair of databases, for example, a Replication activity, might be set up to replicate updates between an Oracle table and a Sybase table. Neither end of the connection needs to be Notes. You can ‘plug in’ a Notes connection document into any of these activities and have it work basically the same as a relational connection document. This avoids the necessity of having several different flavors of the same basic activity type: Chapter 6. Connection documents 157 Replication from Notes to relational database Replication from relational database to Notes Replication from Notes to file and so on. Replication is replication, from a connector of one type to a connector of any other type. To create a connection to a Notes database on either the Domino server that hosts LEI or a Notes database on another Domino server, you need to create a Notes connection document. Before creating the connection document you should confirm that all the base connectivity to the local or remote Domino server is setup by running the DCTEST program as shown in 5.2.4, “Test connectivity using the DCTEST utility” on page 117. To create a Notes connection document, open the LEI Administrator Database (decsadm.nsf) on the LEI server. Click the Add Connection button and click Notes. See Figure 6-9. Figure 6-9 Creating a Notes connection document In the Notes connection document there are two sections that can be filled in. These are: Connectivity: This section includes the connection parameters for the Domino server and database as well as General options, Document Selection, Field Selection, Data Transformation, and Data Creation. Other: This section allows you to categorize your connection documents in the LEI Administrator database, as well as add descriptive comments about the connection. These sections and the fields in the sections are described in detail below. 6.2.1 Connectivity section The Connectivity section (Figure 6-10) of the Notes connection document allows you to enter all data require to connect to a Notes database. The fields in this section include: Name: This is any name you want to give to your connection document. Domino Server: This is the Domino server that is either running LEI or any other Domino server that is accessible by the Domino server that hosts LEI. Notes Database: This field allows you to enter the Notes database you want to connect to. Once the Domino server name is entered you can use the pull-down arrow to see all Notes databases on that Domino server. 158 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server You may notice that for a Notes connection document, no userid and password are supplied. That's because the LEI Administrator process already has a userid that it's ‘signed in’ with when LEI started up. This is specified in the Domino server’s Notes.ini file (KeyFileName or ServerKeyFileName parameter). It uses this ID for all access to Notes data. Note: Make sure the user ID you use to log into Notes and access the LEI Administrator has at least reader access to the Notes database you want to connect to, otherwise you may not be able to access other contents of the database such as available forms. Figure 6-10 Notes connection document, Connectivity section When you select the General Options tab, the following options appear as shown in Figure 6-11. These options can apply to the source or destination database, depending on whether the connection is used by the LEI activity as the source or target connection. Binding Options: – Do Not Enforce Form Design: Specifies that the LEI activity not execute any Notes form and field-related formulas. Computed fields, such as the current date, are not computed. – Enforce Field Flags Only: Specifies that the LEI activity set all field flags as defined in the form but not execute any formulas. As a result, special types, such as reader and author fields, are assigned in new documents as indicated in the form. This option avoids the overhead of computing field formulas. – Enforce Form Design: Calculates all field-related formulas (default value, input translation, and computed field) as part of the LEI activity. This option may cause slower data transfer as a result of formula calculations. This option does not execute @function names that begin with Db. It does enable field flags. – Enforce Form Design and Perform Validation: Calculates all Notes field-related formulas (default value, input translation, and computed field) and invokes all Notes field validation formulas which ensure that the data is within the parameters for the field in the Notes form. Any field validation errors are recorded in the LEI activity log. Server Port: Specifies the name of the port to use when dialing a server remotely. Chapter 6. Connection documents 159 File Path for File Attachments: Specifies the directory where file attachments are stored if the option ‘Extract File Attachments’ is selected. If no path is specified here, file attachments are copied to the current directory. Use Computed Subforms: Allows you to include all computed subforms by name (all non-computed subforms are included by default). The fields in the computed subforms listed here will be accessible in the field mapping dialog box from a LEI activity using this connection document. You may specify any subform here, even if it doesn't actually appear on the form. This is useful if you have extra fields stored in the document which do not appear on the form. Define a subform that includes those fields and put its name here. However, the 'Enforce Form Design' options will not affect subform fields unless the subform actually is included on the form. Note: This field is disabled if anything other than Do Not Enforce Form Design is selected in the Binding Options field discussed above. Figure 6-11 Notes connection document, General Options tab The Document Selection section (Figure 6-12) is used to configure the document level options used by the LEI activity. These are used to limit the documents that the activity selects from the source. Several options can be combined, but the filtering is cumulative. A document must satisfy all options to be selected. These options can apply to the source or destination database, depending on whether the connection is used by the LEI activity as the source or target connection, and applied to the creation of a result set. Form To Use: Enables you to select a form from the database specified in the Notes Database field in the Connectivity section. Fields To Use From Form: Once you select a form, the fields contained on that form are displayed. Check the field names that you wish to use. Note: Any field selection here is ignored when this connection is used in a Replication activity. To tailor field selection for replication, explicitly map the fields in the Mapping section of the Replication activity document. Document Options: – Include View Responses: Includes response documents of any parent document that is used in a view. This option cannot be used along with the Copy Response Hierarchies (Notes to Notes only) option. When used in a Notes to Notes transfer, the result in the destination database is not hierarchical and all documents are copied at the same level. – Copy Response Hierarchies (Notes to Notes only): This option ensures that response documents retain their hierarchical relations to the parent document. This option 160 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server cannot be used with the Include View Responses option. To use this option from an LEI activity with manual field mapping, add a field LCXHIER to both field lists (this is not necessary for automatic field mapping by name or position). – Include Documents of Other Forms: By default, the documents in a result set are restricted to those associated with the source form identified as the metadata in the activity document. Use this option to include documents of all forms in the result set, filtering them through the source form. Note: If the Fetch View Column Data option is used for selection, this option is required and will be automatically selected. – Case-Insensitive View Searches: Makes view searches case-insensitive (they are case-sensitive by default). An example of where to use this is in timestamp replication with the case-insensitive string comparison option, where case-insensitive searches are needed in Notes. Full Text Search Query to Execute: The full text query that you enter here is executed against the current result set and only the resulting documents (those that are contained the searched text) are used by the activity. The query is executed on the result set produced by either the command statement in the activity or the View to Use for Selection entry, plus any defined agent to execute. The Notes database selected in the connectivity section must be full-text indexed and a view must be selected in View to Use for Selection option (located under the Field Selection tab) to support this option. This option only affects document selection through an explicit Notes formula, such as a direct transfer activity or the LC LSX Connection.Execute method. It does not affect generic selection such as those done by replication activities. Figure 6-12 Notes connection document, Document Selection tab The Field Selection tab (Figure 6-13) is used to limit the document fields (or view columns) used by the LEI activity to create the result set. View to Use For Selection: If the name of a Notes view is entered, the documents appearing in that view will be selected by the activity. This option replaces and ignores any command statement specified in the activity. By default, only top-level documents are included, although other options allow the view contents to be altered. Documents not in the view are ignored. Chapter 6. Connection documents 161 When used with ordering or timestamps in replication activities, this field indicates the name of the view to use for these operations. When performing primary key replication, supplying a view name can improve performance by not requiring the database to be re-indexed with every activity run. When no view is specified, a temporary view is still created and an event is logged suggesting use of a permanent view name. When the view is the wrong format or doesn't exist, checking the Allow View Creation/Overwrite option (see below) allows the activity to create or overwrite that view in its own format. This option overwrites the view when modifying an existing view. Allow View Creation/Overwrite: Checking this option allows the activity to modify or create the view if it doesn't already exist or does not have the proper formatting. This option is required for timestamp replication when a view is specified. If the Case-Insensitive View Searches option (located under the Document Selection tab) is selected, then the view columns will be set to sort case-insensitive. Note: When you use a permanent view to support keyed searches, such as those used by replication activities, and an existing view needs to be altered (as is always true for timestamp replication), that view will be deleted and a new view will be created. Agent to Execute: This field enables you to choose an agent name from a resultant list. The agent specified will further refine the documents selected. The agent is executed on the result set produced by the command (or selection) statement in either a direct transfer or command activity. Note: This option is only valid if the Notes connection document will be used in a direct transfer or command activity. Special Fields Option: Unlike relational systems, Notes documents contain a header with additional information about the document that isn't stored in any of the document's fields. Since you may want to transfer information from this header to other databases, this section lets you select additional information from the header that will be included along with the document fields when you read or write using this connection. – Load Document Universal ID (UNID): Appends a virtual field named UNID to the result set. This field will fetch the Universal Note ID for each document. – Load Document Note ID (NOTEID): Appends a virtual field named NOTEID to the result set. This field will fetch the Note ID for each document. – Load Parent Universal ID (REF): Appends a virtual field named REF to the result set. This field will fetch each document's parent Universal Note ID, which is used by Notes to maintain response hierarchies. – Load Last Modified Timestamp (@MODIFIED): Appends a field called @Modified to the result set, which contains the Notes implicit document timestamp. Select this option on the relevant Notes connection and specify it as a timestamp in the replication activity to use Notes implicit timestamps in replication. This prevents having to use additional Notes timestamp fields. – Extract File Attachments (FILE): Appends a virtual field named File to the result set. File contains file names of all attachments in a document and extracts files to disk. The directory for file extraction is the current directory or the one specified in the File Path for File Attachments field (located under the General Options tab). While this option copies file attachments on a Notes to Notes transfer, the Copy File Attachments (Notes 162 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server to Notes only) option (see below) is more efficient for this purpose because it does not write to files. Fetch Selections: Specifies how fetching is to be performed. Choose one of the following options. – Fetch Document Items: Gets the field names from the form designated as source metadata. – Fetch View Column Data: Gets data from the view designated at View to Use for Selection option. The fields are automatically named column1, column2, and so on. Selecting this option automatically checks the Include Documents of Other Forms option (located under the Document Selection tab). Note: If you select this item, do not also select any fields in the Document Selection tab. If you do, your activity will fail with the error, Conflicting values for properties 'FieldNames' and 'FetchViewData'. Development has been apprised of the issue and is working on it. Other Options: – Translate Multivalue Types to Text: Transfers the contents of multivalue types of Text List, Number List, and Datetime List as text. This is useful when the destination database cannot accept a multivalue’s default binary type. – Copy File Attachments (Notes to Notes only): Copies any file attachments associated with transferred documents; regardless of whether the fields are mapped or not. If this option is not selected, transferred file attachments will appear as icons only in the target. To use this option from an activity with manual field mapping, add a field called LCXFILE to both field lists (this is not necessary for automatic field mapping by name or position). – Copy Special Composite Fields (Notes to Notes only): Copies any composite support fields associated with transferred documents. This includes the fields, links, and fonts to return full fidelity of composed data. To use this option from an activity with manual field mapping, add a field called LCXCOMP to both field lists (this is not necessary for automatic field mapping by name or position). – Maximum Length for Text Data: Signals LEI to use this length as the maximum for text type fields. This option is often used when a metadata is being created in a relational database and text lengths and types are important. The default text length is slightly under 64KB. If the Truncate Data When Necessary option is set in the LEI activity document, LEI truncates the text field to the maximum length indicated here before transfer. If the Truncate Data When Necessary option is not checked, any record with one or more fields greater than this limit is not transferred and LEI logs a Data overflow error. Also, there are some additional points to consider with this option: • The Trim option in an activity document controls whether too long data is truncated or generates an error. • This limit does not apply to Notes rich text fields if they are stored to binary columns in a relational database. There, the limit is the size limit of the BLOB column, if any. • Regardless of where this limit is set, Notes cannot store more than 32KB of non-rich text information per document. Chapter 6. Connection documents 163 Figure 6-13 Notes connection document, Field Selection tab When you select the Data Transformation tab, the options seen in Figure 6-14 appear. The Data Transformation tab provides options for executing formulas to transform data. These three formulas do not permanently change the data in a Notes document, but rather provide a way of adding or temporarily changing fields for the purposes of having extra values to output to the relational database. Formula to Execute During Select: Enter the Notes formula that will execute just after the data is fetched. The data is altered as part of the fetch/select operation. This applies when the Notes connector is used to connect to the source database. Formula to Execute Prior to Insert: Enter the Notes formula that will execute just before the selected data is inserted into the target. The data is changed as part of the insert operation. This applies when the Notes connector is used to connect to the target database. Formula to Execute Prior to Update: Enter the Notes formula that will execute before the data in the designated target is updated. The transformation will take place as part of the update operation. This applies when the Notes connector is used to connect to the target database. Note: If you do not want to apply the transformation to all the documents, you can use the SELECT statement to choose which ones to change. For example, to assign a field value, enter the following formula: select @all; FIELD NewField := "New Value"; Figure 6-14 Notes connection document, Data Transformation tab When you select the Data Creation tab, the options as seen in Figure 6-15 appear. The Data Creation tab provides options for managing data creation with the Notes database during processing of any activities associated with the Notes connection document. 164 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Notification Options: – Send New Documents as Mail: Sends inserted documents as mail rather than saving to a Notes database. The transferred records must contain a field named SendTo containing a valid address. For sources that support SQL, this field can be selected as part of the SQL SELECT clause in the statement of the activity document. For example: select column1, column2 from table where SendTo="[email protected]" – Embed Form in Mailed Documents: Embeds the form in documents sent as a result of using the Send New Documents as Mail option. Use this option when the recipients of the mail will not have the relevant form in their mail database. – Commit Changes Immediately: This option commits each change to the Notes database immediately. The default behavior is to commit all changes at database close. This option can slow down performance. – Refresh Views as Database is Closed: Reflects the database changes in the databases views at the end of the transfer or replication process when the destination database is being closed. This option causes view refresh to occur as part of the transfer rather than to occur when the user next opens the view. If you do not enable this option, the Notes views will still be up to date when they are next used. This just saves the next user to open a view, from having to wait while the Notes server updates the view index. – Purge Deletion Stubs as Database is Closed: Use this option to clear all deletion stubs from the Notes database when disconnecting. Do not enable this option for Notes database that are replicated to other Domino servers or to users’ workstations. If the deletion stubs are removed, deletions will not go out to other replicas, and deleted documents will reappear if they are edited elsewhere. Note: It is strongly recommended that this option only be used with the Refresh Views as Database is Closed option, since once the stubs are deleted, they will not be properly removed from the views. Selecting the Refresh Views as Database is Closed option will remove them before purging. This option cannot be used on a Notes database with the Notes replication setting to Delete documents not modified in the last N days. Doing so will skip the purging and generate an error indicating the conflict. To use this option successfully, the Notes ID specified must have sufficient access to the database to enable modification of Notes replication settings. Encryption: Specifies how encryption should occur. – Encrypt Enabled Fields: Encrypts all enabled fields in the form of the target document. – Private Encryption Key(s): To use private encryption keys (the default is to use the public key), provide one or more private encryption key names, separated by commas or semicolons in this field. These keys must be available on the LEI server. Deletion: Delete Database upon Connection deletes the database specified in the activity upon connection. This is used together with Creation option below to delete and then recreate the database prior to population. Do not use this option for a database that has replicas on other Domino servers (including other servers in a Domino cluster) or on user's workstations. The new Notes database will not have the same replica ID as the previous one; therefore, the changes will not replicate. This will also invalidate Web browser users' URL links and ‘favorites’ to documents and Chapter 6. Connection documents 165 views in your database, and Notes client users' doclinks, view links, and database links. Bookmarks will still locate the database. Creation: Create Database (if it doesn't exist), creates a destination Notes database to receive the data if a database does not exist. For database creation, you can optionally enter a template server and template file path. This option should not be selected when the target Domino server is part of a Domino cluster because the database may be created in an inconsistent state. When the target is a Domino cluster, create the database using a Notes client prior to running the LEI activity. Database Template Server: The Domino server containing the template file to be used to create the destination database. Database Template File Name: The file path of the Notes .ntf template file to be used to create the destination database. Figure 6-15 Notes connection document, Data Creation tab 6.2.2 Other section The Other section (for an example, see Figure 6-8 on page 157) allows you to enter a category that you would like the Notes connection document to display under as well as a comment field that allows you to describe the purpose of the Notes connection document. This section is designed to help make LEI administration simpler. The fields in this section include: Category(s): Category where you want the Notes connection document to appear in the LEI Administrator By Category view. Comments: Comments describing the purpose and relevant details about the Notes connection document. 6.3 File connection document LEI on the iSeries server supports File connection documents. This type of connection document allows you to connect to a subdirectory on the iSeries integrated file system (IFS). File connection documents are sometimes used with direct transfer or archive activities to move files from one file system to another. The File connector allows access to a directory in the server's file system in the style of a relational database, where each ‘row’ represents one file. 166 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Note: The File connection documents cannot be used with virtual documents or virtual agent activities. An example of where File connection documents can be used is if you want to run an activity when a file is created on a file server. In this case you can use a polling activity with the file connection document. Whenever a new file is placed in a particular location in a file system the polling activity trigger a dependant activity. To create a File connection document, open the LEI Administrator database (decsadm.nsf) on the LEI server. Click the Add Connection button and click File. See Figure 6-16. Figure 6-16 Creating a File connection document In the File connection document there are three sections that can be filled in. These sections are: Connectivity: Establishes the basic connectivity for the File connection document. Subdirectory: Contains the selection field definitions. Other: Allows you to categorize your connection documents in the LEI Administrator database, as well as add descriptive comments about the connection. These sections and the fields in the sections are described in detail below. 6.3.1 Connectivity section This section contains information about how to connect to the parent directory of the sub-directory you want connect to. See Figure 6-17 for an example. The fields in this section include: Name: This is any name you want to give to your File connection document. Directory Path: Enter the directory path containing the subdirectory to be used as metadata. This path must indicate the parent directory of the subdirectory containing the needed file(s), not the directory in which the file(s) reside.The specified path must be accessible from the server where the LEI Administrator is installed. For iSeries you can enter a forward slash (/) which will allow you to access the root directory or a period (.) which allows you to access the current directory. The current directory for LEI will typically be the data directory of the Domino server. File Content: This allows you to specify if the contents of the files that will be accessed are Binary (that is, BLOB) or text. Chapter 6. Connection documents 167 Sort Order: Specifies one of the following three file sorting methods: – Sort Filenames as Binary - This option does not consider special properties of text. This option gives the best performance. – Sort Filenames with Case Sensitivity - ‘A’ is different ‘a’. – Sort Filenames without Case Sensitivity - ‘A’ is not different then ‘a’. Figure 6-17 File connection document, Connectivity section 6.3.2 Subdirectory Selection section This section contains information about how to connect to the subdirectory that contains the files. See Figure 6-18 for an example. The fields in this section include: Name: Specifies the name of the subdirectory name to search in. Once specified, all associated file attributes are displayed. File Attributes: Lists the file attributes and corresponding data types of the subdirectories listed. Figure 6-18 File Connection document, Subdirectory Selection section 6.3.3 Other section The Other section (for an example, see Figure 6-8 on page 157) allows you to enter a category that you would like the File connection document to display under as well as a comment field that allows you to describe the purpose of the File connection document. This section is designed to help make LEI administration simpler. The fields in this section include: Category(s): Category where you want the File connection document to appear in the LEI Administrator By Category view. Comments: Comments describing the purpose and relevant details about the File connection document. 168 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 6.4 Text connection document The Text connection document allows data transfer between text files and Lotus connectors. You define formats for the input (source) and output (destination) data in a file, called the ZID file. The ZID file is referenced by file name from the Text connection form, or you can specify the actual ZID file contents entirely within the Text connection form. You can also select various options for processing the source and destination data and can select internationalization of days of the week and months of the year. The Text connection document does not support any browsing. It does not support selection criteria, keyed operations, or conditions. As a result, it cannot be used with the archive activity or with the Advanced RealTime activities (virtual fields, virtual documents and virtual agents). The Text connection document supports a limited select operation with minimal properties and no keys. This allows it to be used in combination with the order metaconnector as the source of a one-way non-timestamp replication activity. In any other configuration, it does not support the replication activity. The command statement has no effect; all records are retrieved for relevant activities, including direct transfer and polling. To create a Text connection document, open the LEI Administration Database (decsadm.nsf) on the LEI server. Click the Add Connection button and then click Text. See Figure 6-19. Figure 6-19 Creating a Text connection document In the Text connection document there are three sections that can be filled in. These sections are: Connectivity: Enables you to specify the full path of the source or destination text file and whether the connection is a source or a target. Text Specifications: Describes either the input or output data, depending on whether you are defining a source or destination form. Other: Allows you to categorize your connection documents in the LEI Administrator database, as well as add descriptive comments about the connection. These sections and the fields in the sections are described in detail below. Chapter 6. Connection documents 169 6.4.1 Connectivity section The Connectivity section (Figure 6-20) defines the file name and path of the source or target file. The fields in the Connectivity section include: – Name: Specifies a unique name that identifies this connection. The maximum number of characters allowed is 255. – File Name: Specifies the path of the source or destination text. When using long filenames, include the filename as is (with any embedded spaces). Do not use quotation marks in the filename since they will be considered part of the filename. – Connection Type: Specifies whether the connection is a source to read from the file or target to write to a file. Figure 6-20 Text Connection document, Connectivity section 6.4.2 Text specifications section The Text Specifications section (Figure 6-21) describes either the input or output data, depending on whether you are defining a source or destination form. File Type: Specifies the type of file you are describing in this form. – Text: Specifies that the file type is text. Text files can be composed of either fixed-length or variable records. – Binary: Specifies that the file type is binary. By default, the Lotus Connector for Text processes files in text mode. Text mode translates each carriage return/line feed combination to mean a new record. In certain circumstances, when records are not delimited by carriage return/ line feed combinations, you might want the Text Connection to process the data exactly as is with no text mode translations, and would select binary as the file type. File Text Character Set: If you want to override the default character set of the underlying Connector, enter the overriding character set in this field. For example, enter CP392 if you wish to override the default character set with the CP392 character set. The default character set is the character set that is native to the system on which you are working. Record Delimiter: If the data records are variable in length, enter the delimiter you are using. The default is \n, indicating a new line or carriage return. Fixed Record Size: Fixed-length records are determined by a user-defined decimal value that specifies the actual record length. Variable length records are determined by a user-specified delimiter in character or hexadecimal notation, for example, a carriage return/line feed. This field is mutually exclusive to Record Delimiter. Figure 6-21 Text Specification section of the Text Connection Document 170 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Field Specifications tab (Figure 6-22): A Text connection offers several options that specify how the data should be processed. For example, you can request that the Connection check for a minimum input record size, strip quotation marks from input text or add quotation marks to output text, and skip a specific amount of data before beginning processing. The fields are described below: Specify field options or, for a ZID file, specify @filename.zid: Either reference the ZID file by name (using the syntax: @filepath\filename.zid) or specify the actual field options. Note: Filepath refers to a file on the Domino server and not the workstation’s local hard drive. An ASCII table is provided to assist you in creating definition strings. The ASCII table lists the decimal, hexadecimal, and character equivalents for the ASCII character set. Supported escape sequence characters are indicated in red text. Character options for 0-255 are available. Figure 6-22 Text connection document, Field Specification tab Text Options - Source tab (Figure 6-23): This tab allows you to specify options if the connection is the source in an activity. The fields are described below: Input Options: Check for Input Values Within Quotes, checking this option places quotes around field values in the output document. Select this option if you want the Lotus Connector for Text to remove quotation marks that surround input text. If you do not select this option, the Lotus Connector for Text puts text into the document fields exactly as supplied. Minimum Record Size: Specifies the minimum record size. Use this option when you need to set a minimum input record length. The default value is 1. A value of 0 indicates that no minimum record length exists. Specifying a value greater than 0 forces the Lotus Connector for Text to bypass input records that are smaller than the specified minimum. This feature is very useful for bypassing junk records or blank lines that might be present in an input text file. Maximum Record Size: Specifies the maximum record size in byes. If fields beyond a certain record size should be ignored, enter the largest valid record size here. The default value is 128K. Skip Records: Specifies the number of records the Lotus Connector for Text should skip before it begins processing. This is useful for ignoring header information or extraneous white space at the beginning of a data file. The default is 0. Skip Bytes: Specifies the number of bytes the Lotus Connector for Text should skip before it begins processing. This is useful for ignoring header information or extraneous whitecap at the beginning of a data file. The default is 0. Chapter 6. Connection documents 171 Figure 6-23 Text connection document, Text Options - Source tab Text Options - Target tab (Figure 6-24): This tab allows you to specify options if the connection is the target in an activity. The fields are described below: Target Options: – Output Values Within Quotes: Selecting this option outputs your data with surrounding quotes. If you do not select this option, the Lotus Connector for Text outputs the data exactly as it exists. – Append Data to Output File: Selecting this option appends the data to an existing file. If you do not select this option, the Lotus Connector for Text processes output text as a new file and overwrites any existing data in the file. If you elect to append the data to an existing file, the Lotus Connector for Text writes the string specified by the record delimiter to the output file before any document processing begins. If the file does not exist, the Lotus Connector for Text creates one. Fill Character/String: Specifies the character that you want to occupy unused or whitecap areas in output records. If you do not enter a value, the Lotus Connector for Text defaults to ASCII blanks. Figure 6-24 Text connection document, Text Options - Target tab Text Options - Processing tab (Figure 6-25): This tab allows you to specify options for the processing of your text file. The fields are described below: ZID Field Options: Echo ZID Field Options, Enabling this option captures the ZID state values in a log file. Maximum records processed, Stop after n records processed: Specifies the maximum number of records that can be processed by a single activity using this connection. Maximum length of simple text data in bytes: Specifies that any record larger than this value will be handled as a composite format binary field. Output File Header: The text value entered here will appear as the first entry in the output file. Output File Trailer: The text value entered here will appear as the last entry in the output file. 172 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 6-25 Text connection document, Text Options - Processing tab Text Options - International tab (Figure 6-26): This option helps LEI translate the language used in the file to be processed. The fields are described below: Days of week: Enables you to enter the days of the week in the expected language of the incoming text file. For example, for a Spanish text file enter Domingo, Lunes, Martes, and so on. Months of year: Enables you to enter the months of the year in the expected language of the incoming text file. For example, for a Spanish text file enter Enero, Febrero, Marzo, and so on. A.M. String: Enables you to specify the A.M. equivalent term in the expected language of the incoming text file. P.M. String: Enables you to specify the P.M. equivalent term in the expected language of the incoming text file. Figure 6-26 Text connection document, Text Options - International tab Text Options - Connection tab (Figure 6-27): The field in this tab is described below: ZID Script Replacement/Substitution Strings, format is “current string = replacement string”: Enables you to specify a substitute string for the current string. You can change the definition of fields in your text file by changing the values of the ZID area of the connection. This lets you change the value assigned to the field to something else. Figure 6-27 Text connection document, Text Options - Connection tab Chapter 6. Connection documents 173 6.4.3 Other section The Other section (for an example, see Figure 6-8 on page 157) allows you to enter a category that you would like the Text connection document to display under as well as a comment field that allows you to describe the purpose of the Text connection document. This section is designed to help make LEI administration simpler. The fields in this section include: Category(s): Category where you want the Text connection document to appear in the LEI Administrator By Category view. Comments: Comments describing the purpose and relevant details about the Text connection document. 6.5 Metaconnectors A metaconnector is a special kind of LEI connector that provides preprocessing operations on connector data prior to transfer within a defined activity form. A metaconnector is usually an intermediary between a source connection document and an activity. To use the metaconnection in an activity, select the metaconnection document in place of using the source connection document. For example, in a situation where you use the order metaconnector to order data from DB2 UDB before doing a replication activity with a Notes database, the replication activity document should use the order metaconnector connection document as the source connection and not the DB2 connection document. An illustration of how data flows when using metaconnectors is shown in Figure 6-28. Source connection document Metaconnector connection document Activity document Target connection document Figure 6-28 Data flow when using metaconnectors LEI 6 supports the following metaconnectors: Collapse/Expand Meter Order Trace 6.5.1 Collapse/Expand metaconnector The Collapse/Expand metaconnector provides the capability to take multiple records from a data source table and collapse them to a single multi-value form field or perform the reverse operation which is to expand the data into multiple records. There is a technote (#1102955) that describes known issues with the Collapse/Expand Metaconnector. This technote can be found at: http://www.ibm.com/support/docview.wss?uid=swg21102955 174 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server To create the Collapse/Expand Metaconnector connection document, open the LEI Administrator database (decsadm.nsf) on the LEI server. Click the Add Connection button and then click Collapse/Expand Metaconnection See Figure 6-29. Figure 6-29 Creating Collapse/Expand metaconnection document See Figure 6-30 for an example of the Collapse/Expand MetaConnector connection document. The fields in the Collapse/Expand Metaconnector connection document are described below: Name: Specifies a unique name that identifies this connection. The maximum number of characters allowed is 255. Connection to Use: Specifies the name of the underlying connection that is providing the data. This will often be an Order Metaconnector. Grouping Keys: Specifies the field or list of fields that define the grouping key. One internal record is constructed from all external records with the same key value. To ensure that all records with this key value are collapsed into a single multi value record, make sure that the external result set is ordered using the Order Metaconnector by the grouping key fields. Note: Grouping occurs only on exactly equal keys, it is not possible to ignore case even if combining the Collapse/Expand Metaconnector with the Order Metaconnector. Additional Write Keys: Specifies additional keyfield or fields which define the unique key within a collapsed record. For example, if four orders by a single customer are collapsed into one document, with the customer number as the key, and one order is changed, then the order number may be required to ensure the key's uniqueness across individual external records for this customer on expansion. Other Options, Disable Trimming of Text Trailing Spaces: Disables the trimming of trailing spaces in text data. In normal operation, whenever text data is fetched from a connection, trailing spaces are removed from the text. The property NoTrimText has been added to the direct transfer and replication activities. When using this option in a direct transfer or replication activity that uses a Collapse/Expand Metaconnector, you must also select this option here in the metaconnection document. Chapter 6. Connection documents 175 Figure 6-30 Collapse/Expand metaconnector connection document 6.5.2 Meter metaConnector The Metering metaconnector provides a way to collect statistical usage data. A Meter Metaconnection can identify and quantify data access. To create the Meter Metaconnector connection document, open the LEI Administrator database (decsadm.nsf) on the LEI server. Click the Add Connection button and then click Meter Metaconnection. See Figure 6-31. Figure 6-31 Creating a Meter metaconnection document See Figure 6-32 for an example of the Meter Metaconnector connection document. The fields in the Meter Metaconnector document are described below: Name: Specifies a unique name that identifies this connection. The maximum number of characters allowed is 255. Connection to Use: Specifies the name of the underlying connection that is providing the data. Subtotal Frequency: Specifies how often to record subtotal results computed in number of records. Subtotals can be printed during the process. The number specified is how many records to process to get subtotal information. For example, if you process 1000 records 176 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server and the subtotal frequency is set to 300, you would receive 3 subtotal results and a final tally. Key Fieldname: Use this to generate results grouped by a particular data field value. This is an optional field containing the value to group results by. Meter Filepath: Specifies the path to the meter log file. Note: The meter log file is written to a directory accessible from the LEI server. To transfer this file into a database, follow the metering activity with a direct transfer using the Lotus Connector for Files to access the meter log file and any other Connector as the destination. Record Level: Selects the items to track at the record level. The options are: – Track Bytes: reports the number of bytes per record. – Track Keys: reports the key field value(s) for each record. – Track Timestamp: reports the current time for each record. Total Level: Selects the items to track at the subtotals and totals level. The options are: – – – – Track Bytes: reports the number of bytes per record. Track Records: reports the number of records transferred. Track Keys: reports the key field value(s) for each record. Track Timestamp: reports the current time for each record. Figure 6-32 Meter Metaconnector connection document 6.5.3 Order metaConnector The Order metaconnector is useful when ordering data sets from different server sources. For example, a DB2 UDB table on an iSeries server and a Notes database on a Domino server may use different order systems when ordering data. This can result in a data set comparison problem when using a LEI replication activity, which requires data sets to be ordered in parallel for data set comparisons. The Order Metaconnector may be applied in this situation to preprocess the data sets to be compared during the activity, ensuring the order pattern will be in parallel for accurate data set comparisons during the replication activity. This is particularly true when replicating iSeries DB2 UDB data with Notes databases. For more information about this issue, see technote 110127, LEI Addressing Sort Order Issues When Replicating DB2/400 Data to a Notes Database accessible at: http://www.ibm.com/support/docview.wss?uid=swg21101027 Chapter 6. Connection documents 177 To create the Order Metaconnector connection document, open the LEI Administrator database (decsadm.nsf) on the LEI server. Click the Add Connection button and then click Order Metaconnection. See Figure 6-33. Figure 6-33 Creating a Order metaconnection connection document See Figure 6-34 for an example of an Order metaconnector connection document. The fields in the Order metaconnector document are described below: Name: Specifies a unique name that identifies this connection. The maximum number of characters allowed is 255. Connection to Use: Specifies the name of the underlying connection which is providing the data. Metadata Name: Specifies the name of the selected table. When you select the connection to use, the metadata name appears in this field. Owner: Specifies the owner name of the selected metadata. Text Trimming: Allows you to disable trimming of text trailing spaces. Sort Character Set (optional): Specifies the optional character set to force text data into. By default, the underlying connection's character set is used. To provide a character set, use the corresponding constant suffix. Character sets are listed in the Lotus Connector LotusScript Extensions Guide. For example, for character set Code Page 932, represented by the LEI constant LCSTREAMFMT_CP932, enter CP932 here. Sorting Fields *if not provided in Activity: Contains a list of fields in which to sort data. For activities where ordering is specified, such as replication, these selections are overridden and therefore ignored in the connector form. For other activities, this is a place to provide the ordering (which was not available before). Sorting Options: Specifies whether to sort in ascending (default) or descending order. LEI replication depends on an ascending sorting to operate properly. Do not use the Sort Descending option with a replication activity. Order: Specifies how text is to be sorted. The choices are: – Sort Text as Binary – Sort Text with Case Sensitivity – Sort Text without Case Sensitivity 178 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 6-34 Order metaconnector connection document 6.5.4 Trace metaConnector The Trace metaconnector allows you to trace events associated with a specified sub connection. You may specify options including where to capture data and whether or not to include a timestamp with each trace log entry. The Trace metaconnector is a tool for you and the Lotus support staff to use when troubleshooting. To create the Trace Metaconnector connection document, open the LEI Administrator database (decsadm.nsf) on the LEI server. Click the Add Connection button and then click Trace Metaconnection. See Figure 6-35. Figure 6-35 Creating a Trace metaconnector connection document Figure 6-36 shows an example of a Trace metaconnector document. The fields in the Trace metaconnector document are described below: Name: Specifies a unique name that identifies this connection. The maximum number of characters allowed is 255. Connection to Use: Names the underlying connection to be traced. Chapter 6. Connection documents 179 Trace is displayed on screen: Specifies whether or not to write trace data to the LEI console window. Trace is written to a file: Allows you to capture trace data to a text file. All output captured to a log file is appended to the end of the file. If the output file does not exist, it will be created. If the log file cannot be opened, a message indicating this will be sent to the activity log. The log file can grow quite large. You can delete the log file when the trace data is no longer needed. Log Filename: User-specified log file name that allows you to specify a log file name. This option can provide more control over the trace output destination. Note: The default log file name is trace.log. If you specify some other name (using the Log Filename option), such as "c:/foo/mytrace.log" on Win32, then the initial output, up to the point where the file name parameter is read, will be sent to "trace.log", and trace output after that point will be logged to the "c:/foo/mytrace.log" file. Trace is written to the activity log: Determines whether or not output will be written into the activity log. Record time stamp with each logged entry: Records a timestamp with each entry that is captured in the log file. Figure 6-36 Trace metaconnector connection document 6.6 Test connection documents using the CONTEST utility CONTEST is a utility that is provided with LEI. CONTEST tests that a specific Lotus connection can actually access the external system. For example, when you create a named connection using an LEI connection document, run CONTEST on that connection name before running any LEI activity that uses it. Perform the following steps to use the CONTEST utility: 1. Log onto the iSeries server. 2. On the OS/400 command line, enter the following CL command: CALL PGM(QNOTES/CONTEST) PARM('Name Of Connection Document') 3. You will be prompted to enter the name of the LEI server. Enter the name and press Enter. Make sure that the test completes successfully before continuing. See Figure 6-37. 180 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Enter the name of the local Domino server configured for LEI whose connection you want to test: > leidomsvr Testing Connect to DB2 Address File Connect to DB2 Address File Connection Successful Press ENTER to end terminal session. ===> F3=Exit F4=End of File F6=Print F9=Retrieve F17=Top F18=Bottom F19=Left F20=Right F21=User Window Figure 6-37 Successful results from CONTEST utility Chapter 6. Connection documents 181 182 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 7 Chapter 7. Setting up the examples environment This chapter discusses the setup activities required to run the examples in this redbook. Setting up the examples environment requires the following objects: OS/400 libraries and tables DB2 UDB journal Domino databases Note: For information about how to download, from the Internet, the OS/400 libraries and Domino databases used in the examples in this redbook, see Appendix D, “Additional material” on page 317. © Copyright IBM Corp. 2003. All rights reserved. 183 7.1 OS/400 libraries In DB2 UDB on the iSeries server, a library is a system object that serves as a directory to other objects. A library groups related objects and allows the user to find objects by name. Before you can create a database file, you must create a library to store it. This section lists all the libraries and the databases required to run the examples in Chapter 8, “Advanced RealTime activities” on page 195 and Chapter 9, “Batch activities” on page 255. For more information about libraries on the iSeries server, refer to the IBM ~ iSeries Information Center version 5 release 2 (V5R2) at: http://publib.boulder.ibm.com/iseries/v5r2/ic2924/index.htm?info/rzahf/rzahfli0.htm Note: For information about how to download, from the Internet, the OS/400 libraries and Domino databases used in the examples in this redbook, see Appendix D, “Additional material” on page 317. The examples in this redbook use two libraries: EMPLIB and AUTOBODY. 7.1.1 Download and set up the libraries You will need to download the EMPLIB and AUTOBODY save files from the ITSO FTP site (see Appendix D, “Additional material” on page 317 for details) in order to run the examples shown in this redbook. Once you have the save files downloaded from the Internet, perform the following steps to upload them to your iSeries server and then create the EMPLIB and AUTOBODY libraries: 1. From your 5250 emulation session, create two save files using the following Create Save File (CRTSAVF) CL commands:. CRTSAVF FILE(QGPL/EMPLIB) CRTSAVF FILE(QGPL/AUTOBODY) 2. Open a DOS prompt window to FTP the save files from your local PC workstation to your iSeries server using the following commands: ftp <iSeries server name> <enter your OS/400 user profile> <enter the password for your OS/400 user> bin cd /QSYS.LIB put EMPLIB.SAVF QGPL.LIB/EMPLIB.FILE (replace put AUTOBODY.SAVF QGPL.LIB/AUTOBODY.FILE (replace quit Figure 7-1 shows an example of the FTP commands used to upload the EMPLIB save file. 184 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 7-1 DOS prompt window for FTP 3. From your 5250 emulation session, restore the libraries from the save files using the following Restore Library (RSTLIB) CL commands: RSTLIB SAVLIB(EMPLIB) DEV(*SAVF) SAVF(QGPL/EMPLIB) RSTLIB SAVLIB(AUTOBODY) DEV(*SAVF) SAVF(QGPL/AUTOBODY) 4. To make sure that you have successfully created the libraries, start iSeries Navigator and confirm that EMPLIB and AUTOBODY are listed under libraries as shown in Figure 7-2. If these libraries are not displayed, refer to Appendix B, “Using iSeries Navigator to access DB2 UDB” on page 285 for instructions about how to display a library from iSeries Navigator. Figure 7-2 Displaying libraries on the iSeries server using iSeries Navigator 7.1.2 EMPLIB library The EMPLIB library contains the following objects: Chapter 7. Setting up the examples environment 185 CASE_FILES table DEPARTMENT table EMPLOYEE table EMPLOYEE2 table PATIENT table EMP_DEPT view CASE_FILES table The CASE_FILES table contains information about cases for a law firm. Note: The CASE_FILES table is not included in the library during download. This table is programmatically created by a scripted activity in Example 9.1.1 on page 256. Table 7-1 describes the column names, data type, and size of the data columns. Table 7-1 CASE_FILES table Column name Data type and size Description CASENUM SMALLINT Case number DATEOPENED DATE Date a case is opened TITLE CHARACTER(50) Title of a case DESCRIPTION CHARACTER(100) Brief description STATUS CHARACTER(15) Current status OPENEDBY CHARACTER(20) The person who opens the case ASSIGNEDTO CHARACTER(20) The person who is assigned the case CLIENT CHARACTER(20) The company name of the client CONTACT CHARACTER(20) Contact person from the client’s company CONTACTPHONE CHARACTER(12) Contact phone number CREATEDBY CHARACTER(40) The person creating the document CREATIONDATE DATE Date the record is created MODIFIEDDATE TIMESTAMP Date the record is last modified BODY BLOB(5 MB) Additional information, including images, attachments, and so on DEPARTMENT table The DEPARTMENT table contains detailed information about a department. It is used in the examples to look up the department name and location (given a department number). Table 7-2 describes the column names, data type, and size of the data columns. Table 7-2 DEPARTMENT table 186 Column name Data type and size Description DEPTNO CHARACTER(3) Department number DEPTNAME VARCHAR(36) Department name LOCATION CHARACTER(30) Department location Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server EMPLOYEE table The EMPLOYEE table stores employee profile information. It is a simple table with no constraints. Table 7-3 describes the column names, data type, and size of the data columns. Table 7-3 EMPLOYEE table Column name Data type and size Description EMPNO CHARACTER(6) Employee number FIRSTNAME VARCHAR(15) First name LASTNAME VARCHAR(15) Last name MIDINIT CHARACTER(1) Middle initial PHONENO CHARACTER(4) Phone number HIREDATE DATE Hire date SALARY DECIMAL(9,2) Salary PICTURE BLOB(2 MB) Employee photo WORKDEPT CHARACTER(3) Department number EMPLOYEE2 table The EMPLOYEE2 table is identical to the EMPLOYEE table. We made a copy of EMPLOYEE table because of the virtual documents limitation described in Figure 8-3 on page 204. EMPLOYEE table is already used in “Example 1: Using a virtual documents activity” on page 206. PATIENT table The PATIENT table contains patient information for a medical center. Table 7-4 describes the column names, data type, and size of the data columns. Table 7-4 PATIENT table Column name Data type and size Description PATIENTNO CHARACTER(6) Patient number LASTNAME VARCHAR(20) Last name FIRSTNAME VARCHAR(20) First name MIDINIT CHARACTER(1) Middle initial SEX CHARACTER(1) Sex DOB DATE Date of birth ALLERGIES VARCHAR(100) History of allergies MEDHISTORY BLOB(1 MB) Medical history DATE_MODIFIED TIMESTAMP Date the record is last modified EMP_DEPT view A view is a logical representation of a table, more than one table, or even other views. Users can use views to access data from one or more tables in an alternate format and sequence than what is represented in the table. Chapter 7. Setting up the examples environment 187 Unlike tables, views contain no data records, only relative row number pointers to the location of the rows in the table. These pointers are part of the access path or index that lets the system retrieve data in the required sequence. These pointers are dynamically maintained by the iSeries server. When a view is used for more than one table or view, the tables or view are said to be joined. EMP_DEPT view is created by joining EMPLOYEE and DEPARTMENT tables using an inner join. The following SQL statement is used during the creation of the view to join the tables: SELECT * FROM EMPLIB.EMPLOYEE EMPLOYEE INNER JOIN EMPLIB.DEPARTMENT DEPARTMENT ON EMPLOYEE.WORKDEPT = DEPARTMENT.DEPTNO 7.1.3 AUTOBODY library The AUTOBODY library contains the following objects: DAMAGETOT stored procedure AUTOBODY_DAMAGE table AUTOBODY_EST table DAMAGETOT stored procedure Stored procedures are compiled programs that can be stored on your iSeries server. Creating your programs as stored procedures allows you to call them from an SQL application. Stored procedures may be called repeatedly, may call other programs, and may be saved to tape and restored on other systems. DAMAGETOT stored procedure calculates and updates the total estimate of an automobile repair based on the subtotals. The following lists the SQL statements in this stored procedure: P1 : BEGIN DECLARE TEMP_ESTIMATEID INTEGER ; SET TEMP_ESTIMATEID = ESTIMATEID ; UPDATE AUTOBODY . AUTOBODY_EST SET TOTAL = ( SUBTOTQUANT * SUBTOTPART ) + ( ( SUBTOTLABOR + SUBTOTPAINT ) * 45 ) WHERE ESTIMATEID = TEMP_ESTIMATEID ; END P1 AUTOBODY_DAMAGE table The AUTOBODY_DAMAGE table contains the details of parts, quantity, labor, and so on, that would be included in the estimate of an automobile repair. Table 7-5 describes the column names, data type, and size of the data columns. Table 7-5 AUTOBODY_DAMAGE table 188 Column name Data type and size Description ESTIMATEID INTEGER Estimate id ITEMNO VARCHAR(10) Item number DESC VARCHAR(50) Description QUANT INTEGER Quantity PART DECIMAL(7,2) Parts unit cost LABOR DECIMAL(7,2) Labor unit cost PAINT DEIMAL(7,2) Paint unit cost Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server AUTOBODY_EST table The AUTOBODY_EST table contains estimated repair data for automobiles. Table 7-6 describes the column names, data type, and size of the data columns. Table 7-6 AUTOBODY_EST table Column name Data type and size Description ESTIMATEID INTEGER Estimate id FNAME VARCHAR(20) Customer’s first name LNAME VARCHAR(20) Last name STREET VARCHAR(30) Street address CITY VARCHAR(30) City STATE VARCHAR(30) State ZIP VARCHAR(15) Zip code PHONE VARCHAR(20) Phone number SUBTOTQUANT DECIMAL(7,2) Subtotal quantity SUBTOTPART DECIMAL(7,2) Subtotal parts SUBTOTLABOR DECIMAL(7,2) Subtotal labor SUBTOTPAINT DECIMAL(7,2) Subtotal paint TOTAL DECIMAL(8,2) Total amount (calculated based on subtotals) VEHICLEYR VARCHAR(8) Vehicle year VEHICLEMAKE VARCHAR(20) Vehicle make VEHICLEMODEL VARCHAR(20) Vehicle model VEHICLEPHOTO BLOB(5 MB) Vehicle photo 7.2 Domino databases We have created several Domino databases for the examples in Chapter 8, “Advanced RealTime activities” on page 195 and Chapter 9, “Batch activities” on page 255. These databases include: Autobody demo database (autobodydemo.nsf) Case files database (casefile.nsf) Employee database (employee.nsf) Medical records database (medrec.nsf) These databases are available for download from the ITSO FTP site, see Appendix D, “Additional material” on page 317 for details. Once you have downloaded and unzipped the Domino database files from the ITSO FTP site, you must copy these files to the Domino server’s data directory on the iSeries server. Chapter 7. Setting up the examples environment 189 Note: We recommended that after copying the Domino databases to the Domino server’s data directory, that you verify the ownership of these files using the Work with Authority (WRKAUT) CL command. These database files must have the ownership of QNOTES. To change the ownership of a file, you use the Change Owner (CHGOWN) CL command. 7.2.1 Autobody demo database (autobodydemo.nsf) The autobody demo database (autobodydemo.nsf) contains estimates for repairing automobiles damages and the detailed parts necessary to fix the automobile. It is used in “Example 5: Using virtual agents and virtual attachments” on page 237 to demonstrate using virtual agents and virtual attachments. The primary design element of the Autobody demo database is the Virt Claim Estimate form. Figure 7-3 and Figure 7-4 show an example of a document created using the Virt Claim Estimate form. Figure 7-3 Claim estimate document - Customer tab 190 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 7-4 Claim estimate document - Damage tab The example in “Example 5: Using virtual agents and virtual attachments” on page 237 also demonstrates using multi-value data. In Figure 7-5, the ItemNo and Desc fields are text lists. The Quant, Part, Labor, and Paint fields are number lists. Multi-value data in virtual fields allows a single document in a Notes database to relate to multiple records in the external system. In this example, for a specified EstimateId, multiple rows are retrieved from the AUTOBODY_DAMAGE table and are used to populate the text lists and number lists. This is accomplished by enabling multi-value data in the virtual fields document. Figure 7-5 Multi-value data in virtual fields Chapter 7. Setting up the examples environment 191 7.2.2 Case files database (casefile.nsf) The case files database (casefile.nsf) contains information about cases for a law firm migrating from Domino to DB2 UDB. It is used in “Example: Building a direct transfer scripted activity” on page 256 to demonstrate how to use a scripted activity. The primary design elements of this database include: Case form Examples script library Figure 7-6 shows an example of a document created using the case form. Figure 7-6 Case file document The content of the script library is displayed in Example 9-1 on page 257. 7.2.3 Employee database (employee.nsf) The employee database (employee.nsf) contains forms and views to display employee profile information. It is used in Chapter 8, “Advanced RealTime activities” on page 195 for examples about how to use the Advanced RealTime activities. The following forms are in this database: EmpProfile - Used in “Example 1: Using a virtual documents activity” on page 206. EmpProfileDB2View - Used in “Example 2: Using virtual documents with a DB2 UDB view” on page 216. All the fields in this form are read-only. EmpProfileVirtualFields - Used in “Example 3: Using virtual fields with multiple DB2 tables” on page 224. EmpProfileVirtualDocsAndFields - Used in “Example 4: Using virtual fields with virtual documents” on page 231. The EmpProfile form has fields pertaining to the EMPLOYEE table only. The other three forms (EmpProfileDB2View, EmpProfileVirtualFields, and EmpProfileVirtualDocsAndFields) contain fields from both EMPLOYEE (or EMPLOYEE2) and DEPARTMENT tables. Figure 7-7 shows an example of a document created using these three similar forms. 192 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 7-7 Sample employee document 7.2.4 Medical records database (medrec.nsf) The medical records database (medrec.nsf) keeps track of the medical record of patients for a medical facility. It is used in “Example: Timestamp replication from DB2 UDB to Domino” on page 266 to demonstrate how to use timestamp replication. The primary design element of this database is the patient form. Figure 7-8 shows an example of a document created using the patient form. Figure 7-8 Sample patient medical record document Chapter 7. Setting up the examples environment 193 194 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 8 Chapter 8. Advanced RealTime activities This chapter describes the Advanced RealTime activities of virtual documents, virtual fields and virtual agents, including the differences between virtual documents and virtual fields. It provides examples of when to use virtual documents versus virtual fields and when to use a combination of both activities. This chapter also discusses virtual attachments and virtual agents and provides an example of how to utilize them. This chapter does not discuss the Advanced RealTime feature of integrated credentials. For more information about integrated credentials, refer to 2.2.2, “Integrated credentials” on page 37. In LEI 6.0.1 for iSeries, only connection to DB2 UDB external database is supported (see Chapter 6, “Connection documents” on page 153 for all supported connections). Therefore, all discussions and examples in this chapter focus on DB2 UDB. Note: Before the running the examples in this chapter, be sure that you have the required setup completed for the examples. Refer to Chapter 7, “Setting up the examples environment” on page 183 for more details. Each example in this chapter informs you of which databases are required. © Copyright IBM Corp. 2003. All rights reserved. 195 8.1 Virtual documents activity The virtual documents activity allows Domino users to open, create, update, or delete external data (such as DB2 UDB) directly and transparently through a Lotus Notes/Domino application. Even though the data resides in an external database, from the end users’ point of view, it is as if they are working solely in a Domino database and may not be aware of the presence of an external database. DB2 UDB connectivity software is not required on the client systems. However, it must be installed on the Domino server system. Network access to the external data source is handled by the Domino server, which contains LEI connectivity software for the DB2 UDB external data source. For step-by-step virtual document examples, refer to 8.6, “Example 1: Using a virtual documents activity” on page 206 and 8.7, “Example 2: Using virtual documents with a DB2 UDB view” on page 216. 8.1.1 How does the virtual documents activity work? The following elements are required to setup a virtual documents activity: A connection document to the external database must exist. See Chapter 6, “Connection documents” on page 153 for more details. A virtual documents activity document which specifies the Domino form that will be monitored by the activity and the mapping between the Domino form fields and the external system table columns. You also need to make sure that the external system contains a table with four special columns that map to Domino generated control fields. Refer to 8.1.2, “External system metadata for virtual documents activities” on page 197 for more details about these four special columns. Once all the required elements are in place, the virtual documents activity must be running in order for you to work with the external data. With the virtual documents activity running, you can create a new document in Domino and save it. A new record will be created in the external system table containing the data you entered along with the extra information needed by Domino to treat this record as if it were a ‘normal’ Domino document. Then, when you open the document later in Domino, it will be displayed correctly (including any database links, document links, attachments, and so on). Views containing view selection formulas will correctly display your virtual documents as required by the selection formula. You can also open, update, and delete documents as long as the virtual documents activity is running. If the activity is no longer running, and you attempt to open a document from a view, you will be prompted with an error message. Refreshing the view while a virtual documents activity is not running causes all of the non-native document information to disappear from the view. If the external data is updated by a non-Domino application, the changes will not be immediately effective in Domino until the Domino view is refreshed. Use function key F9 to refresh or Shift+F9 to rebuild the view if the data is altered in this fashion. Note: Shift+F9 is a more expensive operation than F9, but it produces immediate results. Shift+F9 should be used sparingly. 196 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server The same is true for newly created external data. If another external system client creates records, the newly created records are automatically virtualized if you enable the Virtualize External System Data option in the General Options section of the virtual documents activity document and will appear in the view when it is refreshed. Deletions and insertions should be performed with the Domino client through the virtual documents activity instead of through non-Domino clients and applications. This helps ensure the integrity of other Domino processes, such as replication, as it concerns virtual documents. For more information about this topic, refer to 1.3.3, “Current limitations with using LEI 6” on page 8. 8.1.2 External system metadata for virtual documents activities Unlike the virtual fields activity, a virtual documents activity does not require key documents. However, it does require a table in the external system with four special columns that map to Domino-generated control fields. There are two ways to accomplish this: Internal key table Add the four control data columns (described below) to the external system data table directly. This is the table that will be mapped to the Domino form in the virtual documents activity. For maximum performance, always index the data table key columns (see 8.1.3, “Indexing” on page 199). External key table Create a separate table, called an external key table, on the external system that contains only the four control data columns plus a foreign key field(s) to map to the actual data table. You can use the table creation utility button in the virtual documents activity document to automatically create this separate table (external key table). 8.6, “Example 1: Using a virtual documents activity” on page 206 provides step-by-step instructions about how to do this. If you elect to use the external key method, specify the name of the external key table in the virtual documents activity form and the key(s) used to map the key table to the actual data table. These keys can be made up of a combination of fields. The advantage to this method is that you do not need to alter an existing data table. When using an external key table to store the Domino control fields, the key table must reside in the same database and library, and have the same user access rights as the data table. For a discussion about the performance of adding the control data columns to the data table directly versus creating the external key table, refer to 2.3, “Performance considerations” on page 41. With either method, the additional four control data columns are automatically mapped to corresponding internal Domino fields when the virtual documents activity is created. You do not need to map them in the mapping section of the virtual documents activity document. They do not appear when you enable manual mapping. There is nothing you have to do to ensure their being mapped other than to be certain that the names and data types are correct. The four additional Domino control data columns required are described in Table 8-1. Chapter 8. Advanced RealTime activities 197 Table 8-1 Domino control data columns Column Name Data Type Description EINOTEID** INTEGER Defaults to zero. This field must not be NULL. This field contains the enterprise integration notes ID. It is an integer field. EIUNID** CHARACTER(32) Contains the enterprise integration unique ID. EIMODIFIED** TIMESTAMP A timestamp that tracks the last time this document was modified. EINOTEPROPS BLOB Contains any Notes property related to the corresponding field as binary large data types (BLOBs) ** For all applications, it is strongly recommended that you limit the number of revision entries maintained for virtual documents. In the database advanced properties tab, set the ‘Limit entries in $Revisions fields’ and ‘Limit entries in $UpdatedBy fields’ to three or less. Important: These four column names must not be altered! The external system column names, whether added to the existing data table or created in an external key table, must match these names exactly and must be of the appropriate data types. For more information about these four Domino control data columns, refer to the LEI Activities and User Guide (leidoc.nsf). This guide is available in the /help directory of the Domino server’s data directory where your LEI server is installed. You can also download it from the Lotus Developer Domain Documentation Library at the Web address of: http://www.lotus.com/ldd/notesua.nsf Considerations on creating an external key table When creating virtual documents with the external key table option, the following considerations apply: You must enable writeback in order to modify a key using an external key table. Modification of non-key fields does not require writeback. Alternatively, you can delete the record and then recreate it with a new key value. The data table and the external key table must reside on the same external system data source (same connector/server/database/userid/password, different table name). If rows are deleted from the data table by another application and the corresponding entry in the ID table is not deleted, you will receive ‘unable to retrieve external record’ errors when you attempt to access that virtual document. Refer to 8.1.4, “Deletion involving virtual documents” on page 199 for more information. If there are data rows with duplicate keys, only one ID table entry will be created. Only the first data row will be retrieved on open, and both records will be modified on delete and update. For maximum performance, always index the data table key columns (see 8.1.3, “Indexing” on page 199). Regardless of whether the corresponding key columns in the data table may be constrained to not allow duplicate values, do not impose that setting on the key columns in the external key table. In the external key table, key columns should be set to allow duplicate values. There is no support currently for adding the four required columns (EINOTEID, EIUNID, EIMODIFIED, and EINOTEPROPS) to an existing table from the virtual documents activity 198 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server document. If you would prefer to add the fields to an existing table, you could create the external table first, then use your relational database configuration tool to copy fields to the table you want them to appear in. Notice which columns are indexed in the external key table and retain those indexes when you copy the fields. Alternatively, you can create a new table with the new columns and then use an LEI direct transfer activity to copy the data from the old table to the new table. 8.1.3 Indexing Indexing is an important requirement for proper virtual documents activity operation, as well as for proper operation of virtual attachments when they are used with virtual documents activities. Note: When using a virtual documents activity that also uses virtual attachments, you must only virtualize that once. If you reset the EINOTEID back to zero and there are virtual attachments present, they will become inaccessible through Notes. There will be no way to retrieve them from the external system database. For virtual documents, it is strongly recommended that the external system data columns listed in Table 8-2 be indexed for maximum performance. Table 8-2 Data columns to index Column Name Required or Optional When to Use EINOTEID Required Always EIMODIFIED Required Always EIUNID Optional When supporting Web applications through Domino HTTP server. Foreign key Required Always when using external key tables. 8.1.4 Deletion involving virtual documents When a virtual document is deleted, a stub of the former document still remains in Domino. This deletion stub is represented in the external system database in one of three ways: If an external key table is used, the stub is effectively maintained in the key table and the actual data row in the data table is deleted. The only special consideration is that the data key column(s), in the external key table only, should be set to Allow Duplicate Values, even if the corresponding key in the data table is unique. If you do not use an external key table because you have elected to append the four Domino control columns (EINOTEID, EIUNID, EIMODIFIED, and EINOTEPROPS) directly to the data table, by default the table row is not removed. When a virtual document is deleted, it is recognized by Domino as a deleted document and will not be accessible to any Notes user. However, interrogation of the external system table using a SQL client or other external system client will show that the row is in fact not deleted. It remains intact with all the original data. Only the Domino control fields have been changed to designate it as a deletion stub, thus rendering it deleted from Domino's perspective. To prevent the data deleted from external system from showing, disable the maintain deletion stubs option in the activity document. However, this action prevents Domino deletions from being seen in database replicas. It may also cause unexpected behavior if replicas of the deleted virtual documents are subsequently updated. Chapter 8. Advanced RealTime activities 199 Note: If you use the external key table on the virtual documents activity document, you should not disable the maintain deletion stubs option. Virtual documents fully supports Domino soft deletions. A soft deleted virtual document will behave like a native soft deleted document in Domino. However, it will not appear deleted in the external data table. 8.1.5 Domino replication involving virtual documents If you have a virtual documents activity set up for a Domino database and you use native Domino replication either locally to a workstation or to another Domino server, the replica will contain only native Domino documents. When using Domino replication involving virtual documents, consider the following scenario as described in Figure 8-1. Domino server 2 has a Domino database with virtual documents activity running against a DB2 UDB table. Domino replicas are created on Domino server 1 and on local workstations. When the LEI server is down, users create new documents on the Domino replicas (that is, on Domino server 1 or local replicas). As a result, the new documents will never be inserted in the DB2 UDB table. The new documents will become native Domino documents. When LEI server is running, new documents will only be replicated to the Domino database on Domino server 2. Domino server 1 Create New Documents nsf Domino Replication Domino server 2 with LEI Domino Replication Virtual Documents activity nsf DB2 UDB Domino Replication Figure 8-1 Domino replication and adding new documents A similar scenario to consider is described in Figure 8-2. Domino server 2 has a Domino database with virtual documents activity running against a DB2 UDB table. The virtual documents activity is created using external key table. Domino replicas are created on Domino server 1 and on local workstations. 200 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server If external business applications (such as RPG or Cobol programs) delete rows from the DB2 UDB table, the deletion will not be reflected in the Domino replicas. The reason is that the key of the deleted records still exist in the external key table. Domino server 1 nsf Domino Replication Domino Replication Domino server 2 with LEI DB2 UDB Virtual Documents activity nsf Table External Keys Table Delete rows Business applications (i.e. RPG, Cobol programs). Domino Replication Figure 8-2 Domino replication and externally deleting from DB2 UDB 8.1.6 Event options for virtual documents activity There are four events that occur in the Domino form that are always monitored by a virtual documents activity: Create Open Update Delete You can add a Domino formula or stored procedure to further control these events. Refer to the LEI Activities and User Guide for more information. 8.2 Virtual fields activity As with virtual documents, virtual fields activity (previously known as the LEI real time activity or the DECS activity in Domino) allows Domino users to open, create, update, or delete external data directly and transparently through Lotus Notes/Domino application. Virtual fields functionality includes the following features not available in the previous versions of the real time activity function: Support for computed subforms. Options for new line delimiters. Integrated credentials. Support for procedure return parameters following insert and update operations. Chapter 8. Advanced RealTime activities 201 Output from write operations allows results of write operations to be returned to fields in the Domino document being monitored following insert and update operations. One activity can monitor all forms in a database, making it possible to perform a generic lookup of a given field. For a step-by-step virtual fields example, refer to 8.8, “Example 3: Using virtual fields with multiple DB2 tables” on page 224. 8.2.1 How does the virtual fields activity work? The following elements are required to setup the virtual fields activity: A connection document to the external database must exist. See Chapter 6, “Connection documents” on page 153 for more details. One or more virtual fields activity document where you specify which Domino form to monitor and map the Domino fields to the fields of the external table(s). If you are connecting to one external table, then you only need one virtual fields activity. However, if you need to connect to multiple external tables, you will need multiple virtual fields activity documents. With multiple virtual fields activity documents, you need to specify the monitor order. If you use more than one virtual fields activity for a single Domino form, you may specify the order in which the virtual fields activities are executed. The monitor order also enables you to use multiple activities which connect to different tables and use the value found by the first virtual fields activity as a key for subsequent virtual fields activities. Once all the required elements are in place, the virtual fields activity must be running in order for you to work with the external data. In addition, you must have key documents, which are ‘real’ Domino documents containing only the key fields. Therefore, the key fields and retained fields (external fields stored in the key document) will show up in Domino views. The rest of the fields are virtual fields that you can only see when you open the document while the virtual fields activity is running. The key documents are not automatically created. You can use the Initialize Keys option to populate the Domino database with one key document for each external system record. LEI uses the key to fetch the external data and populate the rest of the fields when the document is opened. Initialize keys is a one-time task to populate a new Domino database with the necessary key documents. In order to incorporate new data that is added to the external data from outside Domino, use an LEI replication activity. If a new document is created through the Notes client, a key document will be created and saved with the key values. There are other methods you can use to populate the Domino database with key documents. For example, a virtual fields activity running a stored procedure, or an LEI replication activity, or a Domino agent with a script to create the key documents. Even though by default only the key fields are stored in a key document, you have the option to store all or selected external fields in your Domino form. This is accomplished through setting the appropriate option available in the General Options tab of a virtual fields activity document. Storing the external data in your Domino form is useful if you want to show the fields in the view. 8.2.2 Event options for virtual fields activity There are four events that occur in the Domino form that can be monitored by a virtual fields activity: Create 202 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Open Update Delete You can add a Domino formula or stored procedure to further control these events. Refer to the LEI Activities and User Guide for more information. 8.3 Differences between virtual documents and virtual fields Both virtual documents and virtual fields activities enable transparent use of external data from Domino. The primary distinction between the two is that virtual documents do not require key documents (previously referred to as stub documents) which need to have the keys initialized. Virtual fields do require such documents and the keys initialization. Furthermore, virtual documents fully support views and view refreshes. In a virtual documents activity, all fields on the Domino form must be mapped in order for any changes to the field to be saved. Since none of the document resides in the Domino database (.nsf file), all field data is retrieved from the external system database. Any fields that are not mapped to external database fields will not be stored. In contrast, using a virtual fields activity, any field that is not mapped to external system data is saved in the Domino document. This is because in the virtual fields activity, the key documents exist in the .nsf file. Virtual documents activities always monitor all available form events (create, open, update, and delete). In virtual fields activities, you must specify which events to monitor. 8.3.1 Advantages of virtual documents activity Following are the advantages of using a virtual documents activity: No component of the actual Domino document is stored natively in the Domino application. However, all the data is available to a Domino user and is indistinguishable from data actually stored in Domino. You are not required to maintain key documents in Domino applications, making it more scalable and easier to maintain. Virtual documents fully supports views and view refreshes. By contrast, virtual field data will not appear in a view unless the user elects to leave selected non-key virtual fields monitored fields in the key document, these could potentially contain stale data even after refreshing the view. Virtual document activities support background virtualization of records added to the external system. This process automatically adds new records that have been added to the external system to views. It also virtualizes all records in the existing data table that have not been virtualized. 8.3.2 Limitations of virtual documents activity Following are the limitations of using virtual documents activity: One Domino form can only be mapped to one virtual documents activity. One Domino form can only be mapped to one external data table. One external key table can only be associated with one virtual documents activity. Chapter 8. Advanced RealTime activities 203 Note: LEI will not prompt you with any errors when you create or activate multiple virtual documents activities that map multiple Domino forms to one external data table. However, you will risk getting unpredictable results when running the activities. Figure 8-3 graphically describes these limitations. Domino DB2 UDB a.nsf Table 1 External key table 1 Form 1 Virtual Documents activity 1 Form 2 b.nsf Table 2 Virtual Documents activity 2 External key table 2 Form 3 Form 4 Figure 8-3 Virtual documents and Domino forms mapping 8.3.3 Using virtual fields with virtual documents The ability to use virtual fields with virtual documents gives the best of both worlds. It eliminates the need of having to maintain key documents with virtual fields. It also addresses the limitations of virtual documents that only allows users to map to one external data table. When using virtual fields with virtual documents, be sure not to enable updates of the join keys. It is important to understand that using virtual fields with virtual documents does have some disadvantages. For example, virtual fields activity depends on the virtual documents to provide the key to fetch the rest of the data from the external data table. This implies that virtual documents activity must be started before the virtual fields. If the virtual fields activity starts first, an error will occur. In a production environment, you will typically schedule your Advanced RealTime activities. Currently, there is no way to specify that the virtual fields activity cannot start until the virtual documents activity is up and running. Therefore we recommend that you manually start the activity in the correct sequence instead of scheduling them. For a step-by-step example of using virtual fields with virtual documents, see 8.9, “Example 4: Using virtual fields with virtual documents” on page 231 for more details. 8.4 Virtual attachments Virtual attachments allow you to use Domino to add attachments to the external system database through a Domino application. File attachments will be stored in the external system rather than in your Domino application. 204 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server If you have attachments in Domino documents monitored by a virtual documents you cannot save an attachment unless it is virtualized. If you do not virtualize the attachments, they will not be saved. Note: If the field containing the attachment is a native Domino field (that is, not monitored by a virtual documents or virtual fields activity), you are not required to virtualize the attachment. You need to create the virtual attachments table in order to use this feature. The list of required and optional virtual attachment columns is shown in Table 8-3. Table 8-3 Virtual attachments columns Column Name Required or Optional Data Type and Size EIDBID Required CHARACTER(16) EIFILEID Required INTEGER EIFILESIZE Required INTEGER EIUNID Optional CHARACTER(32) EIFILENAME Optional VARCHAR(256) EICONTENTS Required BLOB(1GB)1 1 For purposes of performance enhancement, future versions of LEI (after 6.0.2) during DB2 UDB fetch may allocate enough memory to contain the largest size BLOB, even if the actual contents are much less. Therefore, when creating this table, you should limit this value to the maximum attachment size you actually need to support to avoid possible memory errors after upgrading. Refer to the LEI Activities and Users Guide for more details about these columns. Note: The virtual attachments table must be on the same external system and the same database and library as the external system data being accessed by the activity. The virtual attachments table cannot reside in a different external system or database than the one being used by the virtual fields activity. This is because the same connection document for both virtual fields and virtual attachments is used to access the external system. If you use a virtual documents and a virtual fields activity on the same form, enable virtual attachments only on the virtual documents activity. For a step-by-step example of using virtual attachments, see 8.10, “Example 5: Using virtual agents and virtual attachments” on page 237. 8.5 Virtual agents activity A virtual agents activity enables you to run an external stored procedure as an agent that you trigger from a Domino application. The virtual agents activity creates the Domino agent and adds it to the Actions pull-down menu. It works as if you are running a normal Domino agent from the Actions menu. The virtual agents activity can execute stored procedures with or without parameters. If the stored procedure requires parameters, you must select Domino documents from the view to run the agent against. These Domino documents must contain fields that are named exactly Chapter 8. Advanced RealTime activities 205 as the parameters in the external system stored procedure and must also have matching data types. Stored procedures that do not accept input parameters do not run against any specific document, they are created and specified as agents that Run on all documents in database. Procedures that do accept parameters are created as agents that Run on selected documents and require that at least one document be selected. All documents selected for a virtual agent are used as a source for input parameters for the agent and the input parameters for the external stored procedure are obtained from the correspondingly named fields in the target document. For a step-by-step example of using virtual agents, see 8.10, “Example 5: Using virtual agents and virtual attachments” on page 237. 8.6 Example 1: Using a virtual documents activity In this example we show using a virtual documents activity against a single DB2 UDB table on the iSeries server. This example requires the employee.nsf Domino database and EMPLOYEE table in DB2 UDB as discussed in Chapter 7, “Setting up the examples environment” on page 183. In this example, we demonstrate how you can update employee data in DB2 UDB using a Lotus Notes client. Figure 8-4 graphically describes this example. Perform the following steps to create the virtual document activity. Domino DB2 UDB employee.nsf EmpProfile form EMPLOYEE table Virtual Documents activity EMP_EXTERNAL External keys table Figure 8-4 Using a virtual documents activity with single DB2 UDB table For batch activities (covered in Chapter 9, “Batch activities” on page 255), neither end of the activity needs to be a Notes database. You could, for instance, replicate between a DB2 UDB database and Oracle. However, Advanced Realtime activities always has a Notes database and form as one end of the hookup. Therefore, it is not necessary to create a Connection to Notes document in the LEI Administrator database for Advanced Realtime activities. Instead, you just select the Domino database filepath and form name on the activity form. You must, however, create a Connection to DB2 document. 8.6.1 Create a DB2 connection document For this example we create a global connection document for any DB2 UDB tables in the specified database. In the other examples, we create specific connections for each table. 206 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server The benefit of creating a global connection document is you do not need to create connection documents for all tables you need to connect to and thus simplify the management of your connection documents. However, if you need more control over each connection, it is more advantageous to create separate connection documents. For example, if some tables are journaled and some are not, you have to create separate connection documents. Perform the following steps to create a global DB2 connection document: 1. From the LEI Administrator Action menu, click Create -> Connection -> DB2. 2. From the Connection to DB2 document, in the Connectivity section, enter the following values: – Name: This is any name you want to give to your connection document. For this example enter DB2 Connection. – Database: This is the name of the database that you want to connect to. For iSeries this is the RDB directory entry name. See 5.2.2, “Creating a local relational database directory entry” on page 105 for details. For our example we used as06. – User Name: The user name must be a valid OS/400 user profile. This user should have access to the DB2 UDB files you want to access. – Password: This field is the associated password for the OS/400 user profile that will be connecting to the database. The password will appear in clear text in the connection document but can be encrypted. In order to encrypt the password field, click the key icon, and choose the secret encryption key. For more information about creating secret encryption keys, see ‘Creating secret encryption keys’ in the Domino Designer help. – Data Journaling: Click Off. This radio button allows you to select if the DB2 UDB files that will be accessed by this connection document are journaled or not. You should check with the database administrator to see if the files are journaled and set this parameter accordingly. Note: The Data Journaling radio button does not turn journaling on or off on the DB2 UDB tables. The selection in the connection document should represent if journaling is on or off on the tables that you will access. If your database is journaled, you must set Data Journaling to On in the DB2 connection document. Be sure to verify data journaling because LEI will generate an error if this setting is not appropriately set. For more information about how to check on database journaling, refer to “Checking for journaling” on page 294. 3. In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 4. Leave the rest of the fields with the default values. You should have a DB2 connection document as shown in Figure 8-5. We will not specify any tables for this connection document so that we can reuse it later for any tables on the iSeries server. Chapter 8. Advanced RealTime activities 207 Figure 8-5 Global DB2 connection document 5. Click Save and Close button to finish. For more information about DB2 connection documents, refer to 6.1, “DB2 connection document” on page 154. 8.6.2 Create a virtual documents activity document You can create a virtual documents activity with or without the user assistant. In this example we use the user assistant. Perform the following steps: 1. From the LEI Administrator Action menu, click Create -> Activity -> Virtual Documents. 2. The dialog box shown in Figure 8-6 appears. Click OK. Note: Make sure the user assistant wizard is enabled by using the button in the Help frame of the LEI Administrator. 208 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 8-6 User assistant wizard for creating a virtual documents activity 3. You are now prompted to select your Domino database (Figure 8-7). Select employee.nsf from the list and click OK. Figure 8-7 Selecting the employee.nsf Domino database Chapter 8. Advanced RealTime activities 209 4. As shown in Figure 8-8, you are prompted to specify the metadata, which is a Domino form in this case. Select the EmpProfile form and click OK. Figure 8-8 Selecting the EmpProfile Domino form 5. You are now prompted to specify the connection document created earlier for DB2 in 8.6.1, “Create a DB2 connection document” on page 206. Select DB2 Connection from the list and click OK. See Figure 8-9. 210 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 8-9 Selecting the DB2 Connection document 6. You are prompted to specify the metadata, which is a DB2 UDB table in this case. Select EMPLIB.EMPLOYEE and click OK. See Figure 8-10. Chapter 8. Advanced RealTime activities 211 Figure 8-10 Selecting the EMPLIB.EMPLOYEE DB2 UDB table 7. The user assistant wizard will now present the Data Field Mapping window. Click the corresponding fields to map them and click OK. See Figure 8-11 for how to map these fields. 8. You are also prompted to provide a descriptive name for the activity. Enter Virtual Document for Employee and click OK. 9. Your virtual documents activity should be as shown in Figure 8-11. 212 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 8-11 Virtual documents activity document 10.Click OK when the user assistant window indicates that the configuration is complete. You will get the error message shown in Figure 8-12. Do not panic! This error is expected as described earlier in 8.1.2, “External system metadata for virtual documents activities” on page 197. Figure 8-12 Key table columns error 11.In order to fix this error, click the Use External Key Table radio button located under the Options tab, General Options sub- tab, Key Table Option field of the virtual documents activity document. 12.Provide a name for the key table in the Key Table Name field. This can be any descriptive name, for our example we use EMPLIB.EMP_EXTERNAL. 13.Enter EMPNO in the Key Field(s) field. Note: You must include the owner name for the key table. In our example, the owner name is EMPLIB. In addition, the owner name must be the same as the owner of the DB2 UDB table you are connecting to. 14.Click the Create External Key Table button to have LEI generate the external key table in DB2 UDB. Figure 8-13 shows the confirmation dialog box. Click OK. Chapter 8. Advanced RealTime activities 213 Figure 8-13 Create external key table dialog box 15.Click OK on the completion dialog box shown in Figure 8-14. Figure 8-14 Key table created successfully message 16.Your virtual documents activity document, Options tab, General Options sub-tab should look like what is shown in Figure 8-15. Figure 8-15 Virtual documents activity document, Options tab, General Options sub-tab 17.Leave the Max. Connections field at the default value of 2. 214 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Note: Setting the appropriate number of maximum connections is important for maximizing performance. More connections will improve performance when a very large number of users access documents simultaneously. However, you should not set more connections than what are necessary. Too many idle connections will have negative impact on performance since more memory will be needed to maintain these connections. 18.In the Scheduling section of the virtual documents activity document (Figure 8-16), click Custom as the Scheduling Option and have LEI run Monday through Friday from 4:00 AM - 8:00 PM. Typically, in a production environment, this option will work best. You can also choose the Scheduling Option of Auto Start so that if LEI goes down, this activity will automatically come back up when LEI is restarted. Manual scheduling should not be used in a production environment. If you turn virtual documents off, you must be sure that no person or process will be trying to use the Notes database during off hours. This includes scheduled Domino agents and replication with other Domino servers. Otherwise, you risk non-virtualized documents getting created while the activity is stopped; these do not get virtualized when the activity starts again. This can be corrected after the fact with LotusScript code, or by using cut and paste from a view to replace the non-virtual documents with new virtual documents. You can identify a document that failed virtualization by its Note ID, visible in the advanced tab of the document properties dialog. Virtual documents' Note IDs begin ‘NT7’ through ‘NTF’, non-virtual documents have IDs starting ‘NT0’ through ‘NT6’. Performance Tip: We recommend that you start the first time virtualization during off-peak hours because it could take significant resources. Figure 8-16 Virtual documents activity document, Scheduling section 19.In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 20.Leave the rest of the fields with the default values and click Save and Close to finish. 8.6.3 Testing the virtual documents activity Perform the following steps to test the virtual documents activity: 1. Make sure the virtual documents activity is started (the current status is Active) in the LEI Administrator. 2. Open the Domino database, employee.nsf, on your Lotus Notes client. 3. Go to EmpProfile\By Department view. You should see documents in the view. These documents are virtual documents retrieved from the DB2 UDB database on the iSeries server. Chapter 8. Advanced RealTime activities 215 It may take a couple of minutes for LEI to virtualize the rows in the DB2 UDB table. Also, if you have opened this database previously, you may need to use Shift+F9 to get Notes to display the newly virtualized documents. 4. Edit one of the documents from your Lotus Notes client. 5. Once your changes have been saved, verify that the DB2 UDB table EMPLIB.EMPLOYEE has been updated accordingly. For more details about how to do this using iSeries Navigator, refer to Appendix B, “Using iSeries Navigator to access DB2 UDB” on page 285. Note: If this or any other LEI activity seems not to be working, whether or not you are getting any error messages on the console, open the LEI Administrator, highlight the activity document in the view, and click the Current Activity Execution Log button to check for logged error messages. 8.7 Example 2: Using virtual documents with a DB2 UDB view This example requires the employee.nsf Domino database and EMP_DEPT view in DB2 UDB as discussed in Chapter 7, “Setting up the examples environment” on page 183. In this example we demonstrate how you can read employees and their corresponding department data in DB2 UDB using a Lotus Notes client. Figure 8-17 graphically describes this example. Domino DB2 UDB employee.nsf EmpProfileDB2View form EMP_DEPT view Virtual Documents activity EXTERNAL_VIEW External keys table Figure 8-17 Using virtual documents with a DB2 UDB view There is a limitation with using a virtual documents activity against a DB2 UDB view to get to data from multiple DB2 UDB tables using a join. In this example the EMP_DEPT view is created by joining the EMPLOYEE and DEPARTMENT tables. As described in IBM eServer iSeries Information Center Version 5 Release 2 (V5R2) at: http://publib.boulder.ibm.com/iseries/v5r2/ic2924/index.htm?info/rzahf/rzahfli0.htm A DB2 UDB view is read-only if it includes any of the following: The first FROM clause identifies more than one table (join). The first FROM clause identifies a read-only view. The first FROM clause identifies a user-defined table function. The first SELECT clause contains any of the SQL column functions (SUM, MAX, MIN, AVG, COUNT, STDDEV, COUNT_BIG, or VAR). The first SELECT clause specifies the keyword DISTINCT. 216 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server The outer subselect contains a GROUP BY or HAVING clause. The outer subselect contains a UNION clause. A subquery where the base object of the outer-most subselect and a table of a subquery are the same table. Consequently, in this example you can only read the information available in EMP_DEPT view through the Domino client. You are not able to add a new record, update, or delete existing records. Despite the limitations, this feature of LEI which allows you to set up an Advanced RealTime activity with a DB2 UDB view is still a very powerful feature. For example, if you have a very large DB2 UDB table with 50 columns, but you only need a few columns out of the table. You can create a DB2 UDB view containing a subset of the table. Then you can set up a virtual documents activity against the DB2 UDB view to maintain a subset of that table. This will tremendously boost up performance compared to mapping to the entire DB2 UDB table. Another example with a DB2 UDB view created using a join. If you are dealing with very large tables, you will have a significant improvement in performance if you use a view for read operations with a virtual documents activity. You can then deal with the limitations by setting up a virtual fields activity to handle the insert, update, and delete operations to the respective tables. In this scenario you will need to have separate Domino forms. In this example you use a Domino form called EmpProfileDB2View for the virtual documents activity that connects to the DB2 UDB view EMP_Dept. You cannot use the EmpProfileDB2View form to set up the virtual fields activity documents to handle the inserts, updates, and deletes. 8.7.1 Create a DB2 connection document to EMPLIB.EMP_DEPT Perform the following steps to create a DB2 connection document to EMPIB.EMP_DEPT: 1. From the LEI Administrator Action menu, click Create -> Connection -> DB2. 2. From the Connection to DB2 document, in the Connectivity section, enter the following values: – Name: This is any name you want to give to your connection document. For this example enter DB2 Connection to EMPLIB.EMP_DEPT. – Database: This is the name of the database that you want to connect to. For iSeries this is the RDB directory entry name. See 5.2.2, “Creating a local relational database directory entry” on page 105 for details. For our example we used as06. – User Name: The user name must be a valid OS/400 user profile. This user should have access to the DB2 UDB files you want to access. – Password: This field is the associated password for the OS/400 user profile that will be connecting to the database. The password will appear in clear text in the connection document but can be encrypted. In order to encrypt the password field, click the key icon, and choose the secret encryption key. For more information about creating secret encryption keys, see ‘Creating secret encryption keys’ in the Domino Designer help. – Data Journaling: Click Off. This radio button allows you to select if the DB2 UDB files that will be accessed by this connection document are journaled or not. You should check with the database administrator to see if the files are journaled and set this parameter accordingly. Chapter 8. Advanced RealTime activities 217 Note: The Data Journaling radio button does not turn journaling on or off on the DB2 UDB tables. The selection in the connection document should represent if journaling is on or off on the tables that you will access. If your database is journaled, you must set Data Journaling to On in the connection document. Be sure to verify data journaling because LEI will generate an error if this setting is not appropriately set. For more information about how to check on database journaling, refer to “Checking for journaling” on page 294. 3. Under the Transaction Options tab, click View for the Selection Type. 4. You should have a DB2 connection document as shown in Figure 8-18. Figure 8-18 DB2 connection document - Connectivity section 5. In View Selection section, specify the owner as EMPLIB and select EMP_DEPT as the name. The Columns field will be automatically populated as shown in Figure 8-19. Figure 8-19 DB2 connection document - View Selection section 218 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 6. In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator grows and becomes harder to manage. 7. Leave the rest of the fields with the default and click Save and Close to finish. Note: You can also create a connection document via copy and paste of an existing connection document. You do this from the Connections view. You will be asked to enter a unique name for the new connection and then you can edit the new connection document to make any necessary changes. For more information about DB2 connection documents, refer to 6.1, “DB2 connection document” on page 154. 8.7.2 Create a virtual documents activity document You can create a virtual documents activity with or without the user assistant. In this example we use the user assistant. Perform the following steps: 1. From the LEI Administrator Action menu, click Create -> Activity -> Virtual Documents. 2. The dialogbox shown in Figure 8-20 appears. Click OK. Figure 8-20 User assistant wizard for creating a virtual documents activity 3. You are now prompted to select your Domino database (Figure 8-21). Select employee.nsf from the list and click OK. Chapter 8. Advanced RealTime activities 219 Figure 8-21 Selecting the employee.nsf Domino database 4. As shown in Figure 8-22, you are prompted to specify the metadata, which is a Domino form in this case. Select the EmpProfileDB2View form and click OK. Figure 8-22 Selecting the EMPProfileDB2View Domino form 220 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 5. You are now prompted to specify the connection document created earlier for DB2 in 8.7.1, “Create a DB2 connection document to EMPLIB.EMP_DEPT” on page 217. Select DB2 Connection to EMPLIB.EMP_DEPT from the list and click OK. See Figure 8-23. Figure 8-23 Selecting the DB2 Connection to EMPLIB.EMP_DEPT document 6. The user assistant wizard will now present the Data Field Mapping window. Click the corresponding fields to map them and click OK. See Figure 8-24 for how to map these fields. 7. You are also prompted to provide a descriptive name for the activity. Enter Virtual Document to DB2 View and click OK. 8. Your virtual documents activity should be as shown in Figure 8-24. Chapter 8. Advanced RealTime activities 221 Figure 8-24 Virtual documents activity to a DB2 UDB view 9. Click OK when the user assistant window indicates that the configuration is complete. You will get the error message shown in Figure 8-12 on page 213. Do not panic! This error is expected as described earlier in 8.1.2, “External system metadata for virtual documents activities” on page 197. 10.In order to fix this error, click the Use External Key Table radio button located under the Options tab, General Options sub- tab, Key Table Option field of the virtual documents activity document. 11.Provide a name for the key table in the Key Table Name field. This can be any descriptive name, for our example we use EMPLIB.EXTERNAL_VIEW. 12.Enter both DEPTNO and EMPNO in the Key Field(s) field. 13.Click the Create External Key Table button to have LEI generate the external key table in DB2 UDB. 14.Your virtual documents activity document, Options tab, General Options sub-tab should look like what is shown in Figure 8-25. 222 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 8-25 Virtual documents activity document, Options tab, General Options sub-tab 15.Leave the Max. Connections field as the default value of 2. Note: Setting the appropriate number of maximum connections is important for maximizing performance. More connections will improve performance when a very large number of users access documents simultaneously. However, you should not set more connections than what are necessary. Too many idle connections will have negative impact on performance since more memory will be needed to maintain these connections. 16.In the Scheduling section of the virtual documents activity document, click Custom as the Scheduling Option and have LEI run Monday through Friday from 4:00 AM - 8:00 PM. Typically, in a production environment, this option will work best. You can also choose the Scheduling Option of Auto Start so that if LEI goes down, this activity will automatically come back up when LEI is restarted. Manual scheduling should not be used in a production environment. Performance Tip: We recommend that you start the first time virtualization during off-peak hours because it could take significant resources. 17.In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator grows and becomes harder to manage. 18.Leave the rest of the fields with the default values and click Save and Close to finish. 8.7.3 Testing the virtual documents activity Perform the following steps to test the virtual documents activity: 1. Make sure the virtual documents activity is started (the current status is Active) in the LEI Administrator. Chapter 8. Advanced RealTime activities 223 2. Open the Domino database employee.nsf on your Lotus Notes client and go to EmpProfileDB2View\By Department view. You should see documents in the view. These documents are virtual documents retrieved from the DB2 UDB view. 3. Since the DB2 UDB view is read-only, you will get an error if you attempt to update any documents from your Lotus Notes client. 8.8 Example 3: Using virtual fields with multiple DB2 tables This example requires the employee.nsf Domino database and EMPLIB.EMPLOYEE and EMPLIB.DEPARTMENT tables in DB2 UDB as discussed in Chapter 7, “Setting up the examples environment” on page 183. Here we demonstrate how you can read, create, update, and delete employee records from the Lotus Notes client. Figure 8-26 graphically describes this example. Domino DB2 UDB employee.nsf Virtual Felds activity EMPLOYEE table Virtual Fields activity DEPARTMENT table EmpProfileVirtualFields form Figure 8-26 Using virtual fields with multiple DB2 UDB2 tables In this example we also show how to work around the limitation of virtual documents activity which can only monitor one DB2 UDB table. It also addresses the limitation of using virtual documents activity with DB2 UDB views built by joining multiple tables which only gives you read access. Essentially, 8.9, “Example 4: Using virtual fields with virtual documents” on page 231 and this example accomplish a similar result. Our goal in providing you both examples is to demonstrate that there are multiple solutions to this implementation. One difference is that EMPNO field is retained in the key document in this example, but not in 8.9, “Example 4: Using virtual fields with virtual documents” on page 231. 8.8.1 Create a DB2 connection document to EMPLIB.EMPLOYEE Perform the following steps to create a DB2 connection document to EMPLIB.EMPLOYEE: 1. From the LEI Administrator Action menu, click Create -> Connection -> DB2. 2. From the Connection to DB2 document, in the Connectivity section, enter the following values: – Name: This is any name you want to give to your connection document. For this example enter: DB2 Connection to EMPLIB.EMPLOYEE. 224 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server – Database: This is the name of the database that you want to connect to. For iSeries this is the RDB directory entry name. See 5.2.2, “Creating a local relational database directory entry” on page 105 for details. For our example we used as06. – User Name: The user name must be a valid OS/400 user profile. This user should have access to the DB2 UDB files you want to access. – Password: This field is the associated password for the OS/400 user profile that will be connecting to the database. The password will appear in clear text in the connection document but can be encrypted. In order to encrypt the password field, click the key icon, and choose the secret encryption key. For more information about creating secret encryption keys, see ‘Creating secret encryption keys’ in the Domino Designer help. – Data Journaling: Click Off. This radio button allows you to select if the DB2 UDB files that will be accessed by this connection document are journaled or not. You should check with the database administrator to see if the files are journaled and set this parameter accordingly. Note: The Data Journaling radio button does not turn journaling on or off on the DB2 UDB tables. The selection in the connection document should represent if journaling is on or off on the tables that you will access. If your database is journaled, you must set Data Journaling to On in the connection document. Be sure to verify data journaling, because LEI will generate an error if this setting is not appropriately set. For more information about how to check on database journaling, refer to “Checking for journaling” on page 294. 3. Under the Table Selection section, specify EMPLIB as the owner and EMPLOYEE as the table name. The columns will be automatically populated. See Figure 8-27. Chapter 8. Advanced RealTime activities 225 Figure 8-27 DB connection document to EMPLIB.EMPLOYEE 4. In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 5. Leave the rest of the fields with the default and click Save and Close to finish. For more information about DB2 connection documents, refer to 6.1, “DB2 connection document” on page 154. 8.8.2 Create a DB2 connection document to EMPLIB.DEPARTMENT Perform the following steps to create a DB2 connection document to EMPLIB.DEPARTMENT: 1. From the LEI Administrator Action menu, click Create -> Connection -> DB2. 2. From the Connection to DB2 document, in the Connectivity section, enter the following values: – Name: This is any name you want to give to your connection document. For this example enter DB2 Connection to EMPLIB.DEPARTMENT. – Database: This is the name of the database that you want to connect to. For iSeries this is the RDB directory entry name. See 5.2.2, “Creating a local relational database directory entry” on page 105 for details. For our example use as06. – User Name: The user name must be a valid OS/400 user profile. This user should have access to the DB2 UDB files you want to access. 226 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server – Password: This field is the associated password for the OS/400 user profile that will be connecting to the database. The password will appear in clear text in the connection document but can be encrypted. In order to encrypt the password field, click the key icon, and choose the secret encryption key. For more information about creating secret encryption keys, see ‘Creating secret encryption keys’ in the Domino Designer help. – Data Journaling: Click Off. This radio button allows you to select if the DB2 UDB files that will be accessed by this connection document are journaled or not. You should check with the database administrator to see if the files are journaled and set this parameter accordingly. Note: The Data Journaling radio button does not turn journaling on or off on the DB2 UDB tables. The selection in the connection document should represent if journaling is on or off on the tables that you will access. If your database is journaled, you must set Data Journaling to On in the connection document. Be sure to verify data journaling because LEI will generate an error if this setting is not appropriately set. For more information about how to check on database journaling, refer to “Checking for journaling” on page 294. 3. Under the Table Selection section, select EMPLIB as the owner and DEPARTMENT as the table name. The columns will be automatically populated. See Figure 8-28. Figure 8-28 DB2 connection document to EMPLIB.DEPARTMENT 4. In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. Chapter 8. Advanced RealTime activities 227 5. Leave the rest of the fields with the default and click Save and Close to finish. For more information about DB2 connection documents, refer to 6.1, “DB2 connection document” on page 154. 8.8.3 Create a virtual fields activity document to EMPLIB.EMPLOYEE You can create a virtual fields activity document with or without the user assistant wizard. In this example we use the user assistant. Perform the following steps: 1. From the LEI Administrator Action menu, click Create -> Activity -> Virtual Fields. 2. Click OK on the first user assistant window. 3. You are now prompted to select your Domino database. Select employee.nsf from the list and click OK. 4. You are prompted to specify the metadata, which is a Domino form in this case. Select the EmpProfileVirtualFields form and click OK. 5. You are now prompted to specify the connection document created earlier for DB2 in 8.8.1, “Create a DB2 connection document to EMPLIB.EMPLOYEE” on page 224. Select DB2 Connection to EMPLIB.EMPLOYEE from the list and click OK. 6. Now the user assistant will bring up the key and data field mapping window. For keys, map EmpNum to EMPNO. For data fields, click the corresponding fields to map them (see Figure 8-29) and click OK. 7. You will be prompted to specify the document events to monitor. Select all events (create, open, update, delete) and click OK. 8. You are also prompted to provide a descriptive name for the activity. Enter Virtual Fields for EMPLIB.EMPLOYEE and click OK. 9. Your virtual fields document should be as shown in Figure 8-29. Figure 8-29 Virtual fields document to EMPLIB.EMPLOYEE 228 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 10.Under the Options tab, General Options sub-tab, set the Monitor Order to 1. When multiple Advanced Realtime activities are running on the same form, the Monitor Order lets you control which activity is applied first. This lets you use one activity to fetch a field that another activity can then use as a key to find additional data (as is the case with the DEPTNO field in this example). 11.For scheduling, set the scheduling option to Custom, running Monday - Friday between 7:00 AM - 7:00 PM. 12.In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 13.Leave the rest of the fields with the default values and click Save and Close to finish. 8.8.4 Generate key documents Perform the following steps to generate the key documents: 1. Open the virtual fields activity document you just finish creating in the previous step (Virtual Fields for EMPLIB.EMPLOYEE). You can do so by double-clicking on the activity document from the view in the LEI Administrator. 2. Click the Initialize Keys button on the action bar of the virtual fields activity document to generate the key documents. The dialog box shown in Figure 8-30is displayed. Figure 8-30 Initialize keys dialog box 3. Click Yes and a message box will be prompted upon completion (see Figure 8-31). Click OK. Figure 8-31 Completion dialog box for key initialization 4. You can now close the virtual fields activity document using the ESC key. 8.8.5 Create a virtual fields activity document to EMPLIB.DEPARTMENT You can create a virtual fields activity document with or without the user assistant wizard. In this example we use the user assistant. Perform the following steps: 1. From the LEI Administrator Action menu, click Create -> Activity -> Virtual Fields. 2. Click OK on the first user assistant window. Chapter 8. Advanced RealTime activities 229 3. You are now prompted to select your Domino database. Select employee.nsf from the list and click OK. 4. You are prompted to specify the metadata, which is a Domino form in this case. Select the EmpProfileVirtualFields form and click OK. 5. You are now prompted to specify the connection document created earlier for DB2. Select DB2 Connection to EMPLIB.DEPARTMENT from the list and click OK. 6. Now the user assistant will bring up the key and data field mapping window. For keys, map DeptNum to DEPTNO. For data fields, click the corresponding fields to map them (see Figure 8-32) and click OK. Note: Notice this field you are using as a key is not stored in Notes but was actually fetched by the previous Virtual Fields activity. 7. You will be prompted to specify the document events to monitor. Select only the Open event and click OK. The reason we select only the Open event here, is that we want the data loaded from the DEPARTMENT table to be read-only on this form. When viewing an Employee Profile, we do not let the Notes user edit information about the employee's department (they might edit the DEPTNO field to move them to a different department, but this is not the place to change the name of their department). Likewise, if an employee profile is deleted, we don't also want to delete the Department record whose key is DEPTNO. 8. You are also prompted to provide a descriptive name for the activity. Enter Virtual Fields for EMPLIB.DEPARTMET and click OK. 9. Your virtual fields activity should be as shown in Figure 8-32. Figure 8-32 Virtual fields document to EMPLIB.DEPTARTMENT 10.Under the Options tab, General Options sub-tab, set the Monitor Order to 2. 11.For scheduling, set the scheduling option to Custom, running Monday - Friday between 7:00 AM - 7:00 PM. 230 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 12.n the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator grows and becomes harder to manage. 13.Leave the rest of the fields with the default values and click Save and Close to finish. 8.8.6 Testing the virtual fields activities Perform the following steps to test the virtual fields activities: 1. Make sure both virtual fields activities are started (the current status are Active) in the LEI Administrator. 2. Open the Domino database, employee.nsf, on your Lotus Notes client and go to the EmpProfileVirtualFields\By Employee# view. You should see documents in the view. These documents are the key documents created in 8.8.4, “Generate key documents” on page 229. 3. Edit one of the documents from your Lotus Notes client. The Department # must be populated in the document. If that field is not populated, you will be prompted with an error message. Note: Department # is a required field because it is used as a key for the virtual fields activity to retrieve the department information from EMPLIB.DEPARTMENT table. 4. Once your changes have been saved, verify that the DB2 UDB table EMPLIB.EMPLOYEE has been updated accordingly. Refer to Appendix B, “Using iSeries Navigator to access DB2 UDB” on page 285 for more information about using iSeries Navigator to do this. 8.9 Example 4: Using virtual fields with virtual documents This example requires the employee.nsf Domino database and the EMPLIB.EMPLOYEE2 and EMPLIB.DEPARTMENT tables in DB2 UDB as discussed in Chapter 7, “Setting up the examples environment” on page 183. In the example we demonstrate how you can read, create, update, and delete employee records from the Lotus Notes client. Figure 8-33 graphically describes this example. DB2 UDB Dom ino em ployee.nsf Em pProfileVirtualDocsAndFields form EM PLOYEE2 table Virtual D ocuments activity Virtual Felds activity EM PLOYEE_EXTERNAL External keys table DEPARTM ENT table Figure 8-33 Using virtual fields with virtual documents Chapter 8. Advanced RealTime activities 231 In this example we do not enable the create, update, and delete of the department data in DB2 UDB using the same form as the form used to update employees data through a Lotus Notes client. This is to enforce an application design to avoid problems that will arise if we enable all document events for both virtual documents and virtual fields activities. For example, if both virtual documents and virtual fields activity documents have all documents events enabled, you could encounter a problem when you transfer an employee from one department to the other. When you change the department for one person from 015 to 035, the WORKDEPT field in EMPLIB.EMPLOYEE2 table for that person is appropriately changed. Inadvertently, the DEPTNO field in EMPLIB.DEPARTMENT table for 015 will also be changed to 035. This is a problem because now we no longer have department 015. Another potential problem could be if an employee is terminated by deleting the virtual document in your Lotus Notes client. In addition to the proper deletion of the employee from the EMPLIB.EMPLOYEE2 table, the department entry of the terminated employee will also be erroneously deleted in the EMPLIB.DEPARTMENT table. Consequently, if you try to open a record of an employee who happens to have the same department of the employee you just deleted, an error will occur. Essentially, 8.8, “Example 3: Using virtual fields with multiple DB2 tables” on page 224 and this example accomplish the similar result. Our goal in providing you both examples is to demonstrate that there are multiple solutions to this implementation. One difference is that EMPNO is retained in the key document in 8.8, “Example 3: Using virtual fields with multiple DB2 tables” on page 224 but not in this example. Note: DB2 UDB table EMPLIB.EMPLOYEE is identical to EMPLIB.EMPLOYEE2. We made a copy of EMPLIB.EMPLOYEE database because of the virtual documents limitation described in Figure 8-3 on page 204. EMPLIB.EMPLOYEE table is already used in Example 1: Using a virtual documents activity. 8.9.1 Create a DB2 connection document to EMPLIB.EMPLOYEE2 Perform the following steps to create a DB2 connection document to EMPLIB.EMPLOYEE2: 1. From the LEI Administrator Action menu, click Create -> Connection -> DB2. 2. From the Connection to DB2 document, in the Connectivity section, enter the following values: – Name: This is any name you want to give to your connection document. For this example enter DB2 Connection to EMPLIB.EMPLOYEE2. – Database: This is the name of the database that you want to connect to. For iSeries this is the RDB directory entry name. See 5.2.2, “Creating a local relational database directory entry” on page 105 for details. For our example we used as06. – User Name: The user name must be a valid OS/400 user profile. This user should have access to the DB2 UDB files you want to access. – Password: This field is the associated password for the OS/400 user profile that will be connecting to the database. The password will appear in clear text in the connection document but can be encrypted. In order to encrypt the password field, click the key icon, and choose the secret encryption key. For more information about creating secret encryption keys, see ‘Creating secret encryption keys’ in the Domino Designer help. – Data Journaling: Click Off. This radio button allows you to select if the DB2 UDB files that will be accessed by this connection document are journaled or not. You should check with the database administrator to see if the files are journaled and set this parameter accordingly. 232 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Note: The Data Journaling radio button does not turn journaling on or off on the DB2 UDB tables. The selection in the connection document should represent if journaling is on or off on the tables that you will access. If your database is journaled, you must set Data Journaling to On in the connection document. Be sure to verify data journaling because LEI will generate an error if this setting is not appropriately set. For more information about how to check on database journaling, refer to “Checking for journaling” on page 294. 3. Under the Table Selection section, specify EMPLIB as the owner and EMPLOYEE2 as the table name. The columns will be automatically populated. See Figure 8-34. Figure 8-34 DB2 connection document to EMPLIB.EMPLOYEE2 4. In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 5. Leave the rest of the fields with the default and click Save and Close to finish. For more information about DB2 connection documents, refer to 6.1, “DB2 connection document” on page 154. Chapter 8. Advanced RealTime activities 233 8.9.2 Create a DB2 connection document to EMPLIB.DEPARTMENT If you do not have the DB2 connection document called DB2 Connection to EMPLIB.DEPARTMENT follow the instructions in 8.8.2, “Create a DB2 connection document to EMPLIB.DEPARTMENT” on page 226. Otherwise, you can skip this step. 8.9.3 Create a virtual documents activity You can create a virtual documents activity with or without the user assistant. In this example, we use the user assistant. Perform the following steps: 1. From the LEI Administrator Action menu, click Create -> Activity -> Virtual Documents 2. Click OK on the first user assistant window. 3. You are now prompted to select your Domino database. Select employee.nsf from the list and click OK. 4. You are prompted to specify the metadata, which is a Domino form in this case. Select the EmpProfileVirtualDocAndFields form and click OK. 5. You are now prompted to specify the connection document created earlier for DB2 in 8.9.1, “Create a DB2 connection document to EMPLIB.EMPLOYEE2” on page 232. Select DB2 Connection to EMPLIB.EMPLOYEE2 from the list and click OK. 6. Now the user assistant will bring up the key and data field mapping window. Click the corresponding fields to map them (see Figure 8-35) and click OK. 7. You are also prompted to provide a descriptive name for the activity. Enter Virtual Documents to Combine with Virtual Fields and click OK. 8. Your virtual documents activity should be as shown in Figure 8-35. Figure 8-35 Virtual documents activity to EMPLIB.EMPLOYEE2 9. Click OK when the user assistant window indicates that the configuration is complete. You will get an error message (see Figure 8-12 on page 213). This error is expected as described earlier in 8.1.2, “External system metadata for virtual documents activities” on page 197. 234 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 10.In order to fix this error, click the Use External Key Table radio button located under the Options tab, General Options sub- tab, Key Table Option field of the virtual documents activity document. 11.Provide a name for the key table in the Key Table Name field. This can be any descriptive name, for our example we use EMPLIB.EMPLOYEE_EXTERNAL. 12.Enter EMPNO in the Key Field(s) field. 13.Click the Create External Key Table button to have LEI generate the external key table in DB2 UDB. 14.Your virtual documents activity document, Options tab, General Options sub-tab should look like what is shown in Figure 8-36. Figure 8-36 Virtual documents activity document, Options tab, General Options sub-tab 15.Leave the Max. Connections field as the default value of 2. Note: Setting the appropriate number of maximum connections is important for maximizing performance. More connections will improve performance when a very large number of users access documents simultaneously. However, you should not set more connections than what are necessary. Too many idle connections will have negative impact on performance since more memory will be needed to maintain these connections. 16.In the Scheduling section of the virtual documents activity document, select Custom as the Scheduling Option and have LEI run Monday through Friday from 7:00 AM - 7:00 PM. Chapter 8. Advanced RealTime activities 235 Typically, in a production environment, this option will work best. You can also choose the Scheduling Option of Auto Start so that if LEI goes down, this activity will automatically come back up when LEI is restarted. Manual scheduling should not be used in a production environment. Performance Tip: We recommend that you start the first time virtualization during off-peak hours because it could take significant resources. 17.In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator grows and becomes harder to manage. 18.Leave the rest of the fields with the default values and click Save and Close to finish. 8.9.4 Create a virtual fields activity You can create a virtual fields activity document with or without the user assistant wizard. In this example we use the user assistant. Perform the following steps: 1. From the LEI Administrator Action menu, click Create -> Activity -> Virtual Fields. 2. Click OK on the first user assistant window. 3. You are now prompted to select your Domino database. Select employee.nsf from the list and click OK. 4. You are prompted to specify the metadata, which is a Domino form in this case. Select the EmpProfileVirtualDocAndFields form and click OK. 5. You are now prompted to specify the connection document created earlier for DB2 in 8.8.2, “Create a DB2 connection document to EMPLIB.DEPARTMENT” on page 226. Select DB2 Connection to EMPLIB.DEPARTMENT from the list and click OK. 6. Now the user assistant displays the key and data field mapping window. For keys, map DeptNum to DEPTNO. For data fields, click the corresponding fields to map them (see Figure 8-37) and click OK. 7. You will be prompted to specify the document events to monitor. Select only the Open event and click OK. Note: If you select all events (create, open, update, delete), by default, you cannot edit the department of an employee. Consequently, you will not be able to transfer an employee from one department to another. In this example, the values in the EMPLIB.DEPARTMENT table should be maintained using a separate Domino form (we will not demonstrate the department maintenance in this example). 8. You are also prompted to provide a descriptive name for the activity. Enter Virtual Fields to Combine with Virtual Documents and click OK. 9. Your virtual fields activity document should be as shown in Figure 8-37. 236 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 8-37 Virtual fields activity to EMPLIB.DEPARTMENT 10.For scheduling, set the scheduling option to Custom, running Monday - Friday between 7:30 AM - 7:00 PM. 11.n the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 12.Leave the rest of the fields with the default values and click Save and Close to finish. 8.9.5 Testing the activities Perform the following steps to test the virtual documents and virtual fields activities: 1. Make sure the virtual documents activity is started first (the current status is Active). Then verify that the virtual fields activity is started. 2. Open the Domino database, employee.nsf, on your Lotus Notes client and go to the EmpProfileVirtualDocAndFields\By Employee# view. You should see documents in the view. These documents are virtual documents retrieved from the DB2 UDB database. 3. Edit one of the documents from your Lotus Notes client. Note: Department # is a required field because it is used as a key for the virtual fields activity to retrieve the department information. 4. Once your changes have been saved, verify the DB2 UDB table EMPLIB.EMPLOYEE2 has been updated accordingly. Refer to Appendix B, “Using iSeries Navigator to access DB2 UDB” on page 285 for more information about using iSeries Navigator to do this. 8.10 Example 5: Using virtual agents and virtual attachments This example requires the AutoBodyDemo.nsf Domino database and the AUTOBODY.AUTOBODY_EST and AUTOBODY.AUTOBODY_DAMAGE tables in DB2 UDB Chapter 8. Advanced RealTime activities 237 and the AUTOBODY.DAMAGETOT stored procedure as discussed in Chapter 7, “Setting up the examples environment” on page 183. Figure 8-38 graphically describes this example. DB2 UDB D om ino A UT O B O D Y_E S T table A utoBodyD em o.nsf AU TO BO D Y_EST_ATTAC H A ttachm ent table V irtClaim E stim ate form Virtual Documents activity AU TO BO DY _EST_KEY E xternal keys table Virtual Fields activity AU TO BO D Y _D AM AG E table Virtual Agents activ ity D A MA G E TO T stored procedure Figure 8-38 Using virtual agents and virtual attachments Example 8-1 lists the stored procedure used in this example. Example 8-1 AUTOBODY.DAMAGETOT stored procedure P1 : BEGIN DECLARE TEMP_ESTIMATEID INTEGER ; SET TEMP_ESTIMATEID = ESTIMATEID ; UPDATE AUTOBODY . AUTOBODY_EST SET TOTAL = ( SUBTOTQUANT * SUBTOTPART ) + ( ( SUBTOTLABOR + SUBTOTPAINT ) * 45 ) WHERE ESTIMATEID = TEMP_ESTIMATEID ; END P1 This example demonstrates how you can use a combination of virtual fields and virtual documents activities to display data from multiple DB2 UDB tables in one Domino form. It also demonstrates how to handle multi-value data in virtual fields, how to use virtual attachments, and how to use virtual agents. Multi-value data allows a single document in a Domino database to relate to multiple records in the external system. For batch activities (covered in Chapter 9, “Batch activities” on page 257), neither end of the activity needs to be a Notes database. You could, for instance, replicate between a DB2 UDB database and Oracle. However, Advanced Realtime activities always has a Notes database and form as one end of the hookup. Therefore, it is not necessary to create a Connection to Notes document in the LEI Administrator database for Advanced Realtime activities. Instead, you just select the Domino database filepath and form name on the activity form. You must, however, need a Connection to DB2 document. 8.10.1 Create a DB2 connection document to AUTOBODY.AUTOBODY_EST Perform the following steps to create a DB2 connection document to AUTOBODY.AUTOBODY_EST: 1. From the LEI Administrator Action menu, click Create -> Connection -> DB2. 238 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 2. From the Connection to DB2 document, in the Connectivity section, enter the following values: – Name: This is any name you want to give to your connection document. For this example enter DB2 Connection to AUTOBODY.AUTOBODY_EST. – Database: This is the name of the database that you want to connect to. For iSeries this is the RDB directory entry name. See 5.2.2, “Creating a local relational database directory entry” on page 105 for details. For our example we used as06. – User Name: The user name must be a valid OS/400 user profile. This user should have access to the DB2 UDB files you want to access. – Password: This field is the associated password for the OS/400 user profile that will be connecting to the database. The password will appear in clear text in the connection document but can be encrypted. In order to encrypt the password field, click the key icon, and choose the secret encryption key. For more information about creating secret encryption keys, see ‘Creating secret encryption keys’ in the Domino Designer help. – Data Journaling: Click Off. This radio button allows you to select if the DB2 UDB files that will be accessed by this connection document are journaled or not. You should check with the database administrator to see if the files are journaled and set this parameter accordingly. Note: The Data Journaling radio button does not turn journaling on or off on the DB2 UDB tables. The selection in the connection document should represent if journaling is on or off on the tables that you will access. If your database is journaled, you must set Data Journaling to On in the connection document. Be sure to verify data journaling because LEI will generate an error if this setting is not appropriately set. For more information about how to check on database journaling, refer to “Checking for journaling” on page 294. 3. Under the Table Selection section, specify AUTOBODY as the owner and AUTOBODY_EST as the table name. The columns will be automatically populated. See Figure 8-39. Chapter 8. Advanced RealTime activities 239 Figure 8-39 DB2 connection document to AUTOBODY.AUTOBODY_EST 4. In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 5. Leave the rest of the fields with the default and click Save and Close to finish. For more information about DB2 connection documents, refer to 6.1, “DB2 connection document” on page 154. 8.10.2 Create a DB2 connection document to AUTOBODY.AUTOBODY_DAMAGE Perform the following steps to create a DB2 connection document to AUTOBODY.AUTOBODY_DAMAGE: 1. From the LEI Administrator Action menu, click Create -> Connection -> DB2. 2. From the Connection to DB2 document, in the Connectivity section, enter the following values: – Name: This is any name you want to give to your connection document. For this example enter DB2 Connection to AUTOBODY.AUTOBODY_DAMAGE. – Database: This is the name of the database that you want to connect to. For iSeries this is the RDB directory entry name. See 5.2.2, “Creating a local relational database directory entry” on page 105 for details. For our example we use as06. – User Name: The user name must be a valid OS/400 user profile. This user should have access to the DB2 UDB files you want to access. 240 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server – Password: This field is the associated password for the OS/400 user profile that will be connecting to the database. The password will appear in clear text in the connection document but can be encrypted. In order to encrypt the password field, click the key icon, and choose the secret encryption key. For more information about creating secret encryption keys, see ‘Creating secret encryption keys’ in the Domino Designer help. – Data Journaling: Click Off. This radio button allows you to select if the DB2 UDB files that will be accessed by this connection document are journaled or not. You should check with the database administrator to see if the files are journaled and set this parameter accordingly. Note: The Data Journaling radio button does not turn journaling on or off on the DB2 UDB tables. The selection in the connection document should represent if journaling is on or off on the tables that you will access. If your database is journaled, you must set Data Journaling to On in the Connection document. Be sure to verify data journaling because LEI will generate an error if this setting is not appropriately set. For more information about how to check on database journaling, refer to “Checking for journaling” on page 294. 3. Under the Table Selection section, specify AUTOBODY as the owner and AUTOBODY_DAMAGE as the table name. The columns will be automatically populated. See Figure 8-40. Figure 8-40 DB2 connection document to AUTOBODY.AUTOBODY_DAMAGE Chapter 8. Advanced RealTime activities 241 4. In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 5. Leave the rest of the fields with the default and click Save and Close to finish. For more information about DB2 connection documents, refer to 6.1, “DB2 connection document” on page 154. 8.10.3 Create a DB2 connection document to AUTOBODY.DAMAGETOT Perform the following steps to create a DB2 connection document to AUTOBODY.DAMAGETOT which in this case is a stored procedure: 1. From the LEI Administrator Action menu, click Create -> Connection -> DB2. 2. From the Connection to DB2 document, in the Connectivity section, enter the following values: – Name: This is any name you want to give to your connection document. For this example enter DB2 Connection to AUTOBODY.DAMAGETOT – Database: This is the name of the database that you want to connect to. For iSeries this is the RDB directory entry name. See 5.2.2, “Creating a local relational database directory entry” on page 105 for details. For our example we used as06. – User Name: The user name must be a valid OS/400 user profile. This user should have access to the DB2 UDB files you want to access. – Password: This field is the associated password for the OS/400 user profile that will be connecting to the database. The password will appear in clear text in the connection document but can be encrypted. In order to encrypt the password field, click the key icon, and choose the secret encryption key. For more information about creating secret encryption keys, see ‘Creating secret encryption keys’ in the Domino Designer help. – Data Journaling: Click Off. This radio button allows you to select if the DB2 UDB files that will be accessed by this connection document are journaled or not. You should check with the database administrator to see if the files are journaled and set this parameter accordingly. Note: The Data Journaling radio button does not turn journaling on or off on the DB2 UDB tables. The selection in the connection document should represent if journaling is on or off on the tables that you will access. If your database is journaled, you must set Data Journaling to On in the connection document. Be sure to verify data journaling because LEI will generate an error if this setting is not appropriately set. For more information about how to check on database journaling, refer to “Checking for journaling” on page 294. 3. For the Selection Type field, click Procedure. 4. Under Procedure Selection, specify AUTOBODY as the Owner and DAMAGETOT as the Name. The Parameter(s) field will be automatically populated. See Figure 8-41. 242 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 8-41 DB2 connection document to EMPLIB.DAMAGETOT 5. In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 6. Leave the rest of the fields with the default and click Save and Close to finish. For more information about DB2 connection documents, refer to 6.1, “DB2 connection document” on page 154. 8.10.4 Create a virtual documents activity document You can create a virtual documents activity with or without the user assistant. In this example we use the user assistant. Perform the following steps: 1. From the LEI Administrator Action menu, click Create -> Activity -> Virtual Documents. 2. Click OK on the first user assistant window. 3. You are now prompted to select your Domino database. Select AutoBodyDemo.nsf from the list and click OK. 4. You are prompted to specify the metadata, which is a Domino form in this case. Select the VirtClaimEstimate form and click OK. 5. You are now prompted to specify the connection document created earlier for DB2 in 8.10.1, “Create a DB2 connection document to AUTOBODY.AUTOBODY_EST” on page 238. Select DB2 Connection to AUTOBODY.AUTOBODY_EST from the list and click OK. Chapter 8. Advanced RealTime activities 243 6. Now the user assistant will bring up the key and data field mapping window. Click the corresponding fields to map them (see Figure 8-42) and click OK. 7. You are also prompted to provide a descriptive name for the activity. Enter Virtual Documents for AUTOBODY_EST and click OK. 8. Your virtual documents activity should be as shown in Figure 8-42. Figure 8-42 Virtual documents activity to AUTOBODY.AUTOBODY_EST 9. Click OK when the user assistant window indicates that the configuration is complete. You will get an error message (see Figure 8-12 on page 213). This error is expected as described earlier in 8.1.2, “External system metadata for virtual documents activities” on page 197. 10.In order to fix this error, click the Use External Key Table radio button located under the Options tab, General Options sub- tab, Key Table Option field of the virtual documents activity document. 11.Provide a name for the key table in the Key Table Name field. This can be any descriptive name, for our example we use AUTOBODY.AUTOBODY_EST_KEY. 12.Enter ESTIMATEID in the Key Field(s) field. 13.Click the Create External Key Table button to have LEI generate the external key table in DB2 UDB. 14.Your virtual documents activity document, Options tab, General Options sub-tab should look like what is shown in Figure 8-43. 244 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 8-43 Virtual documents activity document, Options tab, General Options sub-tab 15.Under the Options tab, Virtual Attachments sub-tab, click the Virtualize Attachments checkbox in the Attachments field. 16.Enter AUTOBODY.AUTOBODY_EST_ATTACH for the Attachment Table. 17.Click the Create Virtual Attachment Table button to create the external attachment table. Note: When using virtual fields with virtual documents, the virtualize attachments option must only be enabled in virtual documents activity. 18.The Create Attachment Table dialog box shown in Figure 8-44 is displayed. Click No to the question ‘Will the table contain attachments from more than one Notes Database?’ Click OK. Attention: In LEI versions up to 6.0.2, there is no problem leaving the Max attachment size blank. However, for better performance during fetch, later versions of the DB2 connector may allocate enough memory to contain the maximum size you specify here, even if the actual attachment is very small. Therefore, to continue working in future versions, the maximum attachment size should not exceed the amount of RAM that your server can comfortably allocate at one time. Chapter 8. Advanced RealTime activities 245 Figure 8-44 Create virtual attachments table 19.A completion notification will be displayed as shown in Figure 8-45. Click OK. Figure 8-45 Virtual attachments table created successfully message 20.Figure 8-46 shows how your virtual documents activity document, Options tab, Virtual Attachments sub-tab should look like. Figure 8-46 Virtual documents activity document, Options tab, Virtual Attachments sub-tab 21.In the Scheduling section, click Custom as the Scheduling Option and have LEI run Monday - Friday from 7:00 AM - 7:00 PM. 22.In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 23.Leave the rest of the fields with the default values and click Save and Close to finish. 8.10.5 Create a virtual fields activity document You can create a virtual fields activity document with or without the user assistant wizard. In this example we use the user assistant. Perform the following steps: 1. From the LEI Administrator Action menu, click Create -> Activity -> Virtual Fields. 2. Click OK on the first user assistant window. 3. You are now prompted to select your Domino database. Select AutoBodyDemo.nsf from the list and click OK. 246 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 4. You are prompted to specify the metadata, which is a Domino form in this case. Select the VirtClaimEstimate form and click OK. 5. You are now prompted to specify the connection document created earlier for DB2 in 8.10.2, “Create a DB2 connection document to AUTOBODY.AUTOBODY_DAMAGE” on page 240. Select DB2 Connection to AUTOBODY.AUTOBODY_DAMAGE from the list and click OK. 6. Now the user assistant displays the key and data field mapping window. For keys, map EstimateId to ESTIMATEID. For data fields, click the corresponding fields to map them (see Figure 8-47) and click OK. 7. You will be prompted to specify the document events to monitor. Select the create, open, update, delete events and click OK. 8. You are also prompted to provide a descriptive name for the activity. Enter Virtual Fields for AUTOBODY_DAMAGE and click OK. 9. Your virtual fields activity document should be as shown in Figure 8-47. Figure 8-47 Virtual fields document to AUTOBODY.AUTOBODY_DAMAGE 10.Under Options tab, Multi-Value Data sub-tab, click the Use multi-value data fields checkbox. 11.In the Subkey fields field, specify ITEMNO. Note: In our testing for this example, we have found that if you do not specify subkey fields for the multi-value data, you will experience error when trying to edit and save a document. This happens if the virtual fields activity is set to monitor all events (open, create, update, delete). In addition, virtual attachments will not be retained if you add an attachment and save a document even though you have virtualize the attachments in the virtual documents activity document. 12.In the Sorting field, click the Sort multi-value data checkbox. Chapter 8. Advanced RealTime activities 247 13.In the Sorting fields field, specify ITEMNO. 14.In the Text order field, click Binary. 15.In the Direction field, click Ascending. 16.See Figure 8-48 for example of how your virtual fields activity document, Options tab, Multi-Value Data sub-tab should look. Figure 8-48 Virtual fields activity document, Options tab, Multi-Value Data sub-tab 17.For scheduling, set the scheduling option to Custom, running Monday - Friday between 7:30 AM - 7:00 PM. 18.n the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 19.Leave the rest of the fields with the default values and click Save and Close to finish. 8.10.6 Create a virtual agents document Perform the following steps to create a virtual agents document: 1. From the LEI Administrator Action menu, click Create -> Activity -> Virtual Agents. 2. The Creating a Virtual Agents Activity user assistant as shown in Figure 8-49 is displayed. Click OK. 248 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 8-49 Creating a Virtual Agents Activity user assistant 3. You are prompted to select your Domino database. Select AutoBodyDemo.nsf from the list and click OK (Figure 8-50). Figure 8-50 Selecting the AutoBodyDemo.nsf Domino database Chapter 8. Advanced RealTime activities 249 4. At this point you need to specify the connection document created earlier for DB2. Select DB2 Connection to AUTOBODY.DAMAGETOT from the list and click OK (Figure 8-51). Figure 8-51 Selecting the DB2 Connection do AUTOBODY.DAMAGETOT 5. You are prompted to select the owner of the metadata. Select AUTOBODY from the list and click OK (Figure 8-52). Figure 8-52 Selecting the metadata owner 6. The next step requires you to select the stored procedure, which is DAMAGETOT. Click OK (Figure 8-53). 250 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 8-53 Selecting the stored procedure DAMAGETOT 7. Enter a descriptive name for the activity, such as Virtual Agents for AUTOBODY.DAMAGETOT as shown in Figure 8-54. Figure 8-54 Entering the activity name 8. The user assistant will indicate completion of the basic configuration as shown in Figure 8-55. Click OK. Chapter 8. Advanced RealTime activities 251 Figure 8-55 Virtual agents activity document completion 9. In the virtual agent document as shown in Figure 8-56, for the Scheduling section, click the Scheduling Option of Custom and specify to run Monday - Friday between 7:30 AM 7:00 PM. 10.Leave the rest of the values as the default and you should have a virtual agent activity document as shown in Figure 8-56. 252 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 8-56 Virtual agents activity document 11.Click Save and Close to finish. 8.10.7 Testing the virtual attachments activity Perform the following steps to test the virtual attachments activity: 1. Make sure the virtual documents activity titled Virtual Documents for AUTOBODY_EST is started first. Then verify t the virtual fields activity titled Virtual Fields for AUTOBODY_DAMAGE activity is started. 2. Open the Domino database AutoBodyDemo.nsf on your Lotus Notes client and go to the “Estimates By \ Estimate No” view. You should see documents in the view. These documents are virtual documents retrieved from the DB2 UDB database. Verify that all the damages are itemized under the Damage tab. This itemization is accomplished using multi-value data in virtual fields. 3. Edit one of the documents from your Lotus Notes client and add one or more attachments. Note: Do not attach any files larger than 100 KB in this example. The DB2 UDB virtual attachment table maximum size for the BLOB column is 100 KB. 4. Once your changes have been saved, verify that the DB2 UDB table AUTOBODY.AUTOBODY_EST has been updated accordingly. Also make sure that attachments are correctly saved. Refer to Appendix B, “Using iSeries Navigator to access DB2 UDB” on page 285 for more information about how to do this using iSeries Navigator. Chapter 8. Advanced RealTime activities 253 8.10.8 Testing the virtual agents activity Perform the following steps to test the virtual agents activity: 1. Open the Domino database, AutoBodyDemo.nsf, on your Lotus Notes client and go to the Estimates By \ Estimate No view. 2. Find a document that does not have the Total field populated. 3. Highlight the document you just changed from the view and manually run the virtual agent by clicking on the pull-down menu options of Actions -> DAMAGETOT as shown in Figure 8-57. Figure 8-57 Running the DAMAGETOT virtual agent 4. Open the document and verify that the Total has now been calculated and populated in the document. 5. For further testing, find a document that has the Total field populated. Take a note of the current value and verify that the DB2 UDB table AUTOBODY2.AUTOBODY_EST also has that value. 6. Edit the document by changing one of the Quantity or Part Cost fields. Click the Save and Close button to save your changes. 7. Highlight the document you just changed from the view and manually run the virtual agent by clicking on the pull-down menu options of Actions -> DAMAGETOT. 8. Open the document and verify that the Total has been recalculated based on your update. 9. Go to the AUTOBODY.AUTOBODY_EST table and verify that the value has also been updated there. Refer to Appendix B, “Using iSeries Navigator to access DB2 UDB” on page 285 for more information about using iSeries Navigator to do this. 254 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 9 Chapter 9. Batch activities This chapter describes the batch activities supported in Lotus Enterprise Integrator (LEI) 6.0.1 and provides detailed examples of a scripted and replication activities. In LEI 6.0.1 for iSeries, only connection to DB2 UDB external database is supported (see Chapter 6, “Connection documents” on page 153 for all supported connections). Therefore, all discussions and examples in this chapter focus on DB2 UDB. Note: Before the running the examples in this chapter, be sure that you have the required setup completed for the examples. Refer to Chapter 7, “Setting up the examples environment” on page 183 for more details. Each example in this chapter informs you of which databases are required. © Copyright IBM Corp. 2003. All rights reserved. 255 9.1 Scripted activity A scripted activity enables you to execute LotusScript Extensions for Lotus Connectors (LC LSX) commands. Using a scripted activity, you can extend the functionalities available from LEI Administrator, such as direct transfer, polling, and replication. The scripted activity is useful when you need complete control over the data transfer. In addition, you can perform data manipulation or evaluation during the transfer. In order to create a scripted activity, you must have the Domino Designer client installed. Scripted activity is not limited to data transfers. You can run any Domino agents using this activity. Consider this scenario, in Domino R5 there is a limitation for Domino scheduled agents that does not allow you to access remote servers. For example, if you have an agent running on an application server that needs to modify the ACL of remote mail servers, you will not be able to schedule this agent. Users with an administrator access to the mail servers will have to manually run the agent. With LEI, you can schedule this agent by creating a scripted activity document and set it to run on a specified schedule. If you are migrating any scripts or agents from the previous versions of LEI, the migration process will automatically update the USELSX statement to LSXLC given that your code is stored in the LEI Vault. Refer to Chapter 4, “Migrating from Lotus Enterprise Integrator 3.x” on page 87 for more information. The LotusScript Extensions for Lotus Connectors (LC LSX) does not require that you have LEI installed on your Domino server in order for you to be able to use it. For example, you can use LC LSX in your agents as long as you are running it on a Domino 6 server. If you want to run the agent manually from your local workstation, you will need to have a Domino 6 server installed locally. Note: In Domino R5, you must explicitly install the LotusScript Extension Toolkit during the Domino code installation process. In Domino 6, the toolkit is automatically installed. For a complete reference on using the LotusScript classes for Lotus Connector, refer to Lotus Connector Lotus Script Extension Guide (lsxlc6.nsf). This guide is available for download from the Lotus Developer Domain Documentation Library Web site at: http://www.lotus.com/ldd/notesua.nsf 9.1.1 Example: Building a direct transfer scripted activity This example illustrates a law firm that maintains and tracks their case files in Domino and has gotten to a point where the Domino database is extremely large and inefficient. Therefore, the firm has decided to migrate the back-end data into a DB2 UDB table. For simplicity, we will create one table in DB2 UDB to hold the data. In order to run this example, you need to the Domino database casefile.nsf as discussed in Chapter 7, “Setting up the examples environment” on page 183. Create a Notes connection document Perform the following steps to create a Notes connection document: 1. Start Lotus Notes and open the LEI Administrator database, descadm.nsf. 2. From the LEI Administrator Action menu, click Create -> Connection -> Notes. 3. In the Connection to Notes document, Connectivity section, enter the following values: – Name = Notes Connection to Casefile.nsf 256 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server – Domino Server field = The Domino server where you have LEI installed. – Notes Database = Casefile.nsf 4. In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 5. Leave the rest of the fields with the default values. Click Save and Close to finish. For more information about Notes connection documents, refer to 6.2, “Notes connection document” on page 157. Create a connection document to DB2 If you do not have the global DB2 connection document called DB2 Connection which was created in 8.6.1, “Create a DB2 connection document” on page 206, follow the instructions on page 206. Otherwise, you can skip this step. Create the script in the script vault Perform the following steps to create the script: 1. Open LEI Vault (leivlt6.nsf) of your LEI server from the Domino Designer client. 2. Copy the Example script library from casefile.nsf to LEI Vault. Example 9-1 displays the content of the subroutine that will perform the direct transfer. Note: We recommend using a script library if you will be running your scripted activity regularly. Using a script library improves performance because the object initialization will occur once when the script library is initialized and available every time the agent is invoked. Example 9-1 RunCaseFileDirectTransfer subroutine Option Public Option Explicit Uselsx "*lsxlc" 'Declarations 'all Sessions needed to be Dim'd as Named sessions for LEI Public Const XFER_SESSION_NAME = "CaseFiles_DirectTransfer" 'This corresponds to the Connection Document that connects to the Notes database Public Const XFER_SOURCE_CONNECTION = "Notes Connection to Casefile.nsf" 'This corresponds to the Connection Document that connects to the Destination Notes database Public Const XFER_TARGET_CONNECTION = "DB2 Connection" 'The Data table in the Packagetrack database Public Const XFER_SOURCE_METADATA = "Case" 'This will be the metadata created in the destination database. Public Const XFER_TARGET_METADATA = "EMPLIB.CASE_FILES" 'to allow for precision truncation, in the case where truncation of data is necessary for the activity to proceed. 'These are set as the initial field flags for each field added to the fieldlist. Public Const XFER_TRUNCATION_FLAGS = LCFIELDF_TRUNC_PREC 'Optional. The number of records in the fieldlist. The default is 1. All fields added to the fieldlist will have this number of records. Public Const XFER_RECORD_COUNT = 1 'The statement to execute in the syntax defined for the connector. In this case, the connector is notes. 'For a relational database, it would be similiar to this SQL statement: "Select * from TABLENAME". Chapter 9. Batch activities 257 Public Const XFER_STATEMENT = "Select @ALL" 'To create the target metadata, set this to "1". Public Const XFER_CREATE = 1 ' E-Mail Address of the person to receive the notification of error/success Public Const XFER_EMAIL_RECIPIENT = "Administrator/ITSO" Sub RunCaseFilesDirectTransfer ' ' ' ' ' ' Dim Dim Dim Dim Dim Dim Dim Dim Dim Dim Dim Dim Dim Dim Dim Dim ---------------------------------------------------------------------------------Before any LEI objects may be used, an LCSession context must be created. This provides all of the logging and administration required by the rest of LEI and the other LEI objects you may create ---------------------------------------------------------------------------------s As New NotesSession db As NotesDatabase doc As NotesDocument session As New LCSession(XFER_SESSION_NAME) record_count As Long count As Long src_connect As New LCConnection (XFER_SOURCE_CONNECTION) targ_connect As New LCConnection (XFER_TARGET_CONNECTION) fieldlist As LCFieldlist field As LCField mapped_fieldlist As LCFieldList vDate As LCDateTime todayDate As New NotesDateTime("Today") createDate As NotesDateTime sqlStmt, newCase, body As String numInserted As Integer On Error Goto ErrHandler Set db = s.CurrentDatabase Set doc = db.CreateDocument ' turn on connection pooling session.ConnectionPooling = True ' specify metadata src_connect.metadata = XFER_SOURCE_METADATA targ_connect.metadata = XFER_TARGET_METADATA ' connect to both database components src_connect.Connect targ_connect.Connect CreateTable: ' now connected, we can execute a SQL statement to create the table sqlStmt = "CREATE TABLE " + XFER_TARGET_METADATA + " ( " sqlStmt = sqlStmt + "CASENUM SMALLINT NOT NULL , " sqlStmt = sqlStmt + "DATEOPENED DATE DEFAULT NULL , " sqlStmt = sqlStmt + "TITLE CHAR(50) CCSID 37 DEFAULT NULL , " sqlStmt = sqlStmt + "DESCRIPTION FOR COLUMN DESCR00001 CHAR(100) CCSID 37 DEFAULT NULL , " sqlStmt = sqlStmt + "STATUS CHAR(15) CCSID 37 DEFAULT NULL , " sqlStmt = sqlStmt + "OPENEDBY CHAR(20) CCSID 37 DEFAULT NULL , " sqlStmt = sqlStmt + "ASSIGNEDTO CHAR(20) CCSID 37 DEFAULT NULL , " sqlStmt = sqlStmt + "CLIENT CHAR(20) CCSID 37 DEFAULT NULL , " sqlStmt = sqlStmt + "CONTACT CHAR(20) CCSID 37 DEFAULT NULL , " 258 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server sqlStmt = sqlStmt + "CONTACTPHONE FOR COLUMN CONTA00001 CHAR(12) CCSID 37 DEFAULT NULL , " sqlStmt sqlStmt sqlStmt sqlStmt count = = sqlStmt + "CREATEDBY CHAR(40) CCSID 37 DEFAULT NULL , " = sqlStmt + "CREATIONDATE DATE DEFAULT NULL , " = sqlStmt + "MODIFIEDDATE TIMESTAMP DEFAULT NULL, " = sqlStmt + "BODY BLOB(5242880) DEFAULT NULL ) ;" targ_connect. Execute (sqlStmt, Nothing) ' create fieldlist and Execute statement and result set record_count = XFER_RECORD_COUNT If (record_count = 0) Then record_count = 1 End If Set fieldlist = New LCFieldlist (record_count, XFER_TRUNCATION_FLAGS) 'This method executes a statement in Connector-specific syntax for the purposes of producing a result set. 'Count is the number of records selected or affected by this statement. 'If this number cannot be determined by the connector, the constant LCCOUNT_OVERVIEW is returned. count = src_connect.Execute (XFER_STATEMENT, fieldlist) 'This was a successful execution that produced no data 'consider it completed successfully If ((count = 0) Or ((count = LCCOUNT_UNKNOWN) And (fieldlist.FieldCount = 0))) Then Exit Sub ' set for mapping by name targ_connect.mapbyname = "1" Set mapped_fieldlist = fieldlist ' Load first N records from the source count = src_connect.Fetch (fieldlist, 1, record_count) numInserted = 0 newCase = "" While (count > 0) ' Store N records in destination targ_connect.Insert mapped_fieldlist, 1, count numInserted = numInserted + 1 Set field = fieldlist.Lookup ("CreationDate") If Not (field Is Nothing) Then Set vDate = field.GetDatetime (1) Set createDate = New NotesDateTime (vDate.Text) If todayDate.DateOnly = createDate.DateOnly Then Set field = fieldlist.Lookup ("CaseNum") If Not (field Is Nothing) Then newCase = newCase & Chr$(13) & Cstr(field.GetInt (1)) Set field = fieldlist.Lookup ("Title") If Not (field Is Nothing) Then newCase = newCase & " - " & field.Text (0) End If End If ' Load next N records from the source count = src_connect.Fetch (fieldlist, 1, record_count) Wend ' disconnect src_connect.Disconnect targ_connect.Disconnect Chapter 9. Batch activities 259 ' create notification of completion With doc .Form = "Memo" .SendTo = XFER_EMAIL_RECIPIENT .Subject = "LEI Activity: Case Files Direct Transfer Success Notification" body = "Successfully inserted " & numInserted & " records into DB2" If newCase <> "" Then body = body & Chr$(13) & "The following lists the new cases created today:" & newCase .Body = body Call .Send(False) End With Exit Sub ErrHandler: If (session.Status <> LCSUCCESS) Then Dim text As String Dim extcode As Long Dim exttext As String Call session.GetStatus (text, extcode, exttext) If (session.Status = LCFAIL_EXTERNAL) Then If extcode = -601 Then'CASE_FILES table already exists sqlStmt = "DROP TABLE " + XFER_TARGET_METADATA + ";" Print sqlStmt count = targ_connect. Execute (sqlStmt, Nothing) Goto CreateTable Else Print "DB2 message: " & exttext & " code #" & Cstr(extcode) End If Else Print "Connector message: " & text End If Else Print "Case Files Direct Transfer - Error" & Str(Err) & ": " & Error$ & " on line " & Cstr(Erl) End If ' create notification of error With doc .Form = "Memo" .SendTo = XFER_EMAIL_RECIPIENT .Subject = "LEI Activity: Case Files Direct Transfer Error Notification" body = "Error occurred - " & Str(Err) & ": " & Error$ body = body & Chr$(13) & "Inserted " & numInserted & " records into DB2" .Body = body Call .Send(False) End With Exit Sub End Sub Note: Be sure to modify XFER_EMAIL_RECIPIENT constant to your name so that any e-mail notifications will be sent to you. If you do not name your library as suggested by the examples, please be sure that XFER_TARGET_METADATA points to the correct library. Similarly, if you do not name the connection documents as suggested, make sure XFER_SOURCE_CONNECTION and XFER_TARGET_CONNECTION points to the correct connection documents. 260 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 3. Figure 9-1 shows how to copy the Examples script library from casefile.nsf using the Domino Designer client. Figure 9-1 Copying Examples script library 4. Paste the script library to the LEI Script Vault as displayed in Figure 9-2. Figure 9-2 Pasting the Examples script library into the LEI Vault Chapter 9. Batch activities 261 5. Create an agent in LEI Script Vault that calls the RunCaseFileDirectTransfer subroutine by clicking the Create Agent button available from any of the views in the LEI Vault. Optionally, you can choose to copy the Case Files Direct Transfer agent from casefile.nsf (see Figure 9-3) and paste the agent to LEI Script Vault in Domino Designer (see Figure 9-4). Figure 9-3 Copying the Case Files Direct Transfer agent Figure 9-4 Pasting he Case Files Direct Transfer agent into the LEI Vault Create a scripted activity Perform the following steps to create an LEI scripted activity: 1. From the LEI Administrator Action menu, click Create -> Activity -> Scripted. 262 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 2. In the Identification section, provide a descriptive name, such as Direct Transfer Scripted Activity for Case Files. 3. Under Script section, put your LEI server name as the Agent Server, leivlt6.nsf as the Agent Database and select Case Files Direct Transfer from the list as the Agent Name. 4. In the Activity Execution Options tab, enter your LEI server name as the Designated Server. For our example we used leidomsvr. 5. In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 6. Leave the rest of the fields with the default, your scripted activity document should look like the one shown in Figure 9-5. Figure 9-5 Scripted activity document 7. Click the Save and Close button to finish. Testing the scripted activity Perform the following steps to test the scripted activity: 1. Open LEI Administrator, go to an Activities view and highlight the new activity document. Start the scripted activity by clicking the Start Activity button. 2. The RunCaseFileDirectTransfer subroutine will use connection documents created through LEI Administrator to connect to the data sources. Once connected, the script will execute a SQL statement to create the DB2 UDB table that will hold the data transferred from the Domino database. In addition, the script inspects each row to compile a list of cases created today. This list will be displayed in an e-mail sent out to administrators once the script has successfully run. If any errors occur during the execution, this script Chapter 9. Batch activities 263 demonstrates how errors are being handled. Administrators receive an e-mail notification if errors occur. 3. It will take a few minutes for the activity to run. Once it finishes, verify the EMPLIB.CASE_FILES table has been created and populated with data from the Domino database. You can do this using Run SQL script window for the following SQL statement: Select * from emplib.case_files After running the SQL statement, you should see 3 rows of data in EMPLIB.CASE_FILES table. Refer to Appendix B, “Using iSeries Navigator to access DB2 UDB” on page 285 for more information about using iSeries Navigator to do this. 9.2 Replication activity A replication activity synchronizes data between two data sources, for example, Domino and DB2 UDB databases. It can also be used to merge data from one data source to another. You can use the replication activity in conjunction with a polling activity to refine when the replication activity occurs. For example, you could poll a data source for a specific event, such as a data insertion, and on detection of that event start the replication activity that replicates the new data into another data source. There are two types of replication available from the LEI replication activity: Primary key replication Timestamp replication 9.2.1 Primary key replication LEI primary key replication replicates data based on a unique key common to both connections that can be composed of one or more fields in the metadata. The function of the primary key is to determine if matching records exist in both data sources and if an update to a record, the insertion of a new record, or the deletion of a record is required. How does primary key replication work? When replication occurs, records are replicated according to the following default rules: If a record with matching key values exists in both connections, and the data field values are identical, no action is taken. If a record with matching key values exists in both connections, and the data field values are different, the target record is updated. If a source record contains key values that are not present in the target, a new record is inserted into the target. If a target record contains key values that are not present in the source, that record is deleted from the target. Note: In primary key replication, the replication activity never changes records in the source connection. 9.2.2 Timestamp replication As described in the previous section, primary key replication never changes records in the source connection. If you need to be able to make changes in both connections and keep the 264 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server data synchronized, you need to use timestamp replication. In timestamp replication, there is no designation of source and target. Replication actions can affect both connections. In order for timestamp replication to work, you still must have a unique key or keys to match the records, and in addition you must have a field in both the source and target connections that will be used as the timestamp. In Domino, the field needs to be of type Date and in DB2 UDB, the field must be of type TIMESTAMP. For best performance, the timestamp in DB2 UDB should be indexed. Important: The DB2 UDB column used as the TIMESTAMP in timestamp replication must be of type TIMESTAMP, not DATE. How does timestamp replication work? The LEI replication activity document maintains internal timestamp fields based on the last replication from each respective connection. These fields are SrcTimeStamp and DestTimeStamp. You can see these fields by viewing the document properties of the activity document. To do so, right-click while active in the activity document or choose File -> Document properties from the Action bar. Use the Fields tab and scroll down to locate these field names as shown in Figure 9-6. Figure 9-6 Timestamp Replication Activity Document Property When replication occurs, records are replicated according to the following default rules: If a source record contains a timestamp value that is later than the SrcTimeStamp value, and a target record does not exist with the same key fields, a new record is inserted into the target. If a target record contains a timestamp value that is later than the DestTimeStamp value, and a source record does not exist with the same key fields, a new record is inserted into the source. If a source record contains a timestamp value that is later than the SrcTimeStamp value, and a target record exists with the same key fields, the target record is updated. If a target record contains a timestamp value that is later than the DestTimeStamp value, and a source record exists with the same key fields, the source record is updated. Records are never deleted from either connection. Note: If a source and target record share the same key fields and contain timestamp values that are later than the SrcTimeStamp and the DestTimeStamp respectively, then the target record is updated. In this case, the replication activity does not use the timestamp values to determine the replication action. Chapter 9. Batch activities 265 9.2.3 Example: Timestamp replication from DB2 UDB to Domino This example illustrates a medical facility that maintains and tracks their medical records in a DB2 UDB database. Some of the doctors want to be able to have a local Domino database replica for them to access from home. Since it is not possible to create local replicas directly from DB2 UDB to Domino, we first create a Domino replica on the server and then use the native Domino replication feature to create local replicas on the doctors’ laptops. Since the doctors want to have the capability to modify the records from the local replicas and have the modifications replicated to DB2 UDB (in addition to receiving updates from DB2 UDB), we will use timestamp replication. For simplicity, we will create one table in DB2 UDB to hold the data. In order to run this example, you need the Domino database medrec.nsf and DB2 UDB table EMPLIB.PATIENT as discussed in Chapter 7, “Setting up the examples environment” on page 183. Known issue with sort order in replication The key field of EMPLIB.PATIENT (PATIENTNO) is alpha-numeric. There is a known issue regarding using a mixed alpha-numeric key when replicating DB2 UDB data from iSeries to a Domino database with replication activity. You will find that LEI performs unnecessary record inserts and deletes. This is caused by the different sort sequences used by EBCDIC-based systems and Domino servers. Specifically, EBCDIC-based systems sort mixed alpha-numeric data by alpha characters first, then by numeric characters. Domino, on the other hand, sorts mixed alpha-numeric data by numeric characters first, then by alpha characters. When this occurs, LEI will insert records that do not match the sorted order that is presented by the DB2 connector and then remove the same records after Notes presents the same records. One solution to this issue is to use an Order MetaConnector either against the DB2 UDB connector, the Notes connector, or both. However, the use of MetaConnectors is a performance consideration. For more details about this problem and the recommended solution, refer to Technote #110127 titled ‘LEI: Addressing Sort Order Issues when Replicating DB2/400 Data to a Notes Database’ accessible at: http://www.ibm.com/support/docview.wss?uid=swg21101027 Create a Notes connection document Perform the following steps to create a Notes connection document: 1. Start Lotus Notes and open the LEI Administrator database, descadm.nsf. 2. From the LEI Administrator Action menu, click Create -> Connection -> Notes. 3. In the Connection to Notes document, Connectivity section, enter the following values: – Name = Notes Connection to Medrec.nsf – Domino Server field = The Domino server where you have LEI installed. – Notes Database = Medrec.nsf 4. In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 5. Leave the rest of the fields with the default values and you should have a Notes connection document as shown in Figure 9-7. 266 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 9-7 Notes connection document to medrec.nsf 6. Click Save and Close to finish. For more information about Notes connection documents, refer to 6.2, “Notes connection document” on page 157. Create a DB2 connection document to EMPLIB.PATIENT Perform the following steps to create a DB2 connection document to EMPLIB.PATIENT: 1. From the LEI Administrator Action menu, click Create -> Connection -> DB2. 2. From the Connection to DB2 document, in the Connectivity section, enter the following values: – Name: This is any name you want to give to your connection document. For this example enter DB2 Connection to EMPLIB.PATIENT. – Database: This is the name of the database that you want to connect to. For iSeries this is the RDB directory entry name. See 5.2.2, “Creating a local relational database directory entry” on page 105 for details. For our example we used as06. – User Name: The user name must be a valid OS/400 user profile. This user should have access to the DB2 UDB files you want to access. – Password: This field is the associated password for the OS/400 user profile that will be connecting to the database. The password will appear in clear text in the connection document but can be encrypted. In order to encrypt the password field, click the key icon, and choose the secret encryption key. For more information about creating secret encryption keys, see ‘Creating secret encryption keys’ in the Domino Designer help. – Data Journaling: Click Off. This radio button allows you to select if the DB2 UDB files that will be accessed by this connection document are journaled or not. You should Chapter 9. Batch activities 267 check with the database administrator to see if the files are journaled and set this parameter accordingly. Note: The Data Journaling radio button does not turn journaling on or off on the DB2 UDB tables. The selection in the connection document should represent if journaling is on or off on the tables that you will access. If your database is journaled, you must set Data Journaling to On in the connection document. Be sure to verify data journaling because LEI will generate an error if this setting is not appropriately set. For more information about how to check on database journaling, refer to “Checking for journaling” on page 294. 3. Under Table Selection section, specify EMPLIB as the owner and PATIENT as the table name. The columns will be automatically populated as shown in Figure 9-8. 4. In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 5. Leave the rest of the fields with the defaults and you should have a DB2 connection document as shown in Figure 9-8. Figure 9-8 DB2 connection document to EMPLIB.PATIENT 6. Click Save and Close to finish. For more information about DB2 connection documents, refer to 6.1, “DB2 connection document” on page 154. 268 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Create a replication activity document Perform the following steps to create a replication activity document: 1. From the LEI Administrator Action menu, click Create -> Activity -> Replication. 2. Provide a descriptive name, such as Timestamp Replication for Medical Records. 3. For the source connection, select DB2 Connection to EMPLIB.PATIENT. See Figure 9-9. Figure 9-9 Selecting the DB2 Connection to EMPLIB.PATIENT source connection 4. For the Target Connection, select Notes Connection to medrec.nsf as shown in Figure 9-10. Figure 9-10 Selecting the Notes connection to medrec.nsf target connection 5. From the Notes selection window shown in Figure 9-11, click Patient as the form to use. Chapter 9. Batch activities 269 Figure 9-11 Selecting the Notes form to use 6. On the Data Field Mapping window shown in Figure 9-12, click the arrow next to the Mapping label to map your key and data fields. Click OK when finished. Figure 9-12 Data field mapping 7. Figure 9-13 shows what your replication activity document should look like. 270 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure 9-13 Replication activity document 8. Under the Source Restrictions and Target Restrictions fields, be sure to uncheck all the checkboxes, except for Skip Deletions. The source restrictions are not visible until you enable timestamp replication. See Figure 9-13. 9. Under the Replication Options tab, Timestamp sub-tab, click the Enable Timestamp Replication checkbox and select DATE_MODIFIED for both the Source and Target Timestamp fields. See Figure 9-14. Figure 9-14 Enable Timestamp Replication 10.In the Other section, enter LEI6 Tutorial as the category. This step is not required. However, you will find that it is useful to add a category as the LEI Administrator database grows and becomes harder to manage. 11.Leave the rest of the fields with the defaults. Chapter 9. Batch activities 271 12.Click Save and Close to finish. Testing the replication activity Perform the following steps to test the replication activity: 1. Open the Domino database medrec.nsf on your Lotus Notes client and verify that there is no data there by opening a view and verifying there is no documents in the view. 2. From the LEI Administrator, start the replication activity by clicking on the Start Activity button. It will take a few minutes for the activity to run. Be patient! While LEI is processing the activity, you will see the hourglass icon. 3. Once the replication activity is completed, refresh the view in the medrec.nsf database using the F9 function key. You should see there are now documents in the view. These documents have been replicated from the EMPLIB.PATIENT table in DB2 UDB. 4. Update one of the documents from your Lotus Notes client. For example, change the middle initial of one of the patients. 5. Start the replication activity from LEI Administrator again. When the activity is completed, verify that the change you made has been replicated to EMPLIB.PATIENT. Refer to Appendix B, “Using iSeries Navigator to access DB2 UDB” on page 285 for more information about using iSeries Navigator to do this. 6. Now we test to make sure that if you make an update in the DB2 UDB table, the change will also be replicated to your Domino database. Use the following SQL statement in iSeries Navigator Run SQL Script window to change the middle initial of one the patients: UPDATE EMPLIB.PATIENT SET MIDINIT = 'L', DATE_MODIFIED = CURRENT TIMESTAMP WHERE PATIENTNO = 'MD-001'; Refer to Appendix B, “Using iSeries Navigator to access DB2 UDB” on page 285 for more information about using iSeries Navigator to do this. Note: The timestamp field, DATE_MODIFIED will not be automatically updated. Therefore it is necessary to manually update it in this example. 7. Verify the SQL statement has successfully run and updated the middle initial and timestamp fields. 8. Start the replication activity from the LEI Administrator again. When the activity is completed, verify that the change you made has been replicated to the Domino database. 9.3 Other data moving activities LEI has other data moving activities that are valuable tools for your data moving needs. This section briefly discusses these activities. For more information about these activities, refer to the LEI Activities and User Guide. 9.3.1 Archive The Archive activity moves data from one database to another. It is useful to place infrequently accessed data to a removable storage device to free space on a system server, protect data when migrating from one database to another, and create space on a full disk. The Archive activity deletes the original records from the source database. 272 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 9.3.2 Command A Command activity executes operating system, database, and SQL commands. In order to execute an operating system command, select No Connector and enter the command as it would be entered at an operating system command prompt. For a database or connection-specific command, select the appropriate connection document. 9.3.3 Direct transfer A Direct Transfer copies data from one database to another. The data to be transferred is identified by a statement, for example a SQL query or Notes selection formula. Direct Transfer activities can be combined with other activities, such as a Polling activity in order to perform the data transfer when a specified condition is met. 9.3.4 Java A Java activity allows LEI to launch a Java application. The Java application is not restricted to LEI-specific applications. A Java activity is useful when you need more elaborate control of source and destination during data transfers or when you expect to perform different kinds of data massaging based on certain application-specific conditions. When developing a Java activity or activity document, consider the following: The application must exist on the same system as the LEI server that is designated to run that application. A Java JVM must also exist on that system. 9.3.5 Polling The Polling activity polls a database to see if a specified condition exists, and, if so, executes an activity. A Polling activity is useful when you need to execute some action when another action or event occurs or is encountered. The Polling activity can run more than one activity at a time (for example, a replication activity and a direct transfer activity). 9.3.6 Admin-Backup The Admin-Backup activity backs up the LEI Administrator database (decsadm.nsf) and, optionally, the LEI Script Vault database (leivlt6.nsf). The Admin Backup activity is useful when you want to create a safe backup of the LEI Administrator and associated documents and optionally the LEI Script Vault. 9.3.7 Admin-Purge Log The Admin-Purge Log activity purges the LEI log database of documents older than a user-specified number of days. The Admin Purge Log is useful to control the size of your LEI log database. Chapter 9. Batch activities 273 274 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server A Appendix A. Removing Lotus Enterprise Integrator (LEI) This appendix covers the removal of LEI from the iSeries platform. Removal of any software is never as simple as just removing the code off the desired workstation or server. There are a number of issues that require addressing prior to physical removal, otherwise users of the environment could find access to systems, that are expected to be available, are no longer responding. The issues covered in this appendix are not discussed in detail as each situation and response will be different at each site. The topics discussed include: Considerations that require addressing prior to removal of a software resource. The process of removing LEI 6.0.1 from the iSeries platform. Note: For LEI uninstall and removal instructions specific to other LEI 6 releases, see the LEI installation guide supplied with your product and also available on the Lotus Developers Domain Documentation Library Web site in the Enterprise Integrator product area at: http://www.lotus.com/ldd © Copyright IBM Corp. 2003. All rights reserved. 275 Considerations prior to removing LEI Whether LEI has been operating as a pilot environment, or has been employed as an enterprise solution for a number of years there are issues that must be resolved prior to removing the LEI infrastructure. Issues that are to be resolved include: How is access to data, presently provided through LEI going to continue to be provided? Is this server part of an LEI cluster? Is it envisioned that the previous Domino Enterprise Connection Services (DECS) environment is going to be reinstated? Access to data The removal of LEI from a server is likely to have issues in relation to the data being accessed by users or other servers. Issues that should be reviewed include: Is the information that is being accessed going to continue to be available through other means? Do users need to be informed of removal of access to information? Have users successfully been redirected to a different LEI server for the information? Is there a requirement for restoring Domino Enterprise Connection Services (DECS)? Are the new measurements in place before removing LEI? LEI clustered environment The first issue with LEI clustering that is required to be identified is whether the LEI server being removed is administered by a remote administrator, or whether it is the administration server administering the other LEI servers in the cluster. If the server being removed is remotely administered by a different LEI server it is fine to remove the LEI software from the server. After removing the LEI software the configuration document for the removed LEI server will require deleting from the LEI Administrator database on the administration server. The software cannot be removed if the LEI server is identified as the administration server for an LEI cluster. The LEI server configuration documents are not able to be reconfigured to be administered by a different server. Domino Enterprise Connection Services (DECS) If DECS is desired to be reinstated, the operator will have to be aware of selecting the radio button to delete the LEI Administrator and LEI databases, displayed in Figure A-8 on page 281, followed by selecting the checkbox for enabling DECS as an addin task. Note: This will reinstate the DECS administration database that was backed up at the time of installing LEI 6. This database is usually named decsadmn.nsf. The process does not migrate new Advanced RealTime activities or connection documents back to the DECS administration database; they will have to be recreated. The only connection documents and Advanced RealTime activities that will be present are the ones that were present at time of backup. 276 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Process of removing LEI Removing LEI is performed on a Win32 based workstation, similar to the process of installation. On the product media used to install LEI, is a file called iSetupUninstall.exe. This file is used to initiate the Java-based UninstallShield that will remove LEI from the iSeries server. 1. From a Win32 workstation, locate and run the uninstall program iSetupUninstall. The first screen presented is the window indicating that the Java Virtual Machine (JVM) is being prepared as shown in Figure A-1. Figure A-1 Java Virtual Machine - Informational message 2. When the JVM is prepared, the setup for LEI uninstall welcome screen is presented as shown in Figure A-2. This is informing you that you are about to initiate the uninstall process for LEI. Click Next to continue. Figure A-2 Setup - Welcome to LEI Uninstall on iSeries 3. The setup wizard now confirms the IP address of your workstation as shown in Figure A-3. The IP address of the current workstation is entered by default, confirm that the address is correct and click Next to continue. Appendix A. Removing Lotus Enterprise Integrator (LEI) 277 Figure A-3 Setup wizard - Confirming workstation IP address 4. The next screen is primarily an informational screen. As displayed in Figure A-4 the status of setup for uninstall is presented. Do not click any buttons unless intending to quit the process of removing LEI. Figure A-4 Setup wizard - Status of setup for uninstall environment 278 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 5. A signon window as shown in Figure A-5 requests you to sign onto the iSeries server that LEI is being removed from. Enter the iSeries system name, an OS/400 profile user and password. Click OK to continue. Figure A-5 iSeries server sign on 6. The setup wizard now opens a number of windows as displayed in Figure A-6. These windows include: – The Remote AWT Daemon controlling the connection between your workstation and the iSeries server. – A DOS window which is used to launch the Remote AWT Daemon. – The installation progress window (displayed as a grey window). – The uninstaller window (displayed as a white window). Note: These windows take a while to load, be patient. It is important that none of these windows are closed unless they are closed by the program itself or a prompt has displayed indicating that it is okay to close the window. Appendix A. Removing Lotus Enterprise Integrator (LEI) 279 Figure A-6 Workstation desktop Note: The uninstaller window (displayed with the white background in Figure A-6) is placed directly on top of the progress window (displayed with the gray background in Figure A-6) when it appears. It has also been known to appear directly behind the progress window. It is sometimes necessary to move the progress window to access the launched uninstaller window. 7. The UninstallShield window presents to the user two options. The option chosen depends on the issues raised in “Considerations prior to removing LEI” on page 276”. If you are choosing to leave the LEI Administrator databases, as displayed in Figure A-7, click Next to continue. If the decision is to delete the LEI Administrator and LEI databases, as shown in Figure A-8, then you have to select whether to: – Enable DECS as an addin task. – Delete the sample and documentation databases. – Delete the script vault database. Click Next to continue. 280 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure A-7 UninstallShield - leaving the LEI databases intact Figure A-8 UninstallShield - deleting the LEI databases 8. The UninstallShield now confirms what will be deleted and where from the system displayed in Figure A-9. Click Next to continue. Appendix A. Removing Lotus Enterprise Integrator (LEI) 281 Figure A-9 UninstallShield - uninstall information 9. The UninstallShield now begins the process of removing the files and displays an informational window to inform the operator that it is now uninstalling as shown in Figure A-10. Do not close this window. Figure A-10 UninstallShield - Uninstalling 282 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 10.When UninstallShield has completed removing LEI from the iSeries server it will display the successfully completed window shown in Figure A-11. Click Finish. Figure A-11 UninstallShield - Completion 11.The setup wizard now displays that it has completed the uninstall environment, as shown in Figure A-12. Click Finish. Figure A-12 Setup - Completion Appendix A. Removing Lotus Enterprise Integrator (LEI) 283 12.All windows should now be closed, and any remaining open can be manually closed at this point. 13.Restart the Domino server. 284 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server B Appendix B. Using iSeries Navigator to access DB2 UDB This appendix provides step-by-step instructions about how to access objects in DB2 UDB using iSeries Navigator. This appendix shows you how to do the following with iSeries Navigator: Connecting to an iSeries server Working with a library Working with tables © Copyright IBM Corp. 2003. All rights reserved. 285 Connecting to an iSeries server To connect to an iSeries server using iSeries Navigator, perform the following steps: 1. Start iSeries Navigator. 2. From the iSeries Navigator window, click the pull-down menu options of File -> Connection to servers -> Add connection (Figure B-1). Figure B-1 Adding a connection to iSeries Navigator 3. A dialog box shown in Figure B-2 is displayed. Enter your iSeries server name and click Next. Figure B-2 Add Connection - entering the iSeries server name 4. In the dialog box shown in Figure B-3, enter your OS/400 user ID and click Next. 286 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure B-3 Add Connection - entering the OS/400 user id 5. The next window as shown in Figure B-4 allows you to verify the connection to the iSeries server. Click Verify Connection. Figure B-4 Add Connection - verifying connection to the iSeries server 6. A dialog box appears as shown in Figure B-5 to verify the connection. Make sure it has completed successfully. Click OK to close the verify iSeries connection window. Click Finish to complete the task. Appendix B. Using iSeries Navigator to access DB2 UDB 287 Figure B-5 Verifying the iSeries connection successfully 7. The newly added connection to the iSeries server is now displayed in the iSeries Navigator window. When you click the new connection, you are prompted to sign on to the iSeries server. Enter your OS/400 userid and password (Figure B-6). Click OK. Figure B-6 Signing on to the iSeries server from iSeries Navigator Working with a library On the iSeries server, a library is a system object that serves as a directory to other objects. A library groups related objects and allows the user to find objects by name. Before you can create a database file, you must create a library to store it. For more information about libraries, refer to the IBM eServer iSeries Information Center Version 5 Release 2 (V5R2) at: http://publib.boulder.ibm.com/iseries/v5r2/ic2924/index.htm?info/rzahf/rzahfli0.htm Creating a library Perform the following steps to create a library using iSeries Navigator: 1. Start iSeries Navigator. 2. Click your iSeries server to expand the tree and then click Databases to expand that tree. 288 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 3. Right-click Libraries and then click New Library as shown in Figure B-7. Figure B-7 Creating a new library 4. A dialog box as shown in Figure B-8 will be displayed. Fill in the library name (for our example we used newlib) and click OK. If you leave the checkbox ‘Add to displayed list of libraries’ checked, the library will be displayed under Libraries in the iSeries Navigator. If you uncheck this option, you will need to manually add this library when you want to work with it from iSeries Navigator. See “Displaying a library” on page 290 for detailed instructions about how to do this. Figure B-8 New Library dialog box 5. The newly created library will be displayed under Libraries as shown in Figure B-9. Appendix B. Using iSeries Navigator to access DB2 UDB 289 Figure B-9 Newly created library Displaying a library Perform the following steps to display a library from iSeries Navigator: 1. Start iSeries Navigator. 2. Click your iSeries server to expand the tree. 3. Expand Databases until you find Libraries, which is under your database name (As08 in our example). 4. Right-click Libraries and click Select Libraries to display (Figure B-10). Figure B-10 Selecting libraries to display 290 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 5. The Select Libraries to Display dialog box as shown in Figure B-11 will be displayed. Figure B-11 Select Libraries to Display dialog box 6. Click the Select from list radio button. 7. Select the library you want to display from iSeries Navigator and click the Add button. The library selected is added to the list of Libraries to display on the right side of the dialog box. When you are finished adding libraries, click OK. In our example we are adding the AUTOBODY and EMPLIB libraries (Figure B-12). Figure B-12 Adding a library to be displayed from iSeries Navigator 8. The libraries you selected are now displayed under Libraries in the iSeries Navigator window (Figure B-13). Appendix B. Using iSeries Navigator to access DB2 UDB 291 Figure B-13 Libraries added to the iSeries Navigator displayed list Working with tables A table is a basic database object that is used to store database information. Tables are made up of fixed length rows and variable-length columns. While you are defining the table, you are given the opportunity to define indexes, constraints, and triggers. You can also add these definitions later. From the perspective of the iSeries server, physical files are identical to tables. For more information about DB2 UDB tables in iSeries, refer to DB2 Universal Database for iSeries manuals. Viewing the contents of a table You can display the contents of your tables and views from the iSeries Navigator by using quick view. With quick view, you can only view the contents; to make changes to a table, you have to open the table. If you have any columns in the table with a data type BLOB, you are not be able to open the view or update the table. If you attempt to do so, an error message as shown in Figure B-14 is displayed. Figure B-14 Error message when opening a table with BLOB data In the following steps we use the AUTOBODY library which is used in the Advance RealTime activities examples of this redbook. Perform the following steps view the contents of the AUTOBODY_DAMAGE table: 292 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server 1. Start iSeries Navigator. 2. Expand Databases and click the AUTOBODY library. 3. Right-click AUTOBODY_DAMAGE and click Quick View as shown in Figure B-15. Figure B-15 Using iSeries Navigator Quick View to view the contents of a table 4. The contents of the table is displayed as shown in Figure B-16. Figure B-16 Viewing the contents of the AUTOBODY_DAMAGE table Quick view will display the values of all the columns in a table. If you only want to view partial columns, you can use SQL statements to select the columns to display. For detailed instructions, refer to “Running SQL scripts” on page 295. Appendix B. Using iSeries Navigator to access DB2 UDB 293 Checking for journaling A database journal is an object that records changes to the database by sending information to the journal receiver. This information includes the table name and library it belongs to, the job ID, user ID, workstation ID, program name, date and time, type of activity, and relative record number of the affected record. You can also record information before and after a change takes place, giving you a more complete picture of the change being made. When building a connection document in LEI, you need to set data journaling to On or Off. Therefore, it is important to find out whether or not the DB2 UDB table you want to connect to is journaled. Perform the following steps to check for journaling on the EMPLIB.EMPLOYEE table: 1. Start iSeries Navigator. 2. Expand Databases and click EMPLIB under Libraries. 3. Right-click the EMPLOYEE database and click Journaling as shown in Figure B-17. Figure B-17 Checking for journaling on a table 4. A dialog box as shown in Figure B-18 is displayed. The status indicates whether or not the EMPLIB.EMPLOYEE database is journaled. In this example, the database is not journaled. 294 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure B-18 Status of journaling for EMPLIB.EMPLOYEE Running SQL scripts The run SQL scripts window in iSeries Navigator allows you to create, edit, run, and troubleshoot scripts of SQL statements. When you have finished working with the scripts, they can be saved to your local workstation. You can use run SQL scripts to: Create a SQL script Run SQL scripts View the result set of a stored procedure View the job log Change the options for running an SQL script Generate SQL for database objects In this appendix, we will only cover creating and running SQL statements to query a table and generating SQL for a table. For more information about what you can do with run SQL scripts, refer to DB2 Universal Database for iSeries manuals. Creating and running SQL statements Perform the following steps to query the AUTOBODY_EST table: 1. Start iSeries Navigator. 2. Expand Databases and click AUTOBODY under Libraries. 3. On the right side of the iSeries Navigator window click the AUTOBODY_EST table. 4. On the lower right of the iSeries navigator window, under Databases tasks (Figure B-19), click Run an SQL script. Appendix B. Using iSeries Navigator to access DB2 UDB 295 Note: Run an SQL script is available from the Database tasks at the databases, libraries, and tables level. This means if you have a database selected (for example, As06) or a library (for example, AUTOBODY) from iSeries Navigator, you will see same options available under the Database tasks section. Figure B-19 iSeries Navigator - Databases tasks 5. The Run SQL Scripts dialog box shown in Figure B-20 is displayed. 296 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure B-20 Run SQL scripts window 6. Type in the following SQL statement: SELECT estimateid, fname, lname FROM autobody.autobody_est 7. From the pull-down menu click Run -> From Selected. Optionally, you can use CTRL+T to run the SQL statement. The result will be displayed on the Run SQL scripts window as shown in Figure B-21. Note: You need to have your cursor on the line where the executed SQL statements are. Appendix B. Using iSeries Navigator to access DB2 UDB 297 Figure B-21 Query result 8. You can choose to save this query if you want using the pull-down menu options of File -> Save. Using the examples in the Run SQL scripts window Perform the following steps to use the examples available in the Run SQL scripts dialog box: 1. Start iSeries Navigator. 2. Expand the Databases view. 3. Highlight Libraries and click Run an SQL script from Databases tasks. 4. If you cannot remember the syntax of SQL statements, you can take advantage of the drop down list of Examples as shown in Figure B-22. In this example, you can select from the available SQL statements from the list and click the Insert button. 298 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure B-22 Examples drop down list 5. The result is displayed in Figure B-23. You can use this SQL statement as a starting point and edit it to use on the table or column you wish to update. Appendix B. Using iSeries Navigator to access DB2 UDB 299 Figure B-23 Update statement Generating SQL for a table This feature is useful if you want to create a new table based on an existing table. In this example, we generate the SQL statement used to create the EMPLIB.EMPLOYEE table. You can then modify the SQL statement, for example, by modifying the table name to create a new table with the same columns as the EMPLIB.EMPLOYEE table. Perform the following steps to generate the SQL to create a table: 1. Start iSeries Navigator. 2. Expand the Databases view. 3. Click Libraries -> EMPLIB to navigate to the EMPLOYEE table. 4. Right-click the EMPLOYEE table and click Generate SQL (Figure B-24). 300 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure B-24 EMPLIB.EMPLOYEE table 5. A Generate SQL dialog box displayed in Figure B-25 appears. Appendix B. Using iSeries Navigator to access DB2 UDB 301 Figure B-25 Generate SQL dialog box 6. Highlight EMPLOYEE and click Generate. As shown in Figure B-26, the generated SQL is displayed. 302 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure B-26 Run SQL scripts - generated SQL Appendix B. Using iSeries Navigator to access DB2 UDB 303 304 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server C Appendix C. Troubleshooting This appendix discusses the options and tools you have for troubleshooting Lotus Enterprise Integrator (LEI) 6.0.1 activities. This appendix discusses the following tools: Using the LEI log (leilog.nsf) Using the Domino log (log.nsf) Enabling log conflicts in replication activities Logging SQL statements Using the trace metaconnector Using Notes Server Diagnostic (NSD) Using spool file output © Copyright IBM Corp. 2003. All rights reserved. 305 Using the LEI log (leilog.nsf) The LEI log is the most straightforward tool available to troubleshoot an LEI activity. However, it offers the least information about the error. You can access the LEI log using the View Log button from any activity document (see Figure C-1) or the Current Activity Execution Log button from the activity views in the LEI Administrator (see Figure C-2). Figure C-1 View Log button from an activity document Figure C-2 Current Activity Execution Log button When accessing the Log button from the activity views in the LEI Administrator, you must select the activity document to review and then click the Current Activity Execution Log button. 306 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server For example, the highlighted activity document is Test Integrated Credentials. When the log button is clicked from either within the activity document or from the LEI Administrator activities view, the result will be as displayed in Figure C-3. Figure C-3 Activity Log document Another way to retrieve the log document displayed in Figure C-3 is by opening the LEI Log database (leilog.nsf) directly. This database is typically found in the Domino server’s data directory where LEI is installed. All log documents are available from the LEI log views (Figure C-4). Figure C-4 LEI log database Using the Domino log (log.nsf) In some cases, using the LEI log does not provide enough details. Consider this example, we run a scripted activity as in 9.1.1, “Example: Building a direct transfer scripted activity” on page 256 with a minor modification. We have commented out the On Error statement on the RunCaseFileDirectTransfer subroutine listed in Example 9-1 on page 257 as follows: 'On Error Goto ErrHandler Appendix C. Troubleshooting 307 As a result, since we have run the example before, the EMPLIB.CASE_FILE table has been created. If the on error statement is activated, the error handling code will handle the exception by dropping the previously created table and proceeding with creating a new table. Obviously, running the scripted activity in this scenario will result in error. However, upon completion of this activity, the scripted activity appear to have completed successfully. If you click the View Log button of the scripted activity document, the log document will indicate success as depicted in Figure C-5. Figure C-5 LEI log entry for scripted activity Now let’s go to Domino server’s log (log.nsf), which typically resides in the data directory of your Domino server and look for the log document dated around the time you ran the scripted activity. You can find the log document from the Miscellaneous event view as shown in Figure C-6. Figure C-6 Domino server’s log, Miscellaneous view You can double-click the document highlighted in the view to examine the contents. Figure C-7 displays the contents of Domino log document dated 5/29/2003 at 7:07 AM until the current time. Here you can see that an error has occurred and you also have more detailed information about the error. The Domino log is especially useful in scripted activities because you can add messagebox or print statements in the script, which will be displayed in the log document. 308 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Note: Messagebox and print statements are specific to Domino agents. Therefore these statements are only used in a scripted activity using Domino agents. 05/29/2003 10:07:55 Opened session for leidomsvr/ITSO (Release 6.0.1) 05/29/2003 10:07:56 LEI: Activity started 05/29/2003 10:07:57 Agent message: Before executing sqlStmt CREATE TABLE EMPLIB.CASE_FILES ( CASENUM SMALLINT NOT NULL , DATEOPENED DATE DEFAULT NULL , TITLE CHAR(50) CCSID 37 DEFAULT NULL , DESCRIPTION FOR COLUMN DESCR00001 CHAR(100) CCSID 37 DEFAULT NULL , STATUS CHAR(15) CCSID 37 DEFAULT NULL , OPENEDBY CHAR(20) CCSID 37 DEFAULT NULL , ASSIGNEDTO CHAR(20) CCSID 37 DEFAULT NULL , CLIENT CHAR(20) CCSID 37 DEFAULT NULL , CONTACT CHAR(20) CCSID 37 DEFAULT NULL , CONTACTPHONE FOR COLUMN CONTA00001 CHAR(12) 05/29/2003 10:07:57 Agent 'Case Files Direct Transfer' error: Error: CASE_FILES in EMPLIB type *FILE already exists., Connector 'DB2 Connection', Method -Execute(-601) 05/29/2003 10:07:57 LEI: Error: CASE_FILES in EMPLIB type *FILE already exists., Connector 'DB2 Connection', Method -Execute- (-601) 05/29/2003 10:07:57 LEI: Activity finished: CaseFiles_DirectTransfer 05/29/2003 10:07:57 LEI: Activity finished 05/29/2003 10:07:57 Closed session for leidomsvr/ITSO|Databases accessed: 2 Documents read: 0 Documents written: 0 05/29/2003 10:08:04 LEI: Activity finished: Direct Transfer Scripted Activity for Case Files 05/29/2003 10:08:04 LEI: Activity finished Figure C-7 Domino log document Enabling log conflicts in replication activities In the replication activity document you have the option to enable conflict logging. This option is available through the Replication Options tab, Conflict Options sub-tab (Figure C-8). By enabling this option, you can use the entries created in the activity log to troubleshoot the problem. Logging entries will also appear in your Domino server console. Figure C-8 Enable conflict logging in a replication activity document The Logging Options specify how conflict logging will be performed. As Event - logs conflicts as errors in the activity log. As Error and Continue - logs conflicts as errors in the activity log, but continues the replication activity. As Error and Stop - logs conflicts as errors in the activity log and stops the replication activity. Appendix C. Troubleshooting 309 Note: Using the As Error options is slower, since each log entry is written to disk. Using the As Event option is much faster and is recommended for production environments. The Limit to field is used to limit logged conflicts to a useful number for the given activity. When this number of conflicts has been logged, additional conflicts are not added to the activity log. The default is 500. Specifying a value of zero indicates no limit (log all conflicts). Figure C-9 shows an example of the output in the activity log. 05/12/2003 04:03:22 PMActivity started 05/12/2003 04:03:24 PMCreated temporary Notes view '(LEIIndexView0)' ** Supply a view name to create a more efficient permanent view, Connector 'Qcustcdt.nsf Notes Conn', Method -Select05/12/2003 04:03:24 PMTrace Statement: <SELECT CUSNUM,LSTNAM,INIT,STREET,CITY,STATE,ZIPCOD,CDTLMT,CHGCOD,BALDUE,CDTDUE FROM mgilley.qcustcdt2 ORDER BY LSTNAM>, Connector 'RCHASSLH', Method -Select05/12/2003 04:03:24 PMTrace Statement: <SELECT * FROM mgilley.qcustcdt2 WHERE 0 = 1>, Connector 'RCHASSLH', Method -Insert05/12/2003 04:03:24 PMTrace Statement: <INSERT INTO mgilley.qcustcdt2 (CUSNUM,LSTNAM,INIT,STREET,CITY,STATE,ZIPCOD,CDTLMT,CHGCOD,BALDUE,CDTDUE) VALUES (?,?,?,?,?,?,?,?,?,?,?) >, Connector 'RCHASSLH', Method -Insert05/12/2003 04:03:24 PM*Replication Conflict* Action: Insert into Connector B; Record key values: LSTNAM = "1A" 05/12/2003 04:03:24 PM*Replication Conflict* Action: Insert into Connector B; Record key values: LSTNAM = "1B" 05/12/2003 04:03:24 PM*Replication Conflict* Action: Insert into Connector B; Record key values: LSTNAM = "1C" 05/12/2003 04:03:24 PMTrace Statement: <DELETE FROM mgilley.qcustcdt2 WHERE LSTNAM=?>, Connector 'RCHASSLH', Method -Remove05/12/2003 04:03:24 PM*Replication Conflict* Action: Remove from Connector B; Record key values: LSTNAM = "1A" 05/12/2003 04:03:24 PM*Replication Conflict* Action: Remove from Connector B; Record key values: LSTNAM = "1B" 05/12/2003 04:03:24 PM*Replication Conflict* Action: Remove from Connector B; Record key values: LSTNAM = "1C" 05/12/2003 04:03:24 PMActivity finished Figure C-9 Conflict logging output Logging SQL statements In DB2 connection documents, you have the option to output SQL statements to the activity log. This option is available through the Logging Options tab under the Connectivity section (Figure C-10). This option is useful in troubleshooting if you want to inspect the generated SQL statements. Figure C-10 Output SQL statements to log 310 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server This causes the SQL statements to be printed out in the activity log document when the activity that uses that connection document is started. Figure C-11 shows an example activity log of a timestamp replication activity. Figure C-11 Outputing SQL to an activity log Note: If your SQL statement is larger than 512 bytes, it will cause a Domino server panic. There is a hotfix available for this problem. You can contact Lotus Support for the hotfix. Another option or work-around to prevent the server panic is by not enabling the output SQL statements to log option from your DB2 connection document. Using the trace metaconnector The trace metaconnector allows you to trace events associated with a specified sub connection. You may specify options including where to capture data (either to the LEI console or to a user-specified file name) and whether or not to include a timestamp with each trace log entry. If there is a problem with your activity or connection, the trace metaconnector is a tool for you to use when troubleshooting. Also, trace output is useful for Lotus support staff when troubleshooting customer calls. For more information about using the trace metaconnector, refer to 6.5.4, “Trace metaConnector” on page 179. Using Notes Server Diagnostic (NSD) The NSD is a Lotus tool designed to gather information about a failing Domino server. This tool is very useful for studying Domino server crashes. You can read an NSD file in two ways: Use the Display File (DSPF) CL command or the Display Stream File (DSPSTMF) CL command. Display the file by using any ASCII editor on your workstation. In order to do this, you need to first download the file to your workstation. Appendix C. Troubleshooting 311 For more details about NSDs, refer to Chapter 3.2.4 of the Lotus Domino for AS/400: Problem Determination Guide, SG24-6051. This redbook is available to download from: http://www.redbooks.ibm.com/ Using spool file output Output queues are areas where printer output files (also called spool files) wait to be processed and sent to the printer. Printer output is created either by the system or by the user using a print file. For troubleshooting LEI problems, we are mostly interested in spool files generated by the QNOTES user profile. All Lotus Domino functionality runs under the QNOTES user profile on the iSeries server. These logs have more details about LEI activities and can be very useful for troubleshooting if other tools (like the LEI log or Domino server log) do not provide enough information. Using the OS/400 command line interface To find spool files generated by the QNOTES user profile through the OS/400 command line interface, perform the following steps: 1. From an OS/400 command line, issue the following Work with Spool Files CL command and press Enter: WRKSPLF QNOTES 2. This will produce the results you see in Figure C-12. Work with All Spooled Files Type options, press Enter. 1=Send 2=Change 3=Hold 4=Delete 5=Display 8=Attributes 9=Work with printing status Opt File QPRINT QPRINT QPRINT QPRINT QPRINT QPRINT QPRINT QPRINT QPRINT User QNOTES QNOTES QNOTES QNOTES QNOTES QNOTES QNOTES QNOTES QNOTES Device or Queue QPRINT QPRINT QPRINT QPRINT QPRINT QPRINT QPRINT QPRINT QPRINT User Data 6=Release Sts RDY RDY RDY RDY RDY RDY RDY RDY RDY Total Pages 1 1 1 1 1 1 1 1 1 7=Messages Cur Page Copy 1 1 1 1 1 1 1 1 1 More... Parameters for options 1, 2, 3 or command ===> F3=Exit F10=View 4 F11=View 2 F12=Cancel F22=Printers F24=More keys Figure C-12 Results of issuing the WRKSPLF QNOTES CL command 3. By pressing the F18 key you can navigate to the bottom of the listing to find the most recent spool files. 4. If the error just occurred, select option 5 next to the spool file and press Enter to view the contents of the file. 5. You will see a screen, such as that shown in Figure C-13. 312 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Display Spooled File File . . . . . : QPJOBLOG Page/Line 1/1 Control . . . . . Columns 1 - 78 Find . . . . . . *...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+... 5722SS1 V5R2M0 020719 Display Job Log Job name . . . . . . . . . . : QSQSRVR User . . . . . . : QUSER Job description . . . . . . : QDFTJOBD Library . . . . . : QGPL MSGID TYPE SEV DATE TIME FROM PGM CPF1124 Information 00 05/20/03 16:04:00.746560 QWTPIIPP Message . . . . : Job 035156/QUSER/QSQS in subsystem QSYSWRK in QSYS. Job enter CPD0912 Diagnostic 20 06/02/03 14:02:07.730208 QWTCHGJB Message . . . . : Printer device PRT01 Cause . . . . . : The printer device wa Either create the printer device (CRTDE device name is not correct, change the command again. CPF1336 Escape 40 06/02/03 14:02:07.730408 QWTCHGJB Message . . . . : Errors on CHGJOB comm Recovery . . . : See the messages list More... F3=Exit F12=Cancel F19=Left F20=Right F24=More keys Figure C-13 Displaying spool file contents 6. To make the information more easily viewable, place your cursor in the Control field in the upper left corner of the spool file display and type in W 38 and press Enter. This will shift the contents on the screen 38 characters to the right, making the contents more readable. An example of the output is shown in Figure C-14. Display Spooled File File . . . . . : QPJOBLOG Page/Line 3/1 Control . . . . . Columns 38 - 115 Find . . . . . . ..4....+....5....+....6....+....7....+....8....+....9....+....0....+....1....+ Display Job Log AS06 06/02/03 10:25:11 QSRVR User . . . . . . : QUSER Number . . . . . . . . . . . FTJOBD Library . . . . . : QGPL V DATE TIME FROM PGM LIBRARY INST TO PGM LI Message . . . . : Authorization failure on distributed database connection attempt. Cause . . . . . : A connection attempt failed with reason code 6. The reason codes and their meanings are as follows: 0 -- Unknown cause. 1 -- Password expired. 2 -- Password not valid. 3 -- Password missing. 4 -- Protocol violation. 5 -- User ID not found. 6 -- User ID not valid. For a DB2 UDB for iSeries server, this could mean a damaged user profile or PASSWORD(*NONE). 7 -- User ID revoked or disabled. 15 -- Security processing at the server failed. 16 -- The new password is not valid. 17 -- The security mechanism requested by the client is not supported or allowed at the server. See recovery information below. 22 -- Security processing at the client failed. 23 -- CCSID conversion of the password failed. Recovery . . . : Correct More... F3=Exit F12=Cancel F19=Left F20=Right F24=More keys Figure C-14 Use the W 38 control command to shift the screen contents 38 characters to the right Appendix C. Troubleshooting 313 7. Scroll down in the spool file until you find more details about what is causing the problem you encountered when attempting to execute the LEI activity. In the example shown in Figure C-14, there is a an authorization error. A reason code of 6 is provided. You can use this information to determine what course of action to take. Using iSeries Navigator Alternatively you can locate the spool files associated with the QNOTES user profile through iSeries Navigator. To do this, perform the following steps: 1. Start iSeries Navigator. 2. From My Connections, expand your iSeries server (in our example this is As06) and expand Users and Groups -> All Users and locate the QNOTES user profile. See Figure C-15. Figure C-15 Navigating to the QNOTES user profile with iSeries Navigator 3. Right-click the QNOTES user profile and click User Objects -> Printer Output as shown in Figure C-16. 314 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Figure C-16 Selecting to view the output for the QNOTES user profile 4. This will produce a separate window as shown in Figure C-17. In this window, double-click the spool file you wish to view. Figure C-17 Displaying the QNOTES user profile spool files Appendix C. Troubleshooting 315 5. You will see the contents of the spool file as displayed in Figure C-18. Figure C-18 Contents of the QNOTES spool file in the iSeries Navigator viewer 316 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server D Appendix D. Additional material This redbook refers to additional material that can be downloaded from the Internet as described below. Locating the Web material The Web material associated with this redbook is available in softcopy on the Internet from the IBM Redbooks Web server. Point your Web browser to: ftp://www.redbooks.ibm.com/redbooks/SG246941 Alternatively, you can go to the IBM Redbooks Web site at: ibm.com/redbooks Select the Additional materials and open the directory that corresponds with the redbook form number, SG246941. Using the Web material The additional Web material that accompanies this redbook includes the following files: File name autobody.savf DominoDBs.zip emplib.savf Description Save file containing the AUTOBODY OS/400 library Zipped file containing the Domino databases (AutoBodyDemo.nsf, casefile.nsf, employee.nsf, and medrec.nsf) Save file containing the EMPLIB OS/400 library How to use the Web material Create a subdirectory (folder) on your PC workstation, download the three files to this folder and unzip the contents of the DominoDBs.zip file into this folder. Refer to Chapter 7, “Setting up the examples environment” on page 183 for details about setting up this material to be used to run the examples in this redbook. © Copyright IBM Corp. 2003. All rights reserved. 317 318 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Related publications The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this redbook. IBM Redbooks For information on ordering these publications, see “How to get IBM Redbooks” on page 320. Note that some of the documents referenced here may be available in softcopy only. Data Sorting Considerations with IBM Lotus Enterprise Integrator (LEI) 6 on the IBM ~ iSeries Server, REDP-3707 IBM Lotus Domino 6 for iSeries Implementation, SG24-6592 Performance Considerations for Domino Applications, SG24-5602 Advanced Functions and Administration on DB2 Universal Database for iSeries, SG24-4249 Lotus Notes and Domino R5.0 Security Infrastructure Revealed, SG24-5341 Other publications These publications are also relevant as further information sources: Indexing Strategies for DB2 UDB for iSeries white paper: http://www.ibm.com/servers/eserver/iseries/developer/bi/documents/strategy/strategy.html All of the LEI publications available from Lotus can be downloaded from the IBM Lotus Developers Domain Documentation Library at: http://www.lotus.com/ldd/doc These publications are located under the Enterprise Integrator product title: IBM Lotus Enterprise Integrator for Domino (LEI) 6.0.1 Release Notes IBM Lotus Enterprise Integrator for Domino (LEI) Installation Guide IBM Lotus Enterprise Integrator for Domino (LEI) Activities and User Guide Lotus Connectors and Connectivity Guide Release notes, white papers, and informative links are also found at this location. Each release of LEI contains its own page of documentation. Online resources These Web sites and URLs are also relevant as further information sources: Lotus Enterprise Integration http://www.lotus.com/ei Lotus Developer Domain LDD Today © Copyright IBM Corp. 2003. All rights reserved. 319 http://www.lotus.com/ldd/today.nsf iSeries Information Center http://www.ibm.com/eserver/iseries/infocenter iSeries performance resources http://www.ibm.com/servers/eserver/iseries/perfmgmt/resource.htm DRDA and DB2 Information Integrator http://www.ibm.com/eserver/iseries/db2 LEI: Addressing Sort Order Issues when Replicating DB2/400 Data to a Notes Database, Technote 110127 http://www.ibm.com/support/docview.wss?uid=swg21101027 How to get IBM Redbooks You can search for, view, or download Redbooks, Redpapers, Hints and Tips, draft publications and Additional materials, as well as order hardcopy Redbooks or CD-ROMs, at this Web site: ibm.com/redbooks 320 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Index A accessing multiple relational databases 35 activity documents 6 Add Relational Database Directory Entry command 105, 107 ADDRDBDIRE 105, 107 admin-backup activity 7, 273 administering 76 Administrator database 77 admin-purge log activity 7, 273 Advanced RealTime activities 8, 11, 195 decentralized access 31 hub and spoke environment 33 performance 41 persistent connections 47 user assistance 115 user assistant wizard 6 using virtual fields with virtual documents 204 Advanced RealTime features integrated credentials 10, 37 virtual attachments 10 Advanced RealTime user assistance 79 advantages of virtual documents 203 agent 16, 205 Application Requester (AR) 104 Application Server (AS) 104 architectural scenarios 26 archive activity 7, 272 authority propagation activity 14 autobody demo example database 190 AUTOBODY library 184, 188 AUTOBODY.AUTOBODY_DAMAGE table 188, 237 AUTOBODY.AUTOBODY_EST table 189, 237 AUTOBODY.DAMAGETOT stored procedure 238 autobodydemo.nsf 190, 237 B base connectors 5 batch activities 7, 255 performance 42 business case for LEI 2 C capture delete support in a replication activity 14 case files example database 192 CASE_FILES table 186 casefile.nsf 192, 257 CCSID 146 CFGTCP 59, 109 CGI interface 13 Change Owner command 59, 190 CHGOWN 59, 190 clustering 83 © Copyright IBM Corp. 2003. All rights reserved. considerations when removing LEI 276 migrating 89 coded character set identifier 146 collapse/expand metaconnector 6, 174 collection 15 column 16 command activity 7, 273 commit 155 comparisons 9 Configure TCP/IP command 59, 109 configuring 80 collapse/expand metaconnector 175 DB2 connection document 154 File connection document 167 integrated credentials 37 LEI cluster 83 local relational database directory entry 105 meter metaconnector 176 Notes connection document 158 order metaconnector 178 remote DRDA connection 109 Text connection document 169 trace metaconnector 179 connection broker metaconnector 12 connection documents 5, 16, 153 DB2 154 DB2 UDB on pSeries server 151 File 166 generic user ID and password 36 Notes 157 Text 169 connection pooling 45 connectivity 104 configuring remote DRDA connection 109 CONTEST utility 180 DCTEST utility 117, 138, 148 iSeries to iSeries 105 iSeries to pSeries 140 ping utility 109 remote DB2 UDB database 104 testing 117, 138, 148 connectivity test tool 12 connectors 5 considerations DB2 UDB performance 44 external key table 198 implementing integrated credentials 40 performance 41 removing LEI 276 security 36 console commands 77 CONTEST utility 180 creating DB2 connection document 206, 217, 224, 226, 232, 238, 240, 242, 267 321 external key table 213, 222 global DB2 connection document 207 iSeries library using iSeries Navigator 288 Notes connection document 256, 266 replication activity document 269 script in the script vault 257 scripted activity 262 virtual agents activity 248 virtual documents activity 208, 219, 234, 243 virtual fields activity 228–229, 236, 246 D DAMAGETOT example stored procedure 188 Data Connection Resources 4 data description specification 15 data journaling 155, 207 data sources 5, 153 data type conversions/mappings 18 data types Domino Designer 20 iSeries physical file 19 iSeries SQL 18 mapping guidelines 21 database 15 database journal 294 Database Server (DS) 104 DB2 connection document 154, 206, 217, 224, 226, 232, 238, 240, 242, 267 logging SQL statements 310 DB2 Data Joiner 104 DB2 Information Integrator 104 DB2 UDB accessing from iSeries Navigator 285 iSeries terminology differences 17 performance 44 using virtual fields with multiple DB2 UDB tables 224 DB2 UDB client errors encountered 139 DB2 UDB view 216 DCRs 4 comparison with DECS and LEI 9 DCTEST utility 12, 117, 138, 148 DDM 105 port number 111 verifying if active 110 DDS 15 DECS 4, 55 comparison with DCRs and LEI 9 reinstating 276 decsadm.nsf 13, 55, 77, 88 decsadmn.nsf 276 deleting virtual documents 199 deletion stub 199 DEPARTMENT example table 186 DestTimeStamp 265 development client 11 differences between virtual documents and virtual fields 203 direct transfer activity 7, 273 performance 42 Display Data Area command 53 322 Display PTF command 53 Display Software Resources command 51 displaying iSeries library using iSeries Navigator 290 Distributed Relational Database Architecture 104 document 16 Domino Designer data types 20 Domino Enterprise Connection Services 4, 55, 276 comparison with DCRs and LEI 9 Domino log 307 Domino replication with virtual documents 200 Domino soft deletions 200 DRDA 29, 104 port number 111 verifying if active 110 DSPDTAARA 53 DSPPTF 53 DSPSRWRSC 51 E EDA/SQL connector 12 EICONTENTS 205 EIDBID 205 EIFILEID 205 EIFILENAME 205 EIFILESIZE 205 EIMODIFIED 42, 198 EINOTEID 42, 198 EINOTEPROPS 198 EIUNID 42, 198, 205 e-mail activity log files 14 EMPLIB library 184 EMPLIB.DEPARTMENT table 224, 231 EMPLIB.EMP_DEPT view 187, 216 EMPLIB.EMPLOYEE table 187, 206, 224 EMPLIB.EMPLOYEE2 table 187, 231 EMPLIB.PATIENT table 266 employee examples database 192 employee.nsf 192, 206, 216, 224, 231 encryption 40 Enterprise Connector Products/Lotus Notes Companion Products user 56 enterprise integration strategy 2 ERP back-end data sources 5 errors with DB2 UDB client 139 event options 202 virtual documents activity 201 examples 183 building a direct transfer scripted activity 256 timestamp replication 266 using a virtual documents activity 206 using virtual agents and virtual attachments 237 using virtual documents with a DB2 UDB view 216 using virtual fields with multiple DB2 tables 224 using virtual fields with virtual documents 231 external key table 41, 197 considerations 198 creating 213, 222 indexing 42 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server F field 16 File connection document 166 file separators 18 form 15 G generating key documents 229 generating SQL for a table 300 global DB2 connection document 207 H hardware 50 help databases 83 leidoc.nsf 198 lsxlc6.nsf 256 I indexing 199 external key table 42 internal keys 42 Informix 35 infrastructure 26 initialize keys 202, 229 installing 60 checklist 60 pre-installation activities 56 prerequisites 50 integrated credentials 10, 14, 37 configuring 37 implementation considerations 40 performance 10, 41 using in Advanced RealTime activity 39 integration with Domino R5 applications 29 internal key table 197 internal keys 41 indexing 42 introduction to LEI 2, 4 iSeries active ports 111 configuring remote DRDA connection 109 connecting from iSeries Navigator 286 connection to another iSeries 105 connectivity to pSeries 140 database 17 hardware requirements 50 library 18, 288 native physical file data types 19 output queues 312 physical file 292 PTFs 52 relational database 15 remote DB2 UDB database 104 software requirements 50 spool files 312 SQL data types 18 table 292 TCP/IP configuration 59 iSeries Navigator 285 checking for journaling 294 connecting to an iSeries server 286 creating a library 288 displaying a library 290 displaying spool files 314 generating SQL for a table 300 running SQL scripts 295 viewing the contents of a table 292 iSetupInstall.exe 60 iSetupMigration.exe 92 iSetupUninstall.exe 277 J Java activity 7, 273 journaling 155, 207, 294 K Kerberos 116 key documents 202 generating 229 L LC Java classes 7 LC LSX 7, 88, 256 lcired.ntf 14 LCTEST 12 LEI Administrator database 77 clustering 83 comparison with DECS and DCRs 9 connection documents 153 CONTEST utility 180 development client 11 help databases 83 installation checklist 60 integration with Domino R5 applications 29 introduction 2, 4 limitations 8 migrating from LEI 3.x 70 migration utility 13 multiple platforms 30 performance 41 performance spectrum 43 prerequisites 50 product tied to release boundary 11 removing 275 scenarios 26 script vault 13 scripted agent database 83 security 36 server-side browsing 11 troubleshooting 305 uninstalling 277 user assistance 79, 115 what’s new with LEI 6 and LEI 6.0.1 11 LEI 6.0.1 on iSeries server 14, 195 removing 275 Index 323 troubleshooting 305 LEI Administrator Configuration document 82 LEI Administrator database 13 LEI log file 306 LEI LSX 88 LEI server administering 76 configuring 80 console commands 77 installing 60 log file 79 migrating 92 pre-installation activities 56 starting 85 stopping 85 upgrading from LEI 3.x 88, 92 LEI Server Configuration document 80 LEI.INI 12 leiadm.nsf 13, 88 leidoc.nsf 198 leilog.nsf 306 leivlt.nsf 88 leivlt6.nsf 13, 88, 257 library 15, 18, 184, 288 limitations 8 limitations of virtual documents 203 Load and Run command 50 local relational database directory entry 105 LODRUN 50 log file 79, 82 log.nsf 307 logical file 16 Lotus Connector Lotus Script Extension Guide 256 LotusScript Extensions for Lotus Connectors 7, 88, 256 lsxlc6.nsf 256 M maximum connections 215, 223 medical records example database 193 medrec.nsf 193, 266 metaconnection documents migrating 89 metaconnectors 6, 174 metadata 15 meter metaconnector 6, 176 Microsoft SQL server 35 migrating 70, 72, 92 considerations 88 duplicate connection or activity documents 89 LEI clustering 89 log file 102 metaconnection documents 89 pre-migration activities 90 remote administration 89 scripted documents 88 troubleshooting 101 migration utility 13, 72, 96 migration.log file 102 mixed alpha-numeric key 266 monitor order 202, 229 324 multiple platforms 30 multiple relational databases 35 multi-value data 238, 247 N ndctest.exe 138, 148 NETSTAT 110 Note IDs for virtual documents 215 Notes connection document 157, 256, 266 Notes Server Diagnostic 311 NotesPump 4 NSD 311 O Oracle 35 order metaconnector 6, 177, 266 output queues 312 owner 15 P PATIENT table 187 performance 41 batch activities 42 connection pooling 45 DB2 UDB considerations 44 direct transfer activity 42 first time start on virtual document activity 42 integrated credentials 10, 41 internal keys verses external key table 41 persistent connections 41, 47 remote database server 42 timestamp replication 42 virtual documents maximum connections 215, 223 performance spectrum 43 persistent connections 41, 47 physical file 16, 292 ping utility 109 polling activity 7, 264, 273 ports 111 pre-installation activities 56 premium connectors 5 prerequisites 50 primary key replication 264 problem determination DB2 UDB client 139 migrating 101 Program Temporary Fixes 52 pSeries server creating a connection document 151 PTFs 52 Q query 17 R RAWT daemon 60, 63, 279 RDBDIRE 105 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server record 16 record format 15 Redbooks Web site 320 Contact us xiv reinstating DECS 276 relational database directory entry 17 releases 11 remote administration 83 migrating 89 remote database server 27 performance 42 remote DB2 UDB database 104 removing LEI 275 replication activity 7, 264 creating 269 enabling conflict logging 309 example of timestamp replication 266 mixed alpha-numeric key 266 primary key replication 264 timestamp replication 264 replication with virtual documents 200 requirements hardware 50 PTFs 52 software 50 workstation 52 rollback 155 row 16 running SQL scripts 295 S SAP connector 6 scenarios 26 accessing multiple databases from iSeries 35 Advanced RealTime in a hub and spoke 33 decentralized Advanced RealTime access 31 integration with Domino R5 applications 29 performance spectrum 43 remote database server 27 single iSeries server 26 schema 18 script vault 13 creating script 257 scripted activity 7, 256 creating 262 example 256 scripted agent database 83 scripted documents 88 security 36 encryption 40 selection formula 17 server-side browsing 11 setting up examples 183 software 50 sort sequences 266 spool files 312 SQL 104 SQL data types 18 SQL scripts 295 SrcTimeStamp 265 Start Host Server command 109 Start TCP/IP command 109 starting 85 statement 17 stopping 85 stored procedures 13, 16, 188, 205 STRHOSTSVR 109 STRTCP 109 subkey fields 247 Sybase 35 T table 16, 18, 292 generating SQL 300 TCP/IP configuration 59 terminology 15 testing connectivity 117, 138, 148 Text connection document 169 timestamp polling 12 timestamp replication 264 example 266 performance 42 trace metaconnector 6, 179, 311 trace.log 180 troubleshooting 305 CONTEST utility 180 DB2 UDB client 139 enabling log conflicts in replication activities 309 leilog.nsf 306 log.nsf 307 logging SQL statements 310 migrating 101 Notes Server Diagnostic (NSD) 311 trace metaconnector 179, 311 using spool file output 312 U uninstalling LEI 277 upgrading 88, 92 user assistance 79, 115 user assistant wizard 6 using virtual fields with virtual documents example 231 V view 16, 187 viewing the contents of a table 292 virtual agents activity 8, 195, 205 creating 248 example 237 virtual attachments 10, 195, 204 example 237 virtual attachments table 205 virtual documents activity 8, 195–196 advantages 203 creating 208, 219, 234, 243 deleting 199 differences with virtual fields 203 Domino replication 200 Index 325 EIMODIFIED 42, 198 EINOTEID 42, 198 EINOTEPROPS 198 EIUNID 42, 198 event options 201 example 206 example using with virtual fields 231 external key table 197 external key table considerations 198 first time start 42 indexing 199 internal key table 197 limitations 203 maximum connections 215, 223 Note IDs 215 performance 41 using with a DB2 UDB view 216 using with virtual fields 204 virtual fields activity 8, 195, 201 creating 228–229, 236, 246 differences with virtual documents 203 event options 202 example with multiple DB2 UDB tables 224 example with using virtual documents 231 generating key documents 229 initialize keys 202, 229 key documents 202 monitor order 202, 229 multi-value data 238, 247 subkey fields 247 using with virtual documents 204 virtualization 3 W Work with Authority command 59, 190 Work with PTF Groups command 54 Work with Relational Database Directory Entries 17, 107 Work with TCP/IP Network Status command 110 workstation requirements 52 WRKAUT 59, 190 WRKPTFGRP 54 WRKRDBDIRE 17, 107 Z ZID file 169 326 Implementing IBM Lotus Enterprise Integrator 6 on the IBM eServer iSeries Server Implementing IBM Lotus Enterprise Integrator 6 on the IBM ~ iSeries Server (0.5” spine) 0.475”<->0.873” 250 <-> 459 pages Back cover ® Implementing IBM Lotus Enterprise Integrator 6 on the IBM Architecting and designing enterprise solutions using LEI 6 Installing and administering LEI 6 on the iSeries server Getting the most out of the Advanced RealTime activities iSeries Server This IBM Redbook helps you to implement Lotus Enterprise Integrator (LEI) 6 on the IBM ~ iSeries server. It is targeted for system administrators who plan to implement or upgrade to LEI 6 in their organization. The redbook provides tips and techniques to help you successfully deploy and administer LEI 6 on an iSeries server. We begin by providing a brief introduction to what’s new with LEI 6 and cover some architectural scenarios of how the LEI 6 infrastructure could be implemented in a customer’s environment. We then provide detailed information about how to install and administer LEI 6 on the iSeries server. Migrating or upgrading from LEI 3.x is also covered. This redbook also provides some basic connectivity information about how to connect one iSeries server to another as well as from iSeries to pSeries and xSeries to iSeries. Finally this redbook provides some working examples of how to use the Advanced RealTime activities that are new in LEI 6. It also provides examples of some of the batch activities previously available in LEI 3.x, such as a scripted activity and a replication activity. INTERNATIONAL TECHNICAL SUPPORT ORGANIZATION BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment. For more information: ibm.com/redbooks SG24-6941-00 ISBN 0738453277