Download Implementing IBM Lotus Lotus Enterprise Integrator 6 grator 6

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