lotus solutions for the enterprise, volume 2 using db2 in a

SG24-4918-00

International Technical Support Organization

http://www.redbooks.ibm.com

Lotus Solutions for the Enterprise, Volume 2Using DB2 in a Domino Environment

Christophe Toulemonde, Jakob Gabathuler, Brendan JansenLaura Rossini, John Wylie, Lancelot Schaper

Lotus Solutions for the Enterprise, Volume 2Using DB2 in a Domino Environment

November 1998

SG24-4918-00

International Technical Support Organization

© Copyright International Business Machines Corporation 1998. All rights reservedNote to U.S Government Users – Documentation related to restricted rights – Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

First Edition (November 1998)

This edition applies to Domino Release 4.6, DB2 Universal Database Version 5.0, and their existing connectors

Comments may be addressed to:IBM Corporation, International Technical Support OrganizationDept. QXXE Building 80-E2650 Harry RoadSan Jose, California 95120-6099

When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you.

Before using this information and the product it supports, be sure to read the general information in Appendix H, “Special Notices” on page 193.

Take Note!

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ix

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

The Team That Wrote This Redbook . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv

Lotus Solutions for the Enterprise Collection . . . . . . . . . . . . . . . . . . . .xviComments Welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Chapter 1. Lotus Notes and Domino . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 Domino Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Lotus Notes Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.3 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.4 Lotus Notes Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2. Lotus NotesPump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.1 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2 NotesPump Administrator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 3. DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.1 Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.2 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.3 Programming DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.4 DB2 object extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.4.1 User-defined Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163.4.2 User-defined Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163.4.3 Binary Large Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.5 Distributed Relational Database Architecture . . . . . . . . . . . . . . . . . . . 183.5.1 Roles of DRDA Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193.5.2 Degrees of Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.6 The DB2 Family . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203.6.1 Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213.6.2 DB2 Client Application Enabler . . . . . . . . . . . . . . . . . . . . . . . . . . 223.6.3 DB2 Software Developer’s Kit. . . . . . . . . . . . . . . . . . . . . . . . . . . 233.6.4 DB2 Connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233.6.5 Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Chapter 4. Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254.1 DBMS Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254.2 Lotus Notes Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

© Copyright IBM Corp. 1998 iii

4.3 Do the Replications Differ?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 5. Development Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295.1 Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

5.1.1 Java Applets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305.1.2 Java Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315.1.3 Java Servlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

5.2 Domino Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . 325.2.1 Formulas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335.2.2 LotusScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335.2.3 Java Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355.2.4 JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365.2.5 Web Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

5.3 Application Programming Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . 375.3.1 Open Database Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . 375.3.2 DB2 Call Level Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405.3.3 Java Database Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415.3.4 DB2 Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Chapter 6. Platforms and Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . 436.1 Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446.2 Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466.3 From Domino to DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Chapter 7. Integrating DB2 and Domino . . . . . . . . . . . . . . . . . . . . . . . . 517.1 The Power of Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517.2 Successful DB2 and Domino Integration . . . . . . . . . . . . . . . . . . . . . . 55

Chapter 8. Methods of Integration between Domino and DB2 . . . . . . . 578.1 @DbFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

8.1.1 Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588.1.2 Technical Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

8.2 LotusScript Data Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598.2.1 Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598.2.2 Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608.2.3 Technical Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

8.3 DB2LSX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628.4 Lotus Domino Connector LSX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648.5 Java and JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658.6 Domino Enterprise Connection Services . . . . . . . . . . . . . . . . . . . . . . 678.7 NotesPump and Lotus Enterprise Integrator . . . . . . . . . . . . . . . . . . . . 698.8 MQSeries and CICS Connections for Domino . . . . . . . . . . . . . . . . . . 708.9 Programmatic Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

iv Using DB2 in a Domino Environment

Chapter 9. Choosing the Right Tool or Product . . . . . . . . . . . . . . . . . . 739.1 Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739.2 Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

9.2.1 Application Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749.2.2 Data Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789.2.3 Environment Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Chapter 10. Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8310.1 Millennium Cafe Sales Tools Plus Application . . . . . . . . . . . . . . . . . 8310.2 DB2 CAE Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8510.3 DB2 Connect Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8710.4 Binding the DB2 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8910.5 Domino Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9010.6 ODBC Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9210.7 LS:DO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9310.8 DB2LSX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9310.9 Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

10.9.1 Java Development Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9410.9.2 Java Servlet Development Kit . . . . . . . . . . . . . . . . . . . . . . . . . . 9410.9.3 JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9410.9.4 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9510.9.5 Java Servlet and Domino Server . . . . . . . . . . . . . . . . . . . . . . . 96

10.10 LC LSX and DECS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9710.11 NotesPump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Chapter 11. Programming the Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . 10111.1 Millennium Cafe Java Sales Tools Plus Application Structure. . . . . 101

11.1.1 Query and Update Employee Options . . . . . . . . . . . . . . . . . . . 10311.1.2 Sales Reporting Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

11.2 LotusScript Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10611.2.1 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10611.2.2 Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

11.3 @DbFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10911.3.1 @DbColumn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10911.3.2 @DbLookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11011.3.3 @DbCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11211.3.4 IDs and Passwords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

11.4 LS:DO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11311.4.1 A Step-by-Step Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

11.5 DB2LSX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11911.5.1 A Step-by-Step Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

11.6 Lotus Domino Connector LSX . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12511.6.1 A Step-By-Step Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

v

11.7 DB2 Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12911.8 JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

11.8.1 Distributing and Running a JDBC Applet. . . . . . . . . . . . . . . . . 13211.8.2 Creating a Java Server Agent, Using JDBC . . . . . . . . . . . . . . 13211.8.3 Running a JDBC Java Server Agent . . . . . . . . . . . . . . . . . . . . 13411.8.4 Creating a Java Servlet, Using JDBC . . . . . . . . . . . . . . . . . . . 13611.8.5 Java Development Environment . . . . . . . . . . . . . . . . . . . . . . . 140

11.9 DECS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14111.9.1 Lotus Connection Document . . . . . . . . . . . . . . . . . . . . . . . . . . 14111.9.2 Realtime Activity Document . . . . . . . . . . . . . . . . . . . . . . . . . . 14311.9.3 Running the Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

11.10 NotesPump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14711.10.1 Links. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14711.10.2 Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

11.11 Programmatic Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15111.11.1 Domino Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15211.11.2 DB2 Dynamic Link Library . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Chapter 12. Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15512.1 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

12.1.1 Domino Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15512.1.2 Lotus Notes Client Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15612.1.3 Web Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15612.1.4 Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15712.1.5 DB2 Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15712.1.6 NotesPump. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15812.1.7 User Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

12.2 Backup and Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16012.3 Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Appendix A. LotusScript Data Option Agent . . . . . . . . . . . . . . . . . . . . . 163A.1 LoadEmployeeODBCDB2 Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163A.2 UpdateEmployeeODBCDB2 Agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Appendix B. DB2LSX Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169B.1 LoadEmployeeDB2BLOB Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Appendix C. Lotus Connector LSX agent . . . . . . . . . . . . . . . . . . . . . . . 173C.1 LoadEmployeeDB2LDC Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

Appendix D. JDBC Agent and Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . 175D.1 LoadEmployeeNative Java Server Agent . . . . . . . . . . . . . . . . . . . . . . . . 175D.2 ReportServletNative Java Servlet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

vi Using DB2 in a Domino Environment

Appendix E. Stored Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183E.1 Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183E.2 Registration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Appendix F. C Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Appendix G. DB2 for Domino . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Appendix H. Special Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Appendix I. Related Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197I.1 International Technical Support Organization Publications . . . . . . . . . . . 197I.2 Redbooks on CD-ROMs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197I.3 Other Publications and Web Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

I.3.1 Domino. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198I.3.2 DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

How to Get ITSO Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201How IBM Employees Can Get ITSO Redbooks . . . . . . . . . . . . . . . . . . . . . . . 201How Customers Can Get ITSO Redbooks. . . . . . . . . . . . . . . . . . . . . . . . . . . 202IBM Redbook Order Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

List of Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

ITSO Redbook Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

vii

viii Using DB2 in a Domino Environment

Figures

1. NotesPump Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82. Servlet Process Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323. Open Database Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384. DB2 CLI and ODBC Drivers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405. Stored Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426. From the User Workstation to the Database, Using Domino . . . . . . . . . . . 437. Local Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488. DB2 Universal Database Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489. DB2 DRDA Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4910. @DbFunction Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5811. LS:DO Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6012. DB2's JDBC Applet Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6613. DB2's JDBC Application Implementation. . . . . . . . . . . . . . . . . . . . . . . . . . 6614. Millennium Cafe Sales Tools Plus Environment . . . . . . . . . . . . . . . . . . . . 8315. "About Database" Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10116. Sales Representative Information Request Form . . . . . . . . . . . . . . . . . . 10317. Sales Representative Information Report Form. . . . . . . . . . . . . . . . . . . . 10418. Custom Sales Report Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10519. Query Results Form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10620. Lotus Notes Client Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10821. Web Browser Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10822. @DbColumn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11023. @DbLookup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11124. @DbCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11225. LS:DO Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11426. DB2LSX Access Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12027. Java Agent: Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13528. Java Agent: Import Java Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13529. Requesting a Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13930. Lotus Connection Document: Supported Data Sources List . . . . . . . . . . 14231. Lotus Connection Document: Connection to DB2 . . . . . . . . . . . . . . . . . . 14232. Realtime Activity Document: Domino Database Selection . . . . . . . . . . . 14333. Realtime Activity Document: Notes Form Selection . . . . . . . . . . . . . . . . 14434. Realtime Activity Document: Connection Selection . . . . . . . . . . . . . . . . . 14435. Realtime Activity Document: Key and Data Field Mapping . . . . . . . . . . . 14536. Realtime Activity Document: Realtime Event Selection. . . . . . . . . . . . . . 14537. Realtime Activity Document: Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

© Copyright IBM Corp. 1998 ix

x Using DB2 in a Domino Environment

Tables

1. Embedded SQL and Call Level Interface Comparison . . . . . . . . . . . . . . . 152. Platforms Supporting Lotus Notes Clients and Domino Servers . . . . . . . . 443. Platforms Supporting DB2 CAE, DB2 Connect, or DB2 Server. . . . . . . . . 454. Domino Protocol Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465. DB2 Protocol Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476. Characteristics of Domino and DB2 Applications: Part I . . . . . . . . . . . . . . 527. Characteristics of Domino and DB2 Applications: Part II. . . . . . . . . . . . . . 538. Characteristics of Domino and DB2 Applications: Part III . . . . . . . . . . . . . 549. DB2LSX and LS:DO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6310. Lotus Notes Client PLatforms: Tool Availability . . . . . . . . . . . . . . . . . . . . . 7311. Domino Server Platforms: Tool Availability . . . . . . . . . . . . . . . . . . . . . . . . 7412. Tools and Application Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7713. Tools and Data Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7914. Tools and Environment Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8115. DB2 UDB TCP/IP Configuration Information . . . . . . . . . . . . . . . . . . . . . . . 8516. DB2 for OS/390 TCP/IP Configuration Information . . . . . . . . . . . . . . . . . . 8717. DB2 for OS/390 DRDA Configuration Information . . . . . . . . . . . . . . . . . . . 8818. CLASSPATH Environment Variable Values . . . . . . . . . . . . . . . . . . . . . . . 9519. Function Names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10220. @DbFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

© Copyright IBM Corp. 1998 xi

xii Using DB2 in a Domino Environment

Preface

Domino is the first e-mail and collaboration server for the Web. It is a messaging and applications server that enables a broad range of secure, interactive business solutions for the Web. DB2, on all its platforms, is a powerful, easy-to-use relational database management system that handles the ad hoc structured queries and transaction processing required to manage and operate a business of any size.

The combined capabilities of Domino applications and DB2 create an integrated vehicle for quickly and easily developing and deploying applications that improve decision making and streamline business processes.

In this redbook we explain how to integrate Domino applications with a DB2 data store. We report on a practical implementation of all connections to DB2. We discuss how to integrate DB2 data and cover the design issues we considered during our implementation. We describe in detail the different techniques we used to integrate Domino with DB2, including:

• Programmatic solutions using LotusScript such as LS:DO, DB2LSX, and the new LC LSX

• Programmatic solutions using Java, JDBC, and Java agents and servlets

• Nonprogrammatic solutions using DECS or LEI (formerly known as NotesPump)

The book is written for:

• Managers and system architects who want to understand why they should combine DB2 and Domino

• System administrators who have to manage such an integrated infrastructure

• Programmers who want to use DB2 data in a Domino application

© Copyright IBM Corp. 1998 xiii

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, San Jose Center.

Christophe Toulemonde is a Senior ITSO Specialist for client/server and network computing at the Application Development and Data Management ITSO, San Jose Center. He writes extensively and teaches IBM classes worldwide on all areas of client/server and network computing. Before joining the ITSO, Christophe worked as a Technical Manager in an IBM subsidiary, Datablue, in France. You can reach him by e-mail at [email protected].

Jakob Gabathuler , a Systems Engineer for IBM in Switzerland, has 22 years of experience in the computer industry, including 3 years in marketing support for office products. His areas of expertise include IBM OfficeVision on all platforms, migration and coexistence of host office products with Lotus Notes, and integration of host data in Lotus Notes. Jakob has been involved with large projects migrating OfficeVision data to Lotus Notes. You can reach him by e-mail at [email protected].

Brendan Jansen is a Systems Engineer for Lotus in Perth, Western Australia. He has 10 years of experience in the computer industry, including 3 years with Lotus Notes solutions. Brendan has worked at Lotus for the past year. Before that he was involved in a large NotesPump data integration project, which also involved extensive application development. You can reach Brendan by e-mail at [email protected]

Laura Rossini is a Systems Engineer in Italy. She has two years of experience in the database and data communications fields. Laura holds a degree in physics from the University of Milan. Her areas of expertise include DB2 for OS/390 and DB2 Universal Database. You can reach Laura by e-mail at [email protected].

John Wylie is a Field Support Engineer for Lotus in London. He has worked at Lotus for two years and has six years of experience in the computer industry. John’s areas of expertise include Lotus Notes and Domino infrastructure, messaging, and administration. You can reach him by e-mail at [email protected]

Lancelot Schaper is an IT specialist at IBM in The Netherlands. He has two years of experience in application design and development. Lancelot holds a degree in computer science from the University of Amsterdam. His areas of expertise include application design and development and e-commerce.

xiv Using DB2 in a Domino Environment

Lancelot recently participated in a major project connecting Net.Commerce, Java, Lotus Notes, and DB2. You can reach him by e-mail at [email protected].

Thanks to the following people for their invaluable contributions to this project:

Mary LehnerIBM - Santa Teresa

John MartinLotus - Business Partner Marketing Group

Mary PetersonLotus Product Manager

Scott PragerLotus - Enterprise Integration Business Unit Lead Architect

Lauren WendelLotus Product Manager

Thanks also to Maggie Cutler for her editorial review.

xv

Lotus Solutions for the Enterprise Collection

This book is the fifth volume of the Lotus Solutions for the Enterprise Collection. This collection of books covers the integration of Domino applications with enterprise data and applications.

It contains:

• Volume 1 - Lotus Notes: An Enterprise Application Platform, SG24-4837

This book explains the integration of Lotus Notes applications with traditional enterprise applications at the architecture level. It is designed to help managers and technical professionals evaluate the impact of implementing such an interface between Lotus Notes and transaction and database management systems.

• Volume 2 - Using DB2 in a Domino Environment, SG24-4918

This book explains the integration of DB2 data in a Domino environment. It provides a working example of an integrated application using DB2 and Domino. It describes the use of such techniques as LS:DO, DB2LSX, and NotesPump to integrate Domino with DB2.

• Volume 3 - Using the IBM CICS Gateway for Lotus Notes, SG24-4512

This book describes the IBM CICS Gateway for Lotus Notes, which enables a Lotus Notes application to access resources on any CICS server.

Although the book focuses on the functions of the IBM CICS Gateway for Lotus Notes, it also describes how to set up communications between Lotus Notes and CICS/ESA and provides some practical examples to demonstrate online CICS data access.

• Volume 4 - Lotus Notes and the MQSeries Enterprise Integrator, SG24-2217

This book describes the use of the MQSeries Enterprise Integrator to connect Lotus Notes to any transaction system. It explains the concept of the extended transaction model supported by this product.

The book focuses on the functions of the MQEI. It also describes how to set up communications between Lotus Notes and several back-end transaction servers.

• Volume 5 - NotesPump: The Enterprise Data Mover, SG24-5255

This book explores how to use NotesPump to integrate Domino applications with enterprise data stores. It describes the NotesPump architecture and provides a sample application that uses NotesPump

xvi Using DB2 in a Domino Environment

components such as Replication, Realtime Notes, Scripted, and DPROPR activities. The book also covers how to use NotesPump to support Web users and provides special programming techniques such as dynamic and drill-down queries.

Comments Welcome

Your comments are important to us!

We want our redbooks to be as helpful as possible. Please send us your comments about this or other redbooks in one of the following ways:

• Fax the evaluation form found in “ITSO Redbook Evaluation” on page 231 to the fax number shown on the form.

• Use the electronic evaluation form found on the Redbooks Web sites:

For Internet usershttp://www.redbooks.ibm.com

For IBM Intranet usershttp://w3.itso.ibm.com

• Send us a note at the following address:

[email protected]

xvii

xviii Using DB2 in a Domino Environment

Chapter 1. Lotus Notes and Domino

Lotus Notes is an enterprise or workgroup computing environment that helps people work together effectively, regardless of platform or technical, organizational, geographical, or time-based boundaries. Lotus Notes based information can be shared across any distance, at any time.

Lotus Notes is an ideal system for developing Internet and intranet applications that provide for the communication between individuals and groups, collaboration between teams and projects, and the coordination of tasks and activities. Lotus Notes’ unique groupware capabilities, matched with its security model and application development environment, provide you with an infrastructure for the development and delivery of applications across the enterprise.

Lotus Notes is also a client/server platform for developing and deploying groupware applications. At its most basic level, Lotus Notes is a document database, serving as a repository for both textual and other information, for example, images, presentations, and spreadsheets. Lotus Notes provides the ability to distribute this information throughout an enterprise through replication and yet offers the security necessary to allow only those users who need to see information see it.

Lotus Notes consists of three primary elements:

• Domino server, the server element

• Lotus Notes clients, the client elements

• Services, which run on clients and servers

1.1 Domino Server

Domino is an applications and messaging server with an integrated set of services that enable you to easily create secure, interactive business solutions for the Internet and corporate intranets. With Domino, you can rapidly build, deploy, and manage applications that help coworkers, partners, and customers collaborate and coordinate critical business activities online. Domino supports a variety of clients and devices, including Web browsers, Lotus Notes clients, and various mail clients.

Domino is available on Microsoft Windows 95 and Windows NT (Intel and DEC Alpha), IBM OS/2, OS/390, OS/400, and AIX, Hewlett Packard HP-UX, Sun Solaris (SPARC and Intel Edition), Novel NetWare.

© Copyright IBM Corp. 1998 1

Domino provides services, including storage and management of shared databases and mail routing, to Lotus Notes users and other Domino servers.

Domino is also a Web server in that it integrates Lotus Notes databases and applications with the Web by supporting any Web browser as a client. Lotus Notes applications can be accessed by using a Web browser on the Internet or intranet.

1.2 Lotus Notes Clients

Lotus offers customers a choice of three clients:

• The Lotus Notes Mail is the advanced messaging client with fully integrated calendaring and scheduling, task management, discussions, basic workflow, and browser integration. It meets the needs of customers who require these advanced messaging capabilities but do not require access to custom intranet applications. It provides full support for mobile users, including the ability to browse the Internet to access and manage Web information online as well as offline.

• The Lotus Notes Desktop is Lotus' strategic intranet client, an integrated working environment that combines groupware and messaging capabilities with Web access. Notes object services allow individuals and organizations to leverage rich, intuitive, and integrated e-mail, workflow, collaboration, calendaring, and scheduling. The Lotus Notes Desktop supports mobile users, powerful custom business applications, and browsing the Internet to access and manage Web information.

• The Lotus Notes Designer for Domino is the Notes design client improved for development of Domino applications. It comes complete with everything that is required to develop powerful client/server and Internet applications, including applications that enable developers to streamline every aspect of Web site creation, design, and management. The Notes Designer for Domino is perfect for Notes application developers designing for the Web and Web developers who need a secure, collaborative, business Web site.

The Lotus Notes clients run on a computer using common operating systems, such as Microsoft Windows 3.1, Windows 95, and Windows NT, IBM OS/2 and AIX, Hewlett Packard HP-UX, Sun Solaris (SPARC and Intel Edition), Apple Macintosh OS (PowerPC and 68K) which provides the means to communicate with Domino servers so that you can use shared databases and read and send mail in a client/server environment.

2 Using DB2 in a Domino Environment

People use Lotus Notes clients for e-mail, calendaring, scheduling, Web access, and Domino-based applications. Lotus Notes clients and Domino servers utilize various services within the software to provide the messaging, communication, and collaborative aspects of applications.

The Notes Designer for Domino 4.6 is an enhanced Lotus Notes client that includes special support for developers building applications for delivery by the Domino server to both Notes clients and Web browsers. It includes all of the features of the Lotus Notes client, such as support for Internet mail systems, enhanced personal information manager (PIM) functions, and improved integration with word processors and desktop suites. It also includes many additions and enhancements to the Notes development environment to capitalize on the knowledge base of Notes developers while giving them more Web-friendly tools. Among the additions and enhancements are:

• Improved support for hypertext markup language (HTML) authoring within the Notes user interface

• Integrated support for Java

• Easy development of applications targeted for display in both Notes and a Web browser

• Bundled tools, including the Lotus BeanMachine for quickly and easily adding multimedia features to Web applications through Java applets, without programming

1.3 Services

The services listed below are used in the Lotus Notes and Domino environment. Most services are available to Lotus Notes clients and Domino servers.

Object StoreDocuments in a Domino database can contain any number of objects and data types including text, rich text, numerical data, structured data, images, graphics, sound, video, file attachments, embedded objects, and Java and ActiveX applets. A built-in full-text search engine makes it easy to index and search documents. The object store also lets your Domino applications dynamically present information based on variables such as user identity, user preferences, user input, and time.

DirectoryA single directory manages all resource directory information for server and network configuration, application management, and security. Domino

Lotus Notes and Domino 3

includes user account synchronization between Windows NT and Domino and is Light Weight Directory Access Protocol (LDAP) compliant. The directory is the foundation for easily managing and securing your Internet and intranet applications.

SecurityThe Domino security model provides user authentication, digital signatures, flexible access control, and encryption. Domino's security enables you to extend your intranet applications to customers and business partners.

ReplicationBidirectional replication automatically distributes and synchronizes information and applications across geographically dispersed sites. Replication makes your business application available to users around your company or around the world, regardless of time or location. “Lotus Notes Replication” on page 26 describes Lotus Notes replication in more detail.

MessagingAn advanced client/server messaging system with built-in calendaring and scheduling enables individuals and groups to send and share information easily. Message transfer agents (MTAs) seamlessly extend the system to Simple Mail Transfer Protocol (SMTP) / Multipurpose Internet Mail Extension (MIME), x.400, and cc:Mail messaging environments. The Domino messaging service provides a single server supporting a variety of mail clients—Post Office Protocol V3 (POP3), Internet Message Access Protocol V4 (IMAP4), Message Application Programming Interface (MAPI), and Lotus Notes clients.

WorkflowA workflow engine distributes, routes, and tracks documents according to a process defined in your application. Workflow enables you to coordinate and streamline critical business activities across your organization, and with customers, partners, and suppliers.

AgentsAgents enable you to automate frequently performed processes, eliminating tedious administration tasks and speeding your business application. Agents can be triggered by time or events in a business application. Agents can be run on Domino servers or Lotus Notes clients.

Development EnvironmentNotes Designer for Domino is general-purpose client software featuring an integrated development environment (IDE) that provides hassle-free access to all features of the Domino server. Notes Designer for Domino features enhancements that make creating advanced Web sites fast and easy. It also


includes two valuable tools: Lotus BeanMachine for Java, and Lotus Notes Global Designer. Use BeanMachine to create multimedia Java applets in minutes without writing any Java code. With Notes Global Designer, your applications can run in many different languages at once.

Scalability and Reliability with Advanced ServicesOptional Advanced Services enable you to cluster up to six Domino servers to provide both scalability and failover protection, to maximize the availability of your groupware and messaging applications. Real-time replication technology keeps the clustered servers synchronized.

Note: A Domino server is not the same as a file server. A file server provides access to shared resources such as printers and applications and manages network activity. Domino is an application-level server process that provides services necessary for the effective management of communications and applications.

1.4 Lotus Notes Databases

Lotus Notes databases manage documents, as opposed to relational databases, which manage tables. Unstructured or structured data as well as associated programming logic are stored within the database.

Lotus Notes databases are essentially a complete application with its associated data. They contain all of the forms, views, agents, fields, and code required to manage the data. Lotus Notes databases can reside on a Domino server or Lotus Notes workstation.

A Lotus Notes document is the foundation for data storage within a database. There are also many design features of Lotus Notes databases. Two of these features are principal design elements, namely forms and views.

DocumentsA Lotus Notes document is a container for data and is similar to a row in a database management system (DBMS). Each document is a collection of fields. A unique identifier is given to each document upon its creation and is used by the Lotus Notes database as a primary key.

A document’s design is held within a Lotus Notes form, which specifies what a document can contain in each field, for example, a number, a date, text, or rich text.

Lotus Notes and Domino 5

FormsForms are used to author, read, and edit documents. Application developers design forms as templates for document creation or as a way to view document data. Different forms can be used to view the same document. Forms are comprised of other design elements, such as text, fields, buttons, and programming code. These design elements are used to manipulate document data when it is accessed with the form.

ViewsViews are used to sort, list, filter, and categorize documents. Application developers design views with particular selection criteria so that they display lists of pertinent documents in a given order. Views allow you to navigate through multiple documents. Documents are accessed and opened from within views. Views also contain other design elements, such as columns, buttons, and programming code, which enables you to manipulate or change multiple documents.


Chapter 2. Lotus NotesPump

Lotus NotesPump is an enterprise-scale data distribution server that allows you to build applications that read and write data between an increasing number of relational, legacy, and Internet-based data sources.

Using the NotesPump server technology, you can move or transform data on a scheduled, one-time, or event-driven basis, or based on a particular business condition. Data can also can be made available to end user clients on demand, when required, directly from back-end databases.

Frequent and reliable access to corporate data has many benefits, especially more accurate, timely data for the users who require it, and the ability to respond to and better manage business operations, using up-to-date corporate business system information.

NotesPump supports database connectivity between a multitude of major databases, providing native server link connections for Domino, IBM DB2, Oracle 7/8, Sybase System 10/11, and Text/ASCII file system. Two other link types, an ODBC link connection and an Information Builders, Inc. EDA/SQL connection, provide NotesPump server access to over 70 other relational and sequential sources.

Another important feature of NotesPump is that, although the server is administered by a Lotus Notes application, NotesPump supports data transfers and replications between dissimilar, non-Notes databases such as DB2 and Oracle. Therefore, system managers can adopt a single enterprise NotesPump system infrastructure to manage interaction between an increasing number of legacy and relational data sources.

The NotesPump system remains unique in its ability to provide data transfer operations between a growing number of legacy and relational systems without necessarily having to program. Common reusable programming logic is built into the NotesPump product. You can utilize this logic by defining parameters rather than writing raw programming code.

2.1 Structure

Lotus NotesPump is a server-based tool for pumping data between data sources either on command or on schedule.

As shown in Figure 1 on page 8, the Lotus NotesPump system is comprised of a server component, the NotesPump Server engine, and its management

Lotus NotesPump 7

application, a Lotus Notes database called the NotesPump Administrator. Working with the NotesPump Administrator database, the system administrator creates and populates Notes documents that become the instruction set carried out by the NotesPump Server engine, a multithreaded, multiprocessing task.

Figure 1. NotesPump Structure

NotesPump is available on Windows NT, OS/2, HP-UX, AIX, Solaris SPARC, Solaris Intel Edition, and OS/400.

2.2 NotesPump Administrator

The Administrator database is the control store for NotesPump. It contains the elements that control the operation of NotesPump servers. All of the elements—the instructions for the NotesPump server—are stored within documents.

Documents define links, activities, and system and server configurations.

NotesPump supports transferring data to and from the following data sources: DB2, EDA/SQL, File, Notes, open database connectivity (ODBC), Oracle, Sybase, and Text. You define how NotesPump can access a data source in a Link document. A link provides NotesPump with all the information required to


locate the data. A link is a defined connection from the NotesPump Server to a specific database product with specific access parameters, such as user IDs and passwords.

An Activity document contains instructions for the NotesPump server and as such is the central element of NotesPump. Activity information in the Administrator database tells a NotesPump engine what to do, when to do it, and how. NotesPump can execute the following types of activities to move and manage data:

• Command activity, which executes an action against one database

• Direct Transfer activity, which transfers data from one database to another

• DPROPR activity, which enables propagation of IBM Data Propagator (DPROPR) consistent change data (CCD) table information to any NotesPump data source

• Java activity, which executes a Java application

• Polling activity, which checks whether a condition is met to execute an activity

• Realtime Notes activity, which provides synchronous access to a NotesPump supported external data source from a Notes application

• Replication activity, which synchronizes databases by updating one database from the data in another

• Scripted activity, which executes LotusScript commands

Lotus NotesPump 9

Chapter 3. DB2

DB2 is a relational DBMS that enables you to store, query, update, insert, or delete data in a database from local or remote client applications. It facilitates all database administration tasks such as configuring, backing up and recovering data, managing directories, scheduling jobs, and managing media.

The DB2 product family spans AS/400 systems, RS/6000 hardware, IBM mainframes, non-IBM machines from Hewlett-Packard and Sun Microsystems, and operating systems such as OS/2, Windows (95 and NT), AIX, HP-UX, SINIX, SCO OpenServer, Sun Solaris, OS/400, and OS/390.

The DB2 family offers open, industrial-strength database management for business intelligence, transaction processing, and a broad range of applications for all types of businesses.

3.1 Structures

In a relational database, data is perceived to exist in one or more tables, each containing a specific number of columns and a number of unordered rows; each column in a table is related in some way to the other columns. DB2 accesses data by referring to its content instead of its location or organization in storage; the rows of a relational table have no fixed order, whereas the order of the columns is always the order you specify when defining the table.

DB2 manages two categories of structures:

• System structures, which are controlled and accessed by DB2. They contain information about the definitions of all objects, such as databases, tables, views, and indexes, as well as security information about the authority that users have for the objects.

• Data structures, which are accessed under the user’s direction and by which data is organized

Below we describe the data structures.

DatabaseA database is a collection of DB2 structures. When you define a database, you give a name to a collection of tables and associated indexes as well to the table space where they reside. A database can contain, for example, all of the data associated with an application program so that you can start or stop access to the data in one operation.

DB2 11

Table SpaceA table space is a physical place where the table’s data and systems structures are stored.

TableA relational database presents data as a collection of tables. A table consists of data logically arranged in columns and rows. The data in the table is logically related, and relationships can be defined among tables. Data can be viewed and manipulated on the basis of mathematical principles and operations called relations. Table data is accessed through structured query language (SQL).

When you create a table, you have to define an ordered set of columns; at the interception of a column and a row is a value. All data in the same column must be of the same type, which is defined when the table is created.

A table can have a primary key. A primary key is a column, or a set of columns, whose values uniquely identify each row.

IndexAn index is an ordered set of pointers to the data of a DB2 table; it allows efficient access to rows in a table by creating a direct path to the data through the pointers. Each index is stored separately from the table it refers to and is based on the values of data in one or more columns of the table.

ViewsA view is an efficient way of representing data without having to maintain it; it can include all or some of the columns or rows of the tables where it is defined.

A view is not an actual table and requires no permanent storage: When you create a view, DB2 stores the definition in its catalog but does not store any data for the view itself because data already exists for the base table. A virtual table is created and used.

3.2 Services

DB2 offers the following services and features:

Structured Query LanguageSQL is the language used to access data in DB2 tables. SQL contains both data definition statements and data manipulation statements. Data definition statements define the structure of the database, and data manipulation statements manipulate data in tables (SELECT, INSERT, UPDATE, DELETE).


SQL also performs functions such as granting or revoking access to resources.

SQL is nonprocedural because you specify what you want to be done, not how to do it. To access data in a table, you only have to specify the names of the table and the columns where it can be found; you do not have to specify an access method.

Application ProcessesAll SQL programs execute as part of an application process. An application process involves the execution of one or more programs and is the unit to which DB2 allocates resources and locks. Different application processes might involve the execution of different programs, or different executions of the same program. The means of initiating and terminating an application process are dependent on the environment.

ConcurrencyMore than one application process might request access to the same data at the same time. Locking is used to maintain data consistency, preventing, for example, two different application processes from updating the same row simultaneously. DB2 acquires locks to prevent uncommitted changes made by one application process from being perceived by any other; locks acquired by an application are released when that process ends or by a commit operation that makes all database changes permanent.

Unit of WorkA unit of work is a recoverable sequence of operations within an application process. At any time, an application process is a single unit of work, but the life of an application process can involve many units of work as result of commit and rollback operations. A unit of work starts when an application process is initiated or when the previous unit of work is ended by something other than the end of the application process. A unit of work is ended by a commit operation, a rollback operation, or the end of the application process.

COMMIT is the operation that ends a unit of work so that the database changes made during that unit of work become permanent and are visible to other users. ROLLBACK is the process of restoring data changed by SQL statements to the state at its last commit point. If a failure occurs during a unit of work, DB2 restores all uncommitted data to the last point of consistency.

A commit or rollback operation affects only the database changes made within the unit of work it ends. While these changes remain uncommitted, other application processes cannot perceive them, and the changes can be

DB2 13

backed out. Once committed, the database changes are accessible by other application processes and can no longer be backed out by a rollback.

RecoveryRecovery is the process of resetting a failed system, or damaged data stored in a system, to an operable state.

LoggingDB2 records all data changes and significant events in a log as they occur. In case of failure, in combination with the database backups, logs are used to recover the consistency of the database right up to the point in time when the error occurred.

3.3 Programming DB2

In a relational database, you must use SQL to access the desired data, but the method with which you integrate the SQL into your application is your choice. The choices are:

• Embedded SQL

• Call Level Interface (CLI) or ODBC

• REXX

• Query products

Embedded SQLEmbedded SQL can consist of either static or dynamic SQL or a mixture of both types.

If your SQL statements are frozen in terms of content and format when your application is in use, consider using embedded static SQL in your application. With sta1tic SQL, the executor of the application can temporarily inherit the privileges of the user that bound the application to the database.

Embedded dynamic SQL can be used where the statements that need to be executed are determined while the application is running. Using embedded dynamic SQL creates a generalized application program that can handle a variety of input.

An application that includes embedded SQL requires program preparation—using the DB2 prep command—prior to using your programming language compiler. In addition, the SQL that makes up the application must

1


be bound—using the DB2 bind command—to the database in order for the application to run.

Call Level InterfaceCLI provides data access to your application through the use of function calls to CLI functions. Any SQL statements that need to be issued are passed to the database through a CLI function call. The advantages of CLI include the elimination of the need for precompiling and binding the program, as well as the increased portability of your application through the use of ODBC interface which is supported by CLI.

An application written with CLI only uses dynamic SQL. The CLI imposes some additional overhead in processing.

Table 1 compares the advantages of using embedded SQL or CLI when writing DB2 applications

Table 1. Embedded SQL and Call Level Interface Comparison

REXXREXX supports a dynamic SQL interface that does not require program preparation or binding the application to the database. Use of this interpretive language may help speed development of applications.

Query ProductsVarious query products—such as Lotus Approach—are available that support query development and reporting. The products vary in how SQL statements are developed and the degree of logic that can be introduced.

3.4 DB2 object extensions

DB2 provides several features that allow object-relational capabilities: large object support, user-defined distinct types, user-defined functions, and

Embedded SQL Call Level Interface

Static and dynamic SQL Dynamic SQL

Performance Portability

Simple for fixed queries No precompile, no bind

Supports multiple programming languages

C or C++

SQLCA, SQLDA No SQLCA or SQLDA

Encapsulation and security Data conversion

DB2 15

triggers. The synergy among these object-oriented extensions enables you to model complex data structures.

In this section we provide a brief introduction to object-oriented extensions in DB2.

3.4.1 User-defined TypeA distinct type is a user-defined data type (UDT) that shares its internal representation with an existing type (its source type) but is considered to be separate and incompatible for most operations. For example, you might want to define an age type, a weight type, and a height type, all of which have quite different semantics but use the built-in data type INTEGER for their internal representations.

The following example illustrates the creation of a distinct type named PAY:

CREATE DISTINCT TYPE PAY AS DECIMAL(9,2) WITH COMPARISONS

Although PAY has the same representation as the built-in data type DECIMAL(9,2), it is considered to be a separate type that is not comparable to DECIMAL(9,2) or any other type. It is comparable only to the same distinct type. Also, operators and functions that would work on DECIMAL do not apply here. For example, a value of PAY data type cannot be multiplied with a value of INTEGER data type. Therefore, you have to write functions that apply only to the PAY data type.

Using distinct data types limits mistakes. For instance, if the SALARY column of table EMPLOYEE was defined as a PAY data type, it cannot be added to COMM even though the sourced types are the same.

3.4.2 User-defined FunctionDB2 provides built-in and user-defined functions (UDF). However, this set of functions will never satisfy all requirements. Often, you have to create customized functions for particular tasks. User-defined functions enable you to create customized functions.

There are two types of user-defined functions: sourced and external.

• Sourced user-defined functions allow user-defined types to selectively reference another built-in or user-defined function that is already known to the database. You can use both scalar and column functions.

In the example below a user-defined function called MAX is created that is based on the built-in MAX column function, which takes a DECIMAL data


type as input. The MAX UDF takes a PAY data type as input and returns a PAY data type as output.

CREATE FUNCTION MAX(PAY) RETURNS PAY SOURCE MAX(DECIMAL)

• External user-defined functions are written by users in a programming language. There are external scalar functions and external table functions.

Assuming that you have already written a function that counts the number of words in a string, you can register it with the database, using the CREATE FUNCTION statement with the name WORDCOUNT. This function can then be used in SQL statements.

For example, the following statement returns employee numbers and the number of words in the ASCII form of their résumés. WORDCOUNT is an external scalar function that the user has registered with the database and is now being used in the statement:

SELECT EMPNO, WORDCOUNT(RESUME) FROM EMP_RESUME WHERE RESUME_FORMAT = 'ascii'

3.4.3 Binary Large ObjectsLarge object support allows multimedia data such as documents, video, image, and voice to be stored in the database and manipulated like other database objects.

DB2 supports three kind of large objects:

• Character large objects (CLOBs)

A CLOB is a string of single-byte characters with an associated code page. When receiving on a client using another code page, code page conversion is supported. CLOBs are best used for text-oriented information to store large single-byte character set data such as documents. A CLOB can be up to 2 GB long.

• Double-byte character large objects (DBCLOBs)

A DBCLOB is a string of double-byte characters with an associated code page. Code page conversion is supported. DBCLOBs are best used for text-oriented information using double-byte characters. A DBCLOB can be up to 2 GB long (1 073 741 823 double-byte characters).

• Binary large objects (BLOBs)

DB2 17

A BLOB is a binary string with no associated code page. BLOBs are used for image, voice, video, graphical, and other media. A BLOB can be up to 2 GB long. A BLOB is primarily intended to hold nontraditional data such as pictures, voice, and mixed media.

3.5 Distributed Relational Database Architecture

The Distributed Relational Database Architecture (DRDA) links together the DB2 family members into a distributed data network. DRDA is an open architecture that has been licensed to many database vendors. It is the industry standard for distributed databases. Through DRDA, endusers and applications can access data in any database in the data network without knowing where that data is located and without the loss of transaction integrity so important to mission-critical applications.

DRDA is a standardized database protocol that provides reliable, fast, and secure access to data within heterogeneous client/server environments. DRDA defines the commands, data formats, and rules that allow any DRDA client to successfully interoperate with any DRDA server. The DB2 family of products implement DRDA.The Open Group also announced the acceptance of DRDA as an industry standard for database access interoperability.

DRDA enables you to keep your existing security, backup, accounting, and other data management procedures while allowing you to access data with applications from your workstation.

DRDA is a set of protocols that allow transparent connectivity between RDBMSs on different platforms; it coordinates communications between systems by defining what must be exchanged and how it must be exchanged.

DRDA is an implementation of the client/server computing model. It provides data services that are available to clients anywhere in the network, irrespective of their method of connection. The distribution complexities are transparent to the client application so that no part of the application needs to reside on the server.

Programs trying to make use of data residing on a variety of hardware and operating system platforms need to be shielded from the differences in those environments. For example, translation is required between EBCDIC and ASCII data when mainframe data is transmitted to a PS/2. Communication links between systems must be defined, data integrity must be protected, and recovery must be coordinated in the event of a problem. The format of the data at both ends must be known, so that both sending and receiving systems understand the data being transmitted. If a database request is made from


one system, the other system must understand it, to perform the request and to return the results to the first system.

It is unreasonable to expect users and programmers to be concerned with these issues. Therefore architectures (supported and implemented by standard system software) are required to ensure that the different systems understand each other.

DRDA allows application programs to access distributed relational data and allows communication among relational DBMSs.

DRDA provides services for connectivity between application programs and distributed relational DBMSs by:

• Describing information flows between participants

• Describing responsibilities of the participants and usage of the information flows

• Providing the formats and protocols required for distributed database management.

DRDA does not provide the application programming interface (API) for distributed DBMSs. The API is provided by SQL.

3.5.1 Roles of DRDA DatabasesIn a DRDA environment every database platform can play a different role for different applications at the same time.

• Client

A database client is the component that runs the application program which issues SQL statements to request data. Typical database clients are the DB2 client application enablers (CAEs).

• Application requester

An application requester (AR) is the code that handles the application end of a distributed connection; it is the application that is requesting data or services. In a workstation environment, the DB2 Connect product functions as an AR on behalf of application programs. As DRDA does not require any local database functions, DB2 Connect can be installed without having the support for local databases.

• Application server

An application server (AS) is the code that handles the database end of the connection; it performs database operations for the client and sends

DB2 19

the results back to the requesting client. The AS code is part of the DBMS on which the requested data resides.

3.5.2 Degrees of DistributionDRDA describes three levels of distribution:

• Remote unit of work (RUW)

RUW processes related SQL statements as a transaction at a single remote database. Each RUW can contain multiple SQL statements that must access the same DBMS. An application program can update several remote databases, but it can access only one database within one unit of work. When the application is ready to commit the work, the commit is initiated at the DBMS where the unit of work was executed.

• Distributed unit of work (DUW)

A DUW consists of coordinated commit and recovery facilities for processing related SQL statements within a transaction that spans multiple remote databases. An application can access more than one database server within one unit of work; it can switch between different database servers before committing the data.

Commit and rollback are coordinated at the database server locations so that, if a failure occurs anywhere in the system, data integrity is preserved.

• Database directed DUW

Within one unit of work an application connects to a DBMS that can execute some requests locally and route other requests to other DBMSs.

The DBMS determines which system manages the data referenced by the SQL statements and automatically directs the request to that system. Within the same unit of work SQL statements can be directed to multiple DBMSs, but all objects of a single SQL statement must be at a single DBMS.

3.6 The DB2 Family

Planning an implementation of data management technology requires careful consideration of many factors. Reliability, functionality and the extensibility of that function, manageability, scalability, and performance are key considerations in evaluating hardware and software platforms. One of the most vital elements of a solution is the relational database server. With the DB2 family, IBM offers the most reliable, extensible, manageable, scalable and high-performance distributed database solution in the industry today.


The IBM DB2 family of relational DBMS products covers a broad range of hardware platforms including:

• Intel-based PCs and servers running OS/2, SCO OpenServer, or Windows NT

• RISC machines including symmetric multiprocessors (SMPs), clusters, and massively parallel processors (MPPs) running AIX, HP-UX, Sun Solaris, or SINIX

• AS/400 mid-range systems

• Mainframe S/390 systems running OS/390, MVS, VSE, or VM.

In addition to database servers—the engines—on each of these platforms, the DB2 family includes middleware solutions for heterogeneous database access, data replication, and database systems management. All of these distributed database management services are accessible from a common set of clients on the most popular desktop platforms using open, industry standard APIs. DB2 is much more than a relational database product; it is a complete distributed database solution for today's network computing environment.

3.6.1 ServersDB2 for OS/390 Version 5 is the flagship of the family. Since its introduction in 1982, it has set the relational database standard for the industry, and it continues to do so into the 1990s as evidenced by its recent enhancements and continued market growth. No relational database product in the industry today manages more data or supports more mission-critical applications than DB2. No other relational database product can match its reliability, manageability, or performance characteristics. The base of research, technology, and successful practical experience with DB2 anchors IBM's full family of distributed database products.

DB2 Universal Database (UDB) Version 5 is IBM's object-relational database for UNIX and Intel servers including AIX, HP-UX, Solaris, OS/2, and Windows NT. An earlier release, DB2 Common Server V2.1, is also available for Siemens-Nixdorf SINIX and SCO OpenServer.

DB2 UDB can run on everything from laptops supporting mobile users to MPPs with terabytes of data and/or thousands of users. DB2 UDB allows you to extend the capabilities of the database to meet your specific organizational requirements including the support of more advanced applications involving multimedia data such as documents, images, audio, and video. DB2 UDB is fully integrated with Web technology so that data can be easily accessed from

DB2 21

the Internet or from your intranet with complete security. DB2 UDB has particular strengths in supporting business intelligence applications such as data warehousing and online analytical processing (OLAP). DB2 leads the industry in parallel database technology and query optimization. DB2 UDB is one of the easiest databases in the industry to set up, use, and manage. It includes a complete suite of graphical administration tools that allow for easy installation, administration, and remote operations. DB2 UDB can be accessed from almost any client workstation over almost any network.

DB2 for OS/400 (DB2/400) is an integrated component of the OS/400 operating system. It is the most widely used multiuser relational DBMS in the world and has evolved to become functionally robust and highly compatible with the other DB2 family members. It can serve both as a local area network (LAN) database server using client/server protocols, or as a host database on a wide area network (WAN).

DB2 for VSE & VM Version 5 (previously known as SQL/DS) provides robust relational database management for mid-range S/390 environments. It is fully compatible with the DB2 family while supporting high performance features such as VM/ESA data spaces and VSE/ESA virtual disks.

DB2 DataJoiner provides the foundation for advanced information integration capabilities. It features data replication, data warehousing, and object/relational data management capabilities for heterogeneous environments. DB2 DataJoiner offers you the facilities needed to leverage data regardless of its location or format, by enabling you to integrate relational and nonrelational data in a transparent, efficient, and consistent manner. Support for Web-based applications, a wide range of data sources, industry-standard SQL, unique query optimization technology, and both synchronous and asynchronous data access are some examples of the product's many features. Available for UNIX (AIX and HP-UX) and Windows NT, DB2 DataJoiner gives firms a clear edge for maximizing their data assets.

3.6.2 DB2 Client Application EnablerThe DB2 CAE provides a common application and user interface into data managed by the DB2 family or by DRDA-compliant non-IBM databases. It supports industry standard interfaces including ISO ANSI SQL, X/Open CLI, and Microsoft's ODBC and can support a wealth of applications from IBM or non-IBM sources.

The CAE must be installed on each workstation executing an application that has to connect to a DB2 server. From the CAE you can:

• Communicate with a DB2 UDB server or DB2 Connect gateway machine.


• Issue an interactive SQL statement on a remote client to access data on a DB2 server.

• Graphically administer and monitor the UDB server.

• Run applications developed to comply with the ODBC standard.

• Run Java applications that access data in UDB databases through Java Database Connectivity (JDBC).

CAE is supported on OS/2, Windows NT, Windows 95, Windows 3.x, AIX,HP-UX, and Solaris.

3.6.3 DB2 Software Developer’s KitThe DB2 Software Developer's Kit (SDK) contains clients, application development tools, and samples for all supported platforms and is separately orderable. The DB2 SDK enables you to develop applications using embedded SQL, CLI, ODBC, and Java through JDBC.

3.6.4 DB2 ConnectDB2 Connect, a member of the DB2 family of products, is the successor to IBM's Distributed Database Connection Services (DDCS). DB2 Connect provides fast and robust connectivity to IBM mainframe databases for e-business and other applications running under the following Intel and UNIX operating systems:

• AIX

• HP-UX

• Microsoft Windows (all variants)

• OS/2

• Sun Solaris

Using DB2 Connect, client applications can transparently access data in the following IBM database products when running as DRDA application servers:

• DB2 for OS/400

• DB2 for OS/390

• DB2 UDB

• DB2 for VSE & VM

Connectivity to host databases is provided over Systems Network Architecture (SNA) connections using IBM's Advanced Peer-to-Peer

DB2 23

Connection (APPC) network. DB2 for OS/390 also supports database connections over TCP/IP.

Regardless of the protocol used, DB2 Connect provides DRDA support for DUW with two-phase commit processing.

3.6.5 PackagingDB2 UDB has three packaging options, each with a set of components:

• DB2 Personal Edition

DB2 Personal Edition contains DB2 UDB for use in a single machine. It contains the functions for the database system and DB2 UDB tools but cannot act as a server for clients in the LAN.

• DB2 Workgroup Edition

DB2 Workgroup Edition contains DB2 UDB for use as a server in a LAN environment. All functions and tools of the Personal Edition are also available in the Workgroup Edition. It also contains DB2 Net.Data for Internet access and DB2 CAEs for all supported platforms

• DB2 Enterprise Edition

DB2 Enterprise Edition contains all components of the Workgroup Edition and the DB2 Connect product for accessing host databases using DRDA.

To develop applications with DB2 UDB, you use the DB2 SDK.

To access DRDA databases, DB2 Connect is available in two versions:

• DB2 Connect Personal Edition

DB2 Connect Personal Edition is intended for single users on Intel workstations and allows a stand-alone workstation to access the host system.

• DB2 Connect Enterprise Edition

Performing the function of a gateway, DB2 Connect Enterprise Edition supports Intel and UNIX workstations in a workgroup, department, or LAN setting and allows connections between multiple clients and the host system.


Chapter 4. Replication

Replication is the creation and maintenance of a duplicate copy of a database or file system on a different computer, typically a server. The term usually implies the intelligent copying of parts of the source database that have changed since the last replication with the destination. Replication can be one way or two way. We refer to one-way replication as synchronization. Two-way replication is much more complicated because of the possibility that a replicated object may have been updated differently in the two locations, in which case some method is needed to reconcile the different versions.

In this chapter we explain two types of replication pertinent to our environment:

• DBMS replication

• Lotus Notes replication

4.1 DBMS Replication

In general, replication systems in a DBMS environment can be used for various kinds of application support, including:

• Sharing host data with client/server and mobile applications, for example, to put data on laptops or where business transactions occur

• Building data warehouses and business intelligence systems that enhance the company's decision-making effectiveness and competitive advantage

• Maintaining backup systems that improve data availability

DBMS data replication solutions support operational applications by:

• Replicating key business data from existing transaction systems into client/server environments

• Replicating only the data required, for example, subsetting by region or branch

• Restructuring data as required for new applications

• Allowing you to control the currency between source and target data to meet your application needs from near real-time replication to point-in-time copies (called snapshots)

• Requiring no changes to production applications

DBMS replication solutions support informational applications by:

Replication 25

• Replicating key business data from transaction systems into informational databases

• Improving data availability and access performance by moving data to the server most convenient for each user

• Enhancing data to improve its usefulness

• Supporting both point-in-time copies and data histories for trend analysis

Because the source data for replication is likely to be a production system, minimizing the impact on production applications and transaction performance is of critical importance. DBMS replication design minimizes the impact on transaction performance by capturing changes from the log instead of competing with transactions for access to production tables or adding path length to production transactions.

DBMS replication design also provides optimizations to minimize network traffic. Data reduction can be carried out at the source site, so only the required data flows over the network. For example, aggregations can be performed at the source by copying only the last change to occur rather than every change that occurred.

4.2 Lotus Notes Replication

Lotus Notes replication is the foundation for synchronizing Lotus Notes databases between clients and servers, and between servers. Lotus Notes replication is the process of updating replica copies of databases. Replicas are identical copies of databases that reside on different servers or on client workstations. Thus users on a variety of networks in a variety of locations can access the same information in a distributed environment. Lotus Notes replication synchronizes design changes as well as changes to data.

Lotus Notes replication is the process of exchanging modifications between replica databases. Through replication, Lotus Notes makes all of the replicas essentially identical over time. For example, users in one office can make changes to a replica on their server at the same time that users in another office make changes to a replica of the same database on their server. When the servers replicate, each replica is updated with the information from the replica on the other server.

A replica has the same replica identification (replica ID) as the original database. This distinguishes a replica from a copy of a database because the common replica ID lets you replicate changes between the replica and the original database.


Replication can occur between two servers or between a workstation and a server, for example, between a laptop and a server. Replication can also occur in one or both directions between replicas. That is, you can set up replication so that two replicas receive updates from each other, or only one replica receives updates from the other.

Lotus Notes lets you choose which databases you want to replicate and when to replicate them. Replication can occur automatically according to a schedule you specify, or manually through server or workstation commands you specify. Replication between servers generally occurs automatically on a schedule specified by a database manager or network administrator, whereas replication between a workstation and a server generally occurs manually when a user needs to replicate updates.

Replication can be selective. You can define which data, or type of data, is replicated to another server or workstation.

Lotus Notes utilizes field-based replication. Therefore only those fields that have new or changed data need to be transferred to the other database. Such replication significantly reduces the time it takes to synchronize data. Lotus Notes replication also uses time stamps to restrict operation to changed documents. It uses deletion stubs to replicate deletions.

If the same data is changed in two separate locations at approximately the same time, there is the possibility of a replication conflict. Lotus Notes manages replication conflicts by merging the data of the two changed documents into one document. Where data cannot be merged, for example, where the same field of data was changed in both documents, Lotus Notes saves one document with its changes intact and saves the other document as a replication conflict. When this occurs a person or process must resolve the conflict by updating or removing documents.

Lotus Notes replication enhances and complements the NotesPump data synchronization solution by allowing you to seamlessly extend enterprise data throughout the Lotus Notes environment.

4.3 Do the Replications Differ?

DBMS and Lotus Notes replications are quite different as they target different objectives and therefore implement different mechanisms. For example, DBMS replication can be used to duplicate the operational environment to an informational environment, whereas Lotus Notes replication can be used to push collaboration information from a source to one or multiple targets.

Replication 27

The main difference between the two replications is in how they solve the update conflicts between the different databases:

• DBMS replication prevents the conflict by locking and concurrency mechanisms. In a DBMS architecture, databases are hierarchized with a master database and nonmaster databases. Updates go to the master database and are controlled by the DBMS. Its locking mechanism prevents conflicts as all users are accessing the same data at the same time. Queries can be spread on every nonmaster database because a conflict is impossible with read-only data.

• Lotus Notes replication solves the conflict after its occurs by allowing the user to look at the two conflicting documents and keep the good one. Lotus Notes does not implement locking, but conflicts are rare because of the nature of Lotus Notes applications. A workflow document moves from one user to another when the first user has finished the work. For example, e-mail replication transfers the arriving mail from the server to the workstation and the outgoing mail from the workstation to the server. They are clearly two different sets of mail.


Chapter 5. Development Features

Domino application development technology supports rapid and effective development and deployment of the application. It also provides different APIs to enable you to use the most appropriate product for the task at hand.

5.1 Java

Java is not just a programming language, it is a platform that can be used to create and deliver information over any network. Java is portable and architecture-neutral for any system implementing the Java virtual machine (JVM). Programs written in Java can be distributed and executed on any client system that has a Java-enabled Web browser. You are freed from having to write multiple versions for multiple platforms and even from having to recompile for each platform. Because the applets run on the client system, scalability and performance are no longer tightly tied to Web server systems. High performance requirements are also addressed through multithreading, the ability to link native code, and the just-in-time compiler.

Java is portable and flexible. In the past, we have had languages that claimed portability, but none delivered anything remotely resembling portability. Developed from the ground up as object-oriented and portable, Java has already addressed the biggest challenge. Companies now are free to let departments select the hardware platform of their choice without worrying or having to budget for integration and porting costs.

Java applications are implementation-neutral. We often get caught up in the fat client, thin client rhetoric. Because Java is truly object-oriented, you are free to distribute the application business logic in the manner that best fits your needs. Modifications are made easily and transparently as business needs change.

Although Java is most often described as a programming language, its more unique capability is its platform independent virtual machine facility. The excitement of Java is that it combines an object programming paradigm with the client/server distributed architecture and the broad connectivity of the Internet, while solving many of the problems industry has encountered with client/server software and hardware management.

Java is an interpreted object-oriented language, similar to C++, which can be used to build programs that are platform independent in both source and object form. Its unique operational characteristics, which span Web browser and network computers as well as servers, enable new client/server functions


in Internet applications while enforcing a discipline that makes software management possible across almost any hardware platform.

To achieve platform independence, the Java language allows no platform-dependent operations and it excludes some C++ functions such as a preprocessor, operator overloading, multiple inheritances, and pointers. All Java programming is encapsulated within classes, and the development toolkit includes an extensive set of classes. These special classes, which are critical to ensuring platform independence, include GUI functions, input/output functions, and network communications.

The Java compiler, however, does not generate machine code. Instead, it generates intermediate code called Java bytecode. This bytecode is interpreted by the Java interpreter, which executes the instructions on the particular hardware platform. The Java interpreter and run-time system are collectively called the JVM.

The interpreter also inspects the bytecode at execution time to ensure its validity and safety to the machine environment. The isolation the Java interpreter provides, coupled with the Java run-time systems provided by vendors, create a a platform-independent virtual machine environment.

The Java language can be used to construct Java applets and Java applications.

5.1.1 Java AppletsA Java applet is a small application program that is downloaded to and executed on a Web browser or network computer. A Java applet typically performs the type of operations that client code would perform in a client/server architecture. It edits input, controls the screen, and communicates transactions to a server, which in turn performs the data or database operations.

Applets are invoked through the use of the applet HTML parameter:

<applet code="ReptApplt.class" width=325 height=275 archive="db2java.zip"></applet>

This tag is used within HTML pages to indicate when applets are to have control and to specify the display area to be used by the applet. When a Java-enabled server is downloading a page and encounters this tag, it also downloads the applet bytecode in the same way it downloads an image referenced by an HTML image tag. The Java-enabled browser, such as Netscape Communicator or Microsoft Internet Explorer, then interprets and

executes the applet bytecode. The applet can edit screen input, generate screen output, and communicate back to the computer from which it was downloaded. An example of applet processing would be an applet in constant communication with a server to receive stock trade information that it would update in a window on the screen. Multiple applets can execute concurrently.

The downloading of applets should not have a significant performance impact on response time because the applets are typically not very large. In fact, applets, by performing processing on the browser or network computer, can improve the overall browser performance by eliminating iterations with the Web server. Note that, just as images are cached in Web browsers, applets are cached, thereby minimizing the frequency of applet downloading. A current performance consideration is the iterative compiling of the Java bytecode at the time of execution. This consideration, however, is rapidly being addressed by the industry and is losing its importance.

5.1.2 Java ApplicationsA Java application is a program written in Java that executes locally on a computer. It allows programming operations in addition to those used in applets which can make the code platform dependent. It can access local files, create and accept general network connections, and call native C or C++ functions in machine-specific libraries.

5.1.3 Java ServletsA Java servlet is a protocol and platform-independent server-side software component, written in Java. Servlets run on a Web server machine inside a Java-enabled server, that is, a server that can start the JVM to support the use of Java servlets. They dynamically extend the capabilities of the server because they provide services over the Web, using the request-response paradigm.

From a high-level perspective, the servlet process flow would be:

1. The client sends a request to the server.

2. The server sends the request information to the servlet.

3. The servlet builds a response and passes it to the server. The response is dynamically built, and the contents of the response usually depend on the client's request.

4. The server sends the response back to the client.

Figure 2 on page 32 shows the servlet process flow.

Development Features 31

Figure 2. Servlet Process Flow

Servlets look like ordinary Java programs. The servlets import particular Java packages that belong to the Java servlet API. Because servlets are object bytecodes that can be dynamically loaded off the Web, we could say that servlets are to the server what applets are to the client. However, servlets run inside servers, so they do not need a graphical user interface (GUI). In this sense servlets are also called faceless objects.

5.2 Domino Development Environment

Domino ships with a complete set of templates for the most common types of applications. These templates include all of the logic and formatting required for a working application, and they can be deployed with no changes. You can also add new fields and logic to the templates. The templates also extend basic application development capabilities to power users.

Domino supports reuse of code that you have created in different ways. Subforms provide a way of sharing common elements among different forms with the side-effect of enforcing a common look and feel of the application’s GUI. Domino applications also can be converted into templates for reuse or adaptation in other solutions.

Domino provides a variety of development alternatives for creating applications, thus enabling you to choose the most appropriate product. The Lotus Notes Designer client is the native development environment for Domino using LotusScript and LotusScript extensions (LSXs) as the development language. However, Lotus has also developed a set of APIs for C, C++, and Visual Basic. Third-party vendors (PowerBuilder, Gupta SQLWindows) have worked together with Lotus to integrate their own development tools.


5.2.1 FormulasYou can use the Lotus Notes formula language to develop applications. The formulas are attached to certain objects in Domino, such as selection formulas for views.

The formula language contains a set of built-in macros, functions, and commands. The functions, referenced as @Functions in Lotus documentation, are prepackaged formulas. Domino has more than 100 functions.

The @Commands are built-in functions that enable you to programmatically simulate menu sequences.

The example below shows a formula to check whether or not the subject field contains a value. It is a typical example of an input validation formula. If the field is empty, you are prompted to enter a subject.

@If(Subject="";@Failure("Enter a subject for your document");@Success)

The formula language has no formal debugging mechanism. You can use the @Prompt function to check the value of the variables of interest.

The following example shows how you can check the LastName variable that is calculated by using several nested commands:

LastName := @RightBack(@Left(@UserName; "/"); " "); @Prompt([Ok]; "Debugging: Value of LastName:", LastName)

With increasing experience you will come to regard formulas as powerful and fast tools to solve many application tasks such as field input validation, default value calculations, and input translation.

The formula language does not provide enhanced program logic, such as for-to and do-while clauses, or triggering mechanisms.

5.2.2 LotusScriptLotusScript is an embedded, BASIC scripting language with a powerful set of language extensions that enable object-oriented application development within and across Lotus products. LotusScript, and its development toolset, provides a common programming environment across Lotus applications on all platforms supported by Lotus and is currently available in Lotus Notes and Domino Version 4.0 or higher, Approach 96 and 97, Freelance 96 and 97, and Word Pro 96 and 97. LotusScript enables you to use more complex scripts in a variety of environments than traditional Lotus Notes macros.


LotusScript extends the development capabilities of Domino by providing:

• A powerful, object-oriented programming language that leverages the knowledge of BASIC and Visual Basic with organizations. The LotusScript language also has a set of extensions beyond Visual Basic that provide additional power and utility when writing applications with Domino.

• A full-fledged debugger and syntax-directed editor

• Access to a broad range of Domino functions through Lotus Notes classes

• Access to external class libraries defined with the LSX toolkit. With the LSX toolkit, you can extend the function of LotusScript by creating your own classes. Examples of extensions are the ODBC implementation and MQSeries. The classes can be used by any Lotus product that hosts LotusScript.

LotusScript incorporates familiar Visual Basic statements such as Dim, Mid$, For...Next, and If...Else. Visual Basic is easy to learn and widely used, so you should find working with LotusScript and its tools a comfortable experience.

The code segment presented below is associated with a button click event on a Lotus Notes form. The code prompts the recipient with a yes/no message box and sends a response message to the Webmaster.

Define:Send Response(Button) Event:ClickSub Click Dim session As New NotesSession Dim db As NotesDatabase Dim doc As NotesDocument

Set db = session.CurrentDatabase ' reader mail database Set doc = New NotesDocument(db) ' create a new mail document

response = MessageBox("Are you going to the game tonight?", MB_YESNO+MB_ICONQUESTION)

If response = IDYES then attend = "Yes"_ Else attend = "No"

' set field values... Call doc.ReplaceItemValue("SendTo",_"Web_master") Call doc.AppendItemValue("Subject",_"Ball Game") Call doc.AppendItemValue("Body", attend) Call doc.Send(True) ' send the message End Sub

This simple example contains Visual Basic-like syntax as well as references to some Notes classes (session, database, and document). The code runs on


all Notes platforms. The reference to CurrentDatabase instead of an explicit path and file name is useful when LotusScript runs on dissimilar machines or in a distributed environment.

Although LotusScript is similar to Visual Basic, there are some important differences. Visual Basic creates stand-alone applications that execute only on Windows platforms. In the context of Lotus applications, the LotusScript interpreter runs on all supported platforms. In other words a LotusScript application, although created on one platform, can be executed by other users or servers on other machines. Note that although LotusScript is platform independent, it can be written with platform-specific resources such as Windows API calls, which of course limits portability.

LotusScript cannot be used to build stand-alone applications. It always has to run in the context of the host application. This is also true for compilation and debugging.

Events in Domino applications are used to trigger LotusScript programs. The following are examples of such events:

• Click a button

• Enter editable fields

• Initialize a form, agent, field, action, or button

• Terminate a form, field, action, or button

5.2.3 Java SupportJava is a programming language with classes, multithreading constructs, a compiler, and development and debugging tools. You can create Java programs running either as Java applets in a Web browser context or as stand-alone programs (Java applications).

Domino introduces several major enhancements related to Java:

• Java applets to a Domino application

By adding Java applets, you can create a richer, more interactive Web browser and Lotus Notes client user experience. Java applets are treated like any other Notes object. They can be stored in the Domino object store, they are easily accessible from the menu, and their properties can be easily modified. By storing Java applets within the Domino object store, you can take advantage of Domino's replication technology for keeping Java applets synchronized in multiple locations.


To prevent hostile applets from modifying or destroying information stored in Notes databases, Java applets cannot directly access the Notes Java classes at this time, unless the Lotus Notes client is installed on the Web browser machine.

Lotus Notes Designer is not a Java programming environment; therefore you have to develop your Java code outside the IDE.

• Java applets in Lotus Notes Designer for Domino and Lotus Notes clients

Lotus Notes Designer for Domino and Lotus Notes clients contain the JVM. Therefore when you place a Java applet in an application that is being developed, the applet automatically runs in place. Thus you can view and test the applet while designing the application.

• Domino server agents in Java, using the Java interface to the Domino object services

With Domino’s Java server agent support, you can use Java to develop server agents to use along with the in-the-box simple agents, formula agents, and LotusScript agents. These agents can perform a range of tasks from e-mail filtering to knowledge management to automated server administration. The agents can be triggered by server events or run as scheduled tasks. The ability to write agents in Java allows you to get the most out of your Java programming resources while still utilizing the power of the Domino environment for your Web needs.

5.2.4 JavaScriptNetscape’s JavaScript is useful for adding some client-side logic to the Web client. The advantage of using JavaScript is mainly in the improved dynamic behavior of Web pages. JavaScript is not a cross-platform language, and even though other Web browsers, such as Microsoft Internet Explorer, support JavaScript, certain constructs may not be supported.

JavaScript should be used to reduce network traffic between the Web browser and the Domino server. This is not only a performance issue but also a functional issue. Well-written JavaScript can provide extremely user-friendly context-sensitive help and enable the cursor to be placed in the field that is in error. JavaScript provides some local processing capabilities, such as validations or simple calculations, in the Web browser.

You may also want to use JavaScript to simulate Lotus Notes functional features on a Web browser (for example, dialog and info boxes) to provide a consistent look and feel for applications that support both the Notes client and the Web client.


5.2.5 Web DevelopmentDomino now easily handles HTML, allowing you to write or use existing HTML by:

• Adding HTML and typical Web objects to a Web page

You can add HTML to a page by typing it in or by copying existing code into the page and setting it to be Pass-thru HTML. Thus it is easy to mix HTML coding with other objects in the Lotus Notes Designer editor.

• Webifying Notes objects

Lotus Notes Designer makes powerful Lotus Notes objects, such as lists of views and navigators, available to Web browsers. Therefore you can embed Lotus Notes objects in Web pages, documents, and forms directly from menu options. In a mixed client environment, you can use these Lotus Notes objects to support both Lotus Notes and Web clients.

• Using computed text

Using computed text, you can present dynamically generated information to your users each time they read a page. Computed text can be mixed with static text and other information on the page. For example, you can compute the current date and time, ask for the user's login name, and even perform lookups in relational databases and present the current value in the Web page.

5.3 Application Programming Interfaces

To understand ODBC, CLI, JDBC, or any callable SQL interface, it is helpful to understand what it is based on, and to compare it with existing interfaces.

The X/Open Company and the SQL Access Group jointly developed a specification for a callable SQL interface referred to as the X/Open CLI. The goal of this interface is to increase the portability of applications by enabling them to become independent of any one database vendor's programming interface. Most of the X/Open CLI specification has been accepted as part of the ISO CLI international standard.

5.3.1 Open Database ConnectivityMicrosoft developed a callable SQL interface, ODBC, for Microsoft operating systems. The ODBC is based on a preliminary draft of the X/Open CLI.

ODBC is a standard that enables users to exchange data among DBMSs. A Windows ODBC-compliant application can manage data managed by nonrelational database managers–such as dBase–as well as most relational


database managers—such as Microsoft SQL Server, Oracle Server, or DB2. The database managers are called data sources in ODBC terminology. The ODBC specification also includes an operating environment where database-specific ODBC drivers are dynamically loaded at run time by a driver manager on the basis of the data source provided on the connect request.

ODBC is a dynamic callable API between your Windows application and the various DBMSs. It is designed to enable transparent, consistent, single-command access to heterogeneous multivendor data sources. It enables users to join data from disparate databases through a single interface, hiding the database interface from the user and the user’s application. Figure 3 shows the ODBC architecture.

Figure 3. Open Database Connectivity

The components of the ODBC architecture are:

• Application

An ODBC-compliant Windows application uses the ODBC API to submit SQL statements, interact with the data source, and retrieve the results. For example, you can write Domino applications that use the ODBC.

• ODBC driver manager

The ODBC driver manager receives function calls from the application, loads the DBMS ODBC manager associated with the data source, and directs the SQL statements to the DBMS ODBC manager.


• DBMS ODBC manager

The DBMS ODBC manager processes the ODBC function calls, translates the SQL statements in a format understood by the data source, and passes them to the data source.

• Data source

The SQL statement is performed at the data source.

The data source is the DBMS that the application wants to access. If the data source is remote, then it also consists of the client/server function of the data source. The data source is defined in a single data-source entry in the ODBC.INI file or registry.

To return the results back to the application, the same path is used.

The ODBC APIs do not provide any client/server feature to access remote data sources. To access a remote data source, you have to install the required elements on the client machine where the application runs. For example, on a Domino running on a Windows NT server machine, you have to install DB2 CAE and provide a communication support (NetBIOS, TCP/IP, SNA) to access a remote DB2 UDB. If you want to access a DB2 for OS/390 or DB2 for OS/400 database, you have to install DB2 Connect.

Because ODBC is a common set of APIs that provides access to multiple nonrelational and relational DBMSs, you can use only common SQL statements that are supported by all DBMSs. Therefore you cannot exploit all of the features of each DBMS. What your application wins in portability—running independently of the DBMS— it loses in function support and performance—using binary objects or user-defined functions.

ODBC is not limited to Microsoft operating systems; other implementations are available on various platforms.

The following DB2 features are available to both ODBC and DB2 CLI applications:

• Double-byte (graphic) data types

• Stored procedures

• DUW

• Two-phase commit

• Compound SQL

• UDT

• UDF


5.3.2 DB2 Call Level InterfaceSimilar to ODBC, the CLI is a callable API for database access and is an alternative to the embedded SQL API. It is supported by the DB2 family of database servers.

The DB2 CLI dynamic load library (DLL) can be loaded as an ODBC driver by an ODBC driver manager. In that configuration ODBC applications can connect to DB2 servers. Applications written directly to DB2 CLI link directly to the DB2 CLI DLL. DB2 CLI includes support for many ODBC and ISO SQL/CLI functions, as well as DB2-specific functions.

In addition to the DB2 features available to both ODBC and DB2 CLI applications, DB2 CLI also contains extensions to access DB2 features that can not be accessed by ODBC applications:

• Support of large objects (BLOBs, CLOBs, DBCLOBs), and large object locators

• SQLCA access for detailed DB2-specific diagnostic information

Figure 4 on page 40 compares the DB2 CLI and DB2 ODBC drivers.

Figure 4. DB2 CLI and ODBC Drivers

In an ODBC environment, the driver manager provides the interface to the application. It also dynamically loads the necessary driver for the database


server to which the application connects. It is the driver that implements the ODBC function set.

In a CLI environment, the DB2 CLI is a self-sufficient driver that provides the interface to the application and passes the SQL requests directly to DB2.

5.3.3 Java Database ConnectivityThe JDBC API is a standard SQL database access interface developed by Sun and its Java partners. Using JDBC, you can access a wide range of relational databases from a Java program. JDBC is now a standard part of the Java platform and is included in the Java development kit (JDK).

The JDBC API defines Java classes to represent database connections, SQL statements, result sets, etc. It allows a Java programmer to issue SQL statements and process the results. JDBC is the primary API for database access in Java. The JDBC API is implemented through a driver manager that can support multiple drivers connecting to different databases.

The JDBC-ODBC bridge provides JDBC access through most ODBC drivers. Because the bridge requires access to the ODBC driver and the database client, its usage is most appropriate for application server code written in Java in a three-tier architecture. Domino provides such a bridge.

DB2 provides two distinct JDBC implementations:

• Application JDBC driver

Using this driver, you can build Java applications that rely on the DB2 CAE to connect to DB2.

• Applet JDBC driver

Using this driver, you can build Java applets that do not require any DB2 component code on the client.

These JDBC drivers are implemented as a wrapper to the DB2 implementation of CLI. Just like CLI, JDBC is a dynamic SQL interface, where all SQL statements in transactions are evaluated on-the-fly. No prep or bind steps are needed to run a JDBC program. However, JDBC presents a convenient object-oriented version of CLI that makes a JDBC program's structure resemble classical embedded SQL programs.

5.3.4 DB2 Stored ProceduresTypically, applications access the database across the network. Such access can result in a lot of data being transmitted across the network and poor


performance. A stored procedure is a part of your application that runs on the database server. Your client application passes control to the stored procedure, allowing it to perform intermediate processing on the server without transmitting unnecessary data across the network. The stored procedure transmits only those records your application needs (see Figure 5).

Figure 5. Stored Procedure

You gain several benefits form using stored procedures:

• Reduced network traffic

Grouping SQL statements together can reduce network traffic. A typical application requires two trips across the network for each SQL statement. Grouping SQL statements results in two trips across the network for each group of statements, resulting in better performance for applications.

• Access to features that exist only on the server

Stored procedures can have access to commands that run only on the server. They might have the advantages of increased memory and disk space on server machines, and they can access any additional software installed on the server.

• Enforcement of business rules

You can use stored procedures to define business rules that are common to several applications. When an application calls the stored procedure, it processes data in a consistent way according to the rules defined in the stored procedure. If you need to change the rules, you only have to make the change once in the stored procedure, not in every application that calls the stored procedure.


Chapter 6. Platforms and Connectivity

Before you begin to develop a Domino application that accesses a DB2 database, you must understand on which platforms you can install the different components and then decide which network protocol to use to connect the components.

As shown in Figure 6 on page 43, three different machines can be used in a three-tier architecture:

• The user accesses the Domino application through a workstation or a network station.

• The Domino application resides either locally on the user workstation or on a Domino server.

• The DB2 database resides either locally on the Domino application or on a remote server.

Figure 6. From the User Workstation to the Database, Using Domino

You can implement multiple network protocols to connect the user workstation to the Domino server and then to the remote database:


• From the user workstation to the Domino application

The user connects the Domino application on the Domino server either from a Web browser (1) or a Lotus Notes client (2).

When using a Lotus Notes client, the user can also connect the Domino application locally (3).

• From the Domino application to the DB2 database

The Domino application accesses the DB2 database either locally (4) or remotely (5)

If the application runs on the Lotus Notes client, it can directly access the DB2 database (6).

6.1 Platforms

Table 2 shows the different platforms on which you can install a Lotus Notes client and a Domino server.

Table 2. Platforms Supporting Lotus Notes Clients and Domino Servers

Lotus Notes Client Domino Server

DOS

Macintosh OS Yes

OS/2 Yes Yes

Windows 3.1 Yes

Windows 95 or 98 Yes Yes

Windows NT Intel Yes Yes

Windows NT Alpha Yes Yes

SCO UnixWare

AIX Yes Yes

SINIX

HP-UX Yes Yes

Sun Solaris Intel Yes Yes

Sun Solaris SPARC Yes Yes

Novell NetWare Yes

OS/400 Yes


To access the Domino application, you can choose between a running Lotus Notes client or a Web browser.

• The Lotus Notes client supports all of the most popular hardware platforms and operating systems. Thus it is easy to communicate, collaborate, and coordinate across an entire organization and between organizations no matter what the mix of computing environments. And Notes customers are free to choose the hardware and software solutions that best support their operations and leverage their existing infrastructure investment.

• The Web browser, Netscape Navigator or Microsoft Internet Explorer, runs on any Intel or a UNIX workstation.

The Domino application can run on the Lotus Notes client or a Domino server. If the application accesses DB2 data, you have to install either DB2 CAE, DB2 Connect, or a DB2 server, depending on your configuration.

Table 3 shows the different platforms on which you can install DB2 CAE, DB2 Connect, or a DB2 server.

Table 3. Platforms Supporting DB2 CAE, DB2 Connect, or DB2 Server

VM and VSE

OS/390 Yes

DB2 CAE DB2 Connect DB2 Server

DOS Yes

Macintosh OS Yes

OS/2 Yes PE, EE PE, EE

Windows 3.1 Yes PE

Windows 95 or 98 Yes PE PE

Windows NT Intel Yes PE, EE PE, EE

Windows NT Alpha

SCO UnixWare Yes Yes

AIX Yes EE Yes

SINIX Yes Yes

HP-UX Yes EE Yes

Lotus Notes Client Domino Server

Platforms and Connectivity 45

6.2 Protocols

The communication protocol between the Web browser and all Domino servers is TCP/IP, as Domino uses the Internet protocol to support Web users.

The communication protocols that can be used between a Lotus Notes client and a Domino server depend on the types of both machines. Table 4 lists the protocols supported between Lotus Notes clients and the Domino server. The list is restricted to the platforms that support a DB2 component.

Table 4. Domino Protocol Support

Sun Solaris Intel

Sun Solaris SPARC Yes EE Yes

Novell NetWare

OS/400 Yes

VM and VSE Yes

OS/390 Yes

Note: PE: Personal Edition, EE: Enterprise Edition

Domino Protocol Supported

OS/2 AppleTalk, NetBIOS/NetBEUI, TCP/IP, VINES, X.PC, SNA

Windows 95 or 98 SPX, NetBIOS/NetBEUI, TCP/IP, X.PC, ISDN

Windows NT Intel AppleTalk, SPX, SPX II, NetBIOS/NetBEUI, TCP/IP, VINES, X.PC, SNA, ISDN

AIX SPX, SPX II, TCP/IP, X.PC

HP-UX SPX, TCP/IP, X.PC

Sun Solaris SPARC SPX II, TCP/IP, X.PC

OS/400 TCP/IP

OS/390 TCP/IP

DB2 CAE DB2 Connect DB2 Server


The communication protocols that can be used between DB2 CAE or DB2 Connect and a DB2 server depend on the types of both machines. Table 5 lists all the supported protocols based on the type of the client and the server. The list is restricted to the platforms that support Domino.

Table 5. DB2 Protocol Support

Platform DB2 Component Protocols Supported

OS/2

DB2 CAE SPX, NetBIOS/NetBEUI, TCP/IP, SNA, Named Pipes (local)

DB2 Connect TCP/IP, SNA

DB2 Server SPX, NetBIOS/NetBEUI, TCP/IP, SNA

Windows 95 or 98

DB2 CAE SPX, NetBIOS/NetBEUI, TCP/IP, Named Pipes


Windows NT Intel

DB2 CAE SPX, NetBIOS/NetBEUI, TCP/IP, SNA, Named Pipes


DB2 Server SPX, NetBIOS/NetBEUI, TCP/IP, SNA

AIX

DB2 CAE TCP/IP, SNA


DB2 Server TCP/IP, SNA

HP-UX

DB2 CAE TCP/IP

DB2 Connect TCP/IP

DB2 Server TCP/IP

Sun Solaris SPARC

DB2 CAE TCP/IP, SNA


DB2 Server TCP/IP, SNA

OS/400 DB2 Server SNA

OS/390 DB2 Server TCP/IP, SNA


6.3 From Domino to DB2

The Domino application can access DB2 data either locally on the DB2 server or remotely using DB2 CAE or DB2 Connect.

• Local access

The Domino server (or in specific cases, the Lotus Notes client) accesses the DB2 database using the DB2 server installed on the same machine. In this configuration, the operating system must support both Domino (or Lotus Notes) and the DB2 server, for example, OS/2, Windows NT, AIX, HP-UX, OS/400, and OS/390. No network protocol configuration is needed (see Figure 7).

Figure 7. Local Access

• Using DB2 CAE

The Domino server (or the Lotus Notes client) accesses the DB2 server running DB2 UDB on an Intel or UNIX platform. In this configuration you must install DB2 CAE on the Domino server (or the Lotus Notes client) and configure communication to the DB2 server, using a compatible protocol (see Figure 8).

Figure 8. DB2 Universal Database Access


• Using DB2 Connect

The Domino server (or the Lotus Notes client) accesses the DB2 server running DB2 on AS/400 or S/390 using DRDA. Two configurations are possible (see Figure 9):

• Using DB2 Connect Personal Edition installed on the Domino server (or the Lotus Notes client), you can access the DB2 database. You have to configure communication to the DB2 server, using a compatible protocol

• Using DB2 Connect Enterprise Edition installed on a gateway, you can access the DB2 database. You must install DB2 CAE on the Domino server (or the Lotus Notes client) and configure communication to the gateway, using a compatible protocol. On the gateway, you also have to configure communication to the DB2 server, using a compatible protocol.

Figure 9. DB2 DRDA Access


Chapter 7. Integrating DB2 and Domino

Domino is the world's most popular secure, distributed, collaborative application environment for document-oriented information. DB2 is the top-rated relational DBMS, handling the adhoc structured queries and transaction processing required to manage and operate a business of any size.

Domino and Lotus Notes clients provide a fully integrated environment for distributing reports in mail memos and collaborative databases to desktop clients and Web users.

DB2 provides an easy-to-use interface with Lotus Notes for generating reports on business data. Together, Lotus Notes and DB2 facilitate generating, customizing, and distributing reports in applications.

DB2, like Lotus Notes and Domino, is available on all of the popular server operating systems, including OS/2, Windows NT, AIX, HP-UX, Sun Solaris, OS/400 and OS/390. Lotus Notes and Domino applications can access query and update data on any of these systems.

Experience increased market competitiveness by developing and relying on applications that combine the strengths of Lotus Notes and DB2, to ensure that your solution can efficiently manage any kind of information, anywhere, anytime.

7.1 The Power of Integration

Lotus Notes and Domino applications differ significantly from traditional DB2 applications. Whereas Notes and Domino focus on the distributed capture of semistructured data through compound documents, DB2 focuses on the point-in-time capture of structured data and basic business transactions. Lotus Notes developers can easily extend existing Domino applications with interactive access to DB2 data, making traditionally hard to reach data available to Notes and Web client users. Of course, this difference in no way implies incompatibility. Quite the contrary, as a messaging and groupware platform, Notes and Domino applications complement DB2 applications such that both system types draw on and reinforce one another’s strengths.


Table 6, Table 7 on page 53, and Table 8 on page 54 summarize the key differences between Domino applications and DB2 applications.

Table 6. Characteristics of Domino and DB2 Applications: Part I

Domino DB2 Comments

Type

- Text, rich text- Multiple choice list- Number- Times or dates

- Text, rich text- Number- Times or dates- Large objects

Domino is capable of storing a large variety of type styles, graphics, and multimedia objects. Rich text includes voice, video, binary objects, and multifont text, tabular data, Web pages, and linked or embedded objects. DB2 handles the same variety of type styles. Graphics and multimedia objects can be stored in DB2 large objects.

Data Store

Distributed Lotus Notes database

Distributed DB2 databases

A Lotus Notes database is accessed by a Lotus Notes application running on a Lotus Notes client or a Domino server.DB2 resources are accessed by a wide range of applications and tools, including transaction processing systems, query tools, and enterprise applications.

Data Scope

Workgroups with distributed and replicated databases

The entire company with centralized databases. Database can be distributed among workgroups.

The location of the data affects its scope. If data is stored in the enterprise database, it is available to the whole company. If data is stored in the workgroup server, it is available only to the group.

Data Integrity

Managed at the application level; there are no tools to manage data integrity at the definition level.

Managed at the definition level by using referential integrity rules.

When defining the relationships between the data,do not create cross-environment references as there is no way of maintaining data integrity between the two environments.


Table 7. Characteristics of Domino and DB2 Applications: Part II

Domino DB2 Comments

Data Input Control

Through Domino application

Through enterprise application

Depending on the scope of the data, you must define where the controls are located.

Data Structure

Semistructured Highly structured Domino handles unstructured data as rich text. An enterprise application handles highly structured, related data.

Application Mode

Supports mobile and remote users

Supports online processing

An integrated Domino application that accesses DB2 data must be able support both disconnected and online processing.

Network Support

Independent of the hardware and network infrastructure

Dependent on the hardware and network infrastructure

Domino works in any network environment. Notes databases and the network infrastructure that makes them available are not restricted to a predetermined set of components. Through Notes and Web clients, Notes applications can be shared easily and securely with customers, suppliers, and vendors with disparate systems and environments, facilitating greatly simplified interenterprise application sharing.DB2 determines the components used to build the network infrastructure. Sharing the data and applications with suppliers, customers, and vendors may require those outside users to conform to a predetermined set of network specifications.

Integrating DB2 and Domino 53

Table 8. Characteristics of Domino and DB2 Applications: Part III

Domino DB2 Comments

Business Logic

Ad hoc processes performed by the Domino application. They are located on either the client for remote and disconnected use or on the server through the use of agents.

Defined business processes performed by a routine or a DB2 stored procedure

Depending on the scope of the application, you must define where the business logic is located. If it is implemented in the enterprise application, the same business logic is applicable for the entire company.

Unit of work

No Yes Because no formal unit of work exists within Domino, the application should ensure that the logical units of work do not spread over both environments. Unit of work management (commit scope, logging, locks,...) applies only in the resource managers (MQSeries, DB2)

Operation

Control distributed operations with periodic updates through Notes replication, a powerful and cost-effective means of supporting distributed operations and occasionally connected users.

Control concurrent operations by using locking and isolation levels that ensure database integrity

Although both environments support concurrency, they do not implement its support in the same way: the Domino environment allows concurrent access and then resolves conflicts; the enterprise application environment does not allow concurrent access.

Backup and recovery

System level System, application, and database level

Each environment has its own backup and recovery mechanisms. There is no way of synchronizing them. Therefore, the architecture of the integrated solution must not rely on synchronized environments.


7.2 Successful DB2 and Domino Integration

Consider the benefits of integrating DB2 and Domino:

Report DistributionLotus Notes provides a fully integrated environment well suited to the task of distributing information. Reports can be distributed in mail memos and collaborative databases to desktop clients and Web users alike. DB2 data can be copied into Lotus Notes applications for the purpose of providing easy access to summarized business data and reports.

ArchivingLotus Notes applications can exploit the scalability of DB2 by transferring less frequently accessed data to DB2 tables. Lotus Notes can be used to store and manipulate the more active documents, and DB2 to archive the least recently accessed data. This approach offers you an easy-to-manage, scalable system that ensures high performance for data analysis or modeling.

Web User ProfilingComplete Web user profiling can easily be implemented with a Domino and DB2 environment. Lotus Notes Web applications can capture user information before granting them access to the site. DB2 tables can be used to log this information for billing or marketing purposes.

Complementary Object StoreThe DB2 object extensions provide powerful built-in functions that enable you to integrate large data objects, such as images, into Lotus Notes applications. Storage of the data object in the Lotus Notes database may not be practical, or desired, especially where data changes rarely and is required infrequently. DB2 can be used as a back-end object management system that Lotus Notes applications can exploit.

Data WarehousingDB2 is the ideal platform for creating a data warehouse or data mart, issuing online analytical processing queries, and enabling a wide range of business intelligence and data mining activities. Lotus Notes applications are not necessarily suited to analysis of large amounts of data. With DB2, you can fully exploit your operational data to help you make informed decisions about your business.

Data DistributionKey business data is often part of an operational DBMS that may not be accessible to people in remote locations or in other organizations. Lotus Notes and Domino is an ideal environment for the distribution of data between

Integrating DB2 and Domino 55

servers and workstations where access to the DBMS is either too difficult to provide or not desirable for security reasons. Lotus Notes applications can be used to provide alternative access to corporate data, particularly when it needs to be distributed to other sites on a regular basis.


Chapter 8. Methods of Integration between Domino and DB2

A variety of integration techniques and products are available to leverage the data storage and manipulation power of DB2 and the messaging and groupware capabilities of Domino. They fall within the following categories:

• Native programmatic Domino access to DB2 from a LotusScript program

• @DbFunctions • LotusScript Data Option (LS:DO) • DB2 LotusScript extension (DB2LSX) • Lotus Domino Connector LotusScript extension (LC LSX)

• Native programmatic Domino access to DB2 from a Java program

• Java Server agent • Java servlets

• Native nonprogrammatic Domino access to DB2

• Domino Enterprise Connection Services (DECS) • NotesPump Realtime Notes activity

• Server-to-server high-volume data transfer

• NotesPump • Lotus Enterprise Integrator (LEI)

• Domino access to DB2 data through a transaction system

• MQSeries and CICS Connections for Domino

• Programmatic access from a C or C++ program

8.1 @DbFunctions

The Lotus Notes formula language contains a set of built-in macros, functions, and commands. The functions are prepackaged formulas. Lotus Notes has more than 100 functions.

With the Lotus Notes @DbFunctions, you have a fast and easy-to-use read-only access method to ODBC-compliant DBMSs. These functions enable you to:

• Generate keyword lists

• Perform lookup operations

• Launch stored procedures and queries stored in external databases


@DbFunctions offer concise, efficient access to databases without the need for LotusScript coding, which makes them extremely useful for fast and compact application development. Each of the @DbFunctions is optimized for specific tasks, which include connecting to the external database, performing queries, caching the result set, and closing the database connection.

There are three @DbFunctions:

• @DbColumn generates a keyword list from either a Lotus Notes database or an ODBC-compliant DBMS.

• @DbLookup looks up a value in one field based on the value of a related field in the same Lotus Notes form or table in the external DBMS.

• @DbCommand causes SQL queries to be passed to the external DBMS.

8.1.1 Usage@DbColumn and @DbLookup can only retrieve data. They cannot add, delete, or modify data. These two @DbFunctions are intended mainly for keyword formulas. Instead of hard-coding a list of keywords and then periodically updating that list, with @DbColumn and @DbLookup you can dynamically retrieve a list of values from DB2.

@DbCommand can retrieve data or send other SQL statements that can change data.

8.1.2 Technical ConsiderationsAll of the @DbFunctions can return no more than 64 KB of data.

Figure 10 shows how Domino processes an @DbFunction.

Figure 10. @DbFunction Process


Each time you issue an @DbFunction, Domino allocates an ODBC connection from either the Lotus Notes client or the Domino server to DB2, processes the query request, gets the result set, and eventually disconnects the connection. Because this connection process is resource-consuming, be careful when using @DbFunctions in your application.

8.2 LotusScript Data Object

The LS:DO provides full read and write access to external ODBC data sources, using the complete control and flexibility of LotusScript, Domino’s native structured programming language.

The design of the LS:DO is consistent with LotusScript’s BASIC syntax and other LotusScript Notes classes, making it easy to learn for anyone familiar with LotusScript itself, or with BASIC or Microsoft Visual Basic.

The LS:DO consists of three classes:

• ODBCConnection

• ODBCQuery

• ODBCResultSet

These classes come complete with a powerful set of properties and methods and full SQL capabilities.

8.2.1 ProcessUsing ODBC, LS:DO can access a DB2 data source through the DB2 ODBC driver provided with DB2 CAE or DB2 Connect.

Figure 11 on page 60 shows the LS:DO process.

Methods of Integration between Domino and DB2 59

Figure 11. LS:DO Process

The process consists of the following steps:

1. Using LS:DO APIs, the application program makes a call to the ODBC APIs.

2. The application uses the three LS:DO objects.

3. The ODBC driver manager parses the requested command. This manager is a set of APIs in the ODBC DLL.

4. The ODBC driver manager loads the DBMS ODBC driver according to database resource information registered in advance through the operating system.

5. The requested command is passed to the DBMS ODBC driver for the database being accessed.

6. The DBMS ODBC driver constructs a series of commands using the DBMS SQL language, and sends the commands to the DBMS.

7. The results are sent back to the calling routine.

8.2.2 UsageThe LS:DO is excellent for real-time data access from any LotusScript event in Notes, such as clicking a button, exiting a field, or opening a document. The LS:DO is available on both the Lotus Notes client and the Domino Web server. The LS:DO real-time data access is the best alternative for optimizing data entry, and when mobile users make queries and updates.


Optimizing data entry You can use Notes as the data entry point for an application that synchronizes data with DB2 or use DB2 for long-term data storage and archiving. The LS:DO provides the following functions:

• On-the-fly look up

Once you enter input data in a field and exit the field with the TAB key or a mouse click, LotusScript code can immediately perform an SQL query to DB2, retrieve some associated information that matches the input data, and fill in the remaining fields in the form, such as address, city, phone, and contact name.

• Immediate updates

LotusScript gives you the flexibility to update the information in DB2 the moment a user saves a new document in Notes or in batches at scheduled intervals. When a user creates another new document in Notes, you can be sure that document will access the most current information in DB2.

• Input validation

Is the right salesperson assigned to a given customer in the Lotus Notes form? Is the regular salesperson for a given region currently overloaded with assignments, indicating that a backup person should be assigned to the task? The LS:DO retrieves that information from DB2. LotusScript’s fully structured programming constructs enable you to evaluate the information and act accordingly.

• Avoiding duplicate entries

Once a user enters a customer’s name, the LS:DO can query the DB2 table for variations on that name to ensure, for example, that the same customer is not entered with an Inc. as opposed to a Co. in DB2.

8.2.3 Technical ConsiderationsIn addition to allowing you to issue SQL to DB2, the LS:DO offers several data manipulation capabilities. The LS:DO supports and manages result sets as well as providing an interface for directly using SQL when appropriate. The result set management takes the form of caching result sets, supporting navigation through the result sets, and managing individual row updates regardless of the underlying driver's cursor or ODBC conformance capabilities.

The three classes that make up the LS:DO (ODBCConnection, ODBCQuery, ODBCResultSet) provide you with the following benefits:

• Multiple query and result sets


You can define multiple query objects to generate multiple result set objects, all of which can be executed against the same connection and manipulated from the same script.

• Bidirectional scrolling over result sets

The ODBCResultSet object provides a scrolling cursor with methods for navigating to the next, previous, first, and last rows.

• Result set search

The LocateRow method of the ODBCResultSet object enables you to search for specific rows within the result set according to specified criteria. This search capability executes faster than multiple queries or comparing values from multiple rows in LotusScript.

• Cached results

The query result in the ODBCResultSet object is optionally cached in memory (default setting), so it can be accessed later by other events in the form, increasing performance and reducing DB2 connection time. In addition, the cached result set enables you to locate later records, using the LocateRow method.

• Update services

Using ODBC directly, you must compose and execute an UPDATE, INSERT, or DELETE statement that uniquely identifies the row you want to modify. LS:DO composes these statements for you according to the query you used and executes them through its UpdateRow or DeleteRow methods. The query you used must still include enough columns to uniquely identify a row. Each change goes to the back-end database when you execute the method.

• Driver transparency

Once the application is developed with a DB2 back end, the LS:DO provides the same level of behavior across all drivers and databases. You do not have to write separate scripts for separate drivers.

8.3 DB2LSX

The DB2LSX provides native access to DB2 through the DB2 CLI. Based on the same model as the LS:DO, the DB2 LSX is a set of three classes:

• DB2Connection

• DB2Query

• DB2ResultSet


These classes access DB2 data natively as well as enable you to use DB2 extended functions, such as support for DB2 user-defined data types and large objects.

The DB2 data access classes provide properties and methods for accessing and updating tables in external databases. These classes are packaged as an LSX file called the DB2LSX. They provide access to DB2 through the DB2 CLI and to non-DB2 databases through the ODBC Version 2.0 standard.

Similar to ODBC, the CLI is a callable API for database access and is an alternative to the embedded SQL API. It is supported by the DB2 family of database servers.

DB2LSX and LS:DO are similar. You can use either to access DB2 databases. There are, however, a few key differences (see Table 9).

Table 9. DB2LSX and LS:DO

You can use DB2LSX to work with DB2 large objects, user-defined data, and binary data.

With LS:DO, you access DB2, using ODBC. With DB2LSX, you access DB2, using the DB2 CLI.

By default, using DB2LSX, additions and changes are not final in the database until you use the Transact method on the DB2Connection object. Using LS:DO, additions and changes are committed when the UpdateRow or DeleteRow methods are executed; that is, the default for autocommit is OFF for DB2LSX and ON for the LS:DO.

Although DB2 access is native, DB2LSX Version 1.1 requires that you register a DB2 database as an ODBC source. DB2LSX Version 1.1 must

DB2LSX LS:DO

Data access Text, number, date, large objects, user-defined data, binary data

Text, number, date

Driver Accesses DB2 through DB2 CLI

Accesses DB2 through DB2 ODBC

Change and add data No autocommit by defaultUse the Transact, Commit, and Rollback method

Autocommit by default when UpdateRow or DeleteRow is executed. Use CommitTransactions and RollbackTransactions methods


know before it makes a connection whether the source is DB2 or not. Putting the DB2 database in the ODBC registry provides that information. If the registry indicates that the source is a DB2 database, the ODBC driver manager is not used. The DB2 CLI is used instead. DB2LSX Version 1.2 does not have this requirement.

8.4 Lotus Domino Connector LSX

To enhance the Domino Web server by adding to its rich set of services and application model, allowing you to create applications that seamlessly integrate Domino workflow and collaboration processes with enterprise data, Lotus has announced two new Domino enterprise integration components: Lotus Domino Connectors (LC) and Domino classes.

The Connectors are modules that extend Domino functionality with native connections to enterprise systems. Lotus has developed connectors for:

• DB2 UDB

• Oracle

• Sybase

• ODBC

• EDA/SQL

• File and text systems

In addition, Lotus plans to offer LCs to other leading enterprise systems including ERP applications and transaction processing monitors. LCs are accessible through Domino application forms, LotusScript, and Java classes, presenting an efficient development environment.

Lotus provides new classes to programmatically connect Domino to additional external enterprise systems through a consistent object model. The new classes are available in LotusScript—the Lotus Domino Connector LSX (LC LSX)—and in Java. They offer you a choice of development platforms and a single object model to access a variety of external data sources from Domino applications.

Additionally, a new LC toolkit will be made available to Lotus Business Partners and developers to create additional LCs. At the time this book was written, we used the beta version of the DB2 LC and the LC LSX. The DB2 LC and the LC LSX are available with Domino Release 4.63 on the following platforms: Windows NT 4.0, Windows NT Alpha, Windows 95, OS/2, AIX, Solaris Intel Edition, Solaris SPARC, and HP-UX.


8.5 Java and JDBC

Domino supports the Java technology in the following ways:

• Since Domino Release 4.5, the Notes client has been able to run Java applets. With Release 4.6, you can insert a Java applet directly on a form so that the applet is included in each document created from the form, or you can insert an applet in a rich text field of a document to include it only in that document. When a Java applet is displayed using a Web browser, the display is under the control of the Web browser.

• A number of Java Notes classes are shipped with Domino Release 4.6. Domino supports Java agents, Notes API programs written using Java 1.1.x. The Java agent’s function is the same as the traditional Lotus Notes agent, and all the features of a Lotus Notes agent can be found in a Java agent. Java agents also have full agent security, such as signing, and restricted/unrestricted authors. They also have the full agent scheduling and triggering ability from both the client and the server. Java agents can be run in the foreground or the background. They can also be replicated.

• Domino 4.6 supports the JavaSoft servlet classes and interfaces, which are a Java standard extension providing Web application developers with a simple, consistent mechanism for extending the functions of a Web server. They can almost be thought of as applets that run on the server side.

Domino supports programs written with the JDK 1.1.1 and the JDBC API. As such any applet, server agent, or servlet can send SQL statements to DB2 and retrieve the results.

Follow these steps to create an applet, a server agent, or a servlet that accesses DB2 data:

1. Import the JDBC DriverManager classes (java.sql).

2. Load the appropriate JDBC driver:

• The JDBC-ODBC bridge, in Domino Release 4.6, that interfaces with the local ODBC driver manager

• The DB2 native application JDBC driver, in DB2 CAE or DB2 Connect • The DB2 native applet JDBC driver

3. Connect to a database, using a JDBC uniform resource locator (URL).

4. Pass SQL statements to the database.

5. Receive the results.

6. Close the connection, the statement, and the result set.


Figure 12 illustrates how the DB2 applet JDBC driver works. The driver consists of a JDBC client and a JDBC server. The JDBC client driver is loaded on the Web browser or the Lotus Notes client along with the applet. When the applet requests a connection to a DB2 database, the client opens a TCP/IP socket to the JDBC server on the machine where Domino is running. After a connection is set up, the client sends each of the subsequent database access requests from the applet to the JDBC server though the TCP/IP connection. The JDBC server then makes corresponding CLI (ODBC) calls to perform the task. On completion, the JDBC server sends the results back to the client through the connection.

Figure 12. DB2's JDBC Applet Implementation

Figure 13 illustrates how a DB2 application JDBC driver works.

Figure 13. DB2's JDBC Application Implementation

You can think of a DB2 JDBC application as a DB2 CLI application, except that you write it using the Java language. Calls to JDBC are translated to calls to DB2 CLI, through Java native methods. This dependency requires that the


DB2 CAE component be installed at the client. A JDBC request flows through DB2 CLI to the DB2 server through the CAE communication flow.

Writing a Java JDBC application or applet is very similar to writing a C application using DB2 CLI or ODBC to access the database. The primary difference between applications and applets is that an application requires the DB2 CAE to be installed on the client and uses the CAE to communicate with DB2; an applet depends on a Java-enabled Web browser and does not require any DB2 code on the client.

You have to treat applets differently from applications, as applets are delivered over the Web. You must install the DB2 server or client on the same machine as your Web server. The JDBC applet and application support is installed as part of DB2.

8.6 Domino Enterprise Connection Services

DECS is a new forms-based technology that will be a feature of future Domino releases. DECS enables you to integrate live data from enterprise systems natively into Domino applications through synchronous access.

With DECS you can open, create, update, or delete external, back-end data, directly and transparently through your familiar Notes client. By extension, Web clients can open the same Notes forms by accessing a Domino Release 4.6 or higher server and obtain real-time access to supported external source data. DECS Realtime activities support a range of external data sources. Currently supported data sources include:

• DB2

• EDA/SQL

• ODBC

• Oracle

• Sybase

At the time this book was written, we used the beta version for Windows NT. DECS is shipped with Domino Release 4.6.3 on the following platforms: Windows NT 4.0, Windows NT Alpha, Windows 95, OS/2, AIX, Solaris Intel Edition, Solaris SPARC, and HP-UX.

DECS provides an easy-to-use forms-based interface that lets you integrate connectivity to external data from Domino applications. With DECS, you work with a nonprogrammatic template application to make external source data an integrated part of any Domino application. If you are a NotesPump user,


some of this may sound familiar to you. As a matter of fact, DECS is an enhancement of the NotesPump Realtime Notes activity that is integrated into Domino 4.63 and 5.0 servers.

DECS provides seamless real-time integration between Domino applications and data in enterprise systems, letting you store application data in either the Domino object store or another system such as a relational database. You can use the DECS technology to pull information from back-end systems into Domino applications in real time. NotesPump's functionality adds to the functionality of DECS by providing connectivity between systems and allowing large volumes of data to be transferred or synchronized between systems.

Once a system administrator has created the DECS Realtime activity, Notes users can open, create, update, or delete DB2 data directly and transparently through their familiar Lotus Notes client. By extension, Web clients can open the same Notes forms by accessing Domino Release 4.6 or higher and obtain real-time access to DB2.

Using DECS, you can create Domino applications that access DB2 in real time without programming. The DECS Realtime activity intercepts Notes database events. For example, when users open, create, update, or save Notes documents, the DECS process intercepts and acts on the corresponding Notes events, obtaining real-time access from the Notes form to DB2. End users can work with DB2 data as if it were in Notes. DB2 connectivity software is not required on the client system. Network access to the external data source is handled by the Domino server machine, which contains the connectivity software for the external data source, such as DB2. No additional coding is necessary in the Notes application. In addition, it is possible to control which fields are actually stored in the Notes database, significantly reducing storage requirements on the Notes side.

When creating a DECS Realtime activity, several items are required to provide real-time data access from a single Notes form. Each DECS Realtime activity monitors a specific Notes database and requires a Notes form to define the metadata. A single external data source definition indicates the data source to connect to and the metadata to use. Key and field mappings are also required.

Several DECS Realtime activities can monitor different databases, a single database or even a single form. Therefore a single document can be populated in real time with data from multiple external databases, using a DECS Realtime activity for each of the various back-end data sources.


8.7 NotesPump and Lotus Enterprise Integrator

NotesPump, and its successor, the LEI, can execute the following types of activities to move and manage data:

• Command activity

Command activities allow an action to be performed against any NotesPump Link. Actions include initiation of DB2 stored procedures and Lotus Notes agents.

• Direct Transfer activity

With the Direct Transfer activity, NotesPump users can schedule the transfer of data from any NotesPump data source to any supported destination, according to user-defined conditions created through SQL queries and Notes formulas.

• DPROPR activity

The DPROPR activity transfers data between DPROPR CCD DB2 databases and NotesPump-supported databases.

• Polling activity

NotesPump uses Polling activities to define conditions to monitor in Notes or relational DBMSs. When a condition is satisfied, NotesPump immediately initiates a specified activity to perform data exchange.

• Realtime Notes activity

A Realtime Notes activity catches and handles Notes events as they occur. Using the Realtime Notes activity established by the system administrator, end users can open or update Notes forms, causing real-time queries or updates to back-end supported NotesPump sources. This capability can be accessed from a Notes client, or through a Web browser accessing a Domino server.

Realtime Notes Activities offer similar function to DECS Realtime activities.

• Replication activity

NotesPump supports two different types of replication activities, whose purpose is to ensure the synchronization of relational data from different sources. Primary Key replication allows the NotesPump user to specify a primary key in the metadata to be used to determine which documents and records are to be replicated. Primary Key/Timestamp replication allows faster synchronization of data sources based upon additional datetime criteria.


• Scripted activity

LotusScript can be used to extend form-based activities with data massaging and conditional processing routines. The Scripted activity executes the LotusScript language commands directly or as stored to a defined Notes agent identified in the activity.

• Java activity

A Java activity created within the NotesPump administrator executes a Java application. Specifically, NotesPump defines a set of Java classes, such as Activity and Stream. Using NotesPump Java classes, you can extend beyond the functionality available within the NotesPump Administrator declarative activities.

8.8 MQSeries and CICS Connections for Domino

Many organizations use host-based mission-critical applications built on DB2 and online transaction processing (OLTP) systems such as CICS or IMS. Therefore they have already implemented programs that read, update, create, or delete data stored in DB2. In such a configuration, Domino offers the MQSeries and CICS Connections for Domino for connecting to the programs that access the data.

You can use the MQSeries and CICS Connections for Domino to access DB2 data from the Domino application using an existing program or transaction running on the back-end server. This method has multiple advantages:

• Any existing transaction program that reads, creates, updates, or deletes data can be used.

• The transaction program uses static SQL, improving performance and allowing a more restrictive security implementation.

• The transaction program is optimized to access the data as it runs on an OLTP system.

• The transaction program controls and validates all data before updating it from all users and applications of the organization, thereby minimizing data integrity exposure.

MQSeries and CICS Connections for Domino is an enterprise integration product that delivers connectivity between the Lotus Domino server, any Web browser or Lotus Notes client, and transaction systems such as CICS and IMS, or linking software such as MQSeries. It has two components:


• The MQSeries Enterprise Integrator (MQEI) is a combination of an extension to LotusScript and two Lotus Notes databases for message, service, and security definitions.

• The MQSeries Link LotusScript Extension (MQLSX) is the MQSeries interface (MQI) fully exposed as LotusScript.

As we do not cover connecting to DB2 through the MQSeries and CICS Connections for Domino, refer to the redbook, Lotus Solutions for the Enterprise, Volume 4, Lotus Notes and the MQSeries Enterprise Integrator, SG24-2217, for more information about this type of connection.

8.9 Programmatic Access

If the connectors described in this chapter are not available on your platform or do not fit your needs, you can still develop your own connection, using a routine that interfaces the Domino database with DB2.

Lotus offers tools to program Domino using LotusScript, C, C++, or Java:

• Lotus Domino Toolkit for Java 1.1

The Lotus Domino Toolkit for Java enables you to write, test, and debug Domino agents using your favorite Java IDE.

• Lotus Notes C API

The Lotus Notes C API provides C developers with access to Notes’ robust distributed, replicated object store, integral messaging, advanced security, and global directory through a comprehensive, granular, multiplatform interface.

• Lotus Notes C++ API

The Lotus Notes C++ API provides developers with an easy-to-use object-oriented interface to Lotus Notes R4.x and beyond. It consists of a set of C++ classes that allow application programs to create, access, and manage Notes databases.

• Lotus Notes HiTest C API

The Lotus Notes HiTest C API is an alternative higher level C interface to the standard Lotus Notes C API. Program development is significantly faster and requires a fraction of the API code needed with other APIs.

• LotusScript Extension Toolkit

The LSX Toolkit expands LotusScript functionality by allowing you to write custom modules that are tightly integrated with both the Lotus Notes and


Lotus Suite environments. The LSXs are separately loadable modules that implement one or more LotusScript classes.

At the time this book was written some connectors were not available on the Domino for S/390 platform. The redbook, Enterprise Integration with Domino for S/390, SG24-5150, provides extensive samples on how to develop connectors to access DB2/ESA, CICS/ESA, IMS/ESA, and MQSeries/ESA from a Domino application.


Chapter 9. Choosing the Right Tool or Product

In this chapter we explain the benefits of the various integration approaches and discuss which tools or products are most suitable in certain situations.

9.1 Platforms

Not all the tools are available on all platforms. Therefore you have to select carefully a tool that is available on your Lotus Notes client, if your application runs on the client, or a tool that is available on the Domino server, if your application serves Web users. Table 10 on page 73 and Table 11 on page 74 list only those platforms that support Lotus software—Lotus Notes client and/or Domino server—and DB2 software—DB2 CAE or a DB2 server.

Table 10 on page 73 list the tools available on the Lotus Notes client platforms.

Table 10. Lotus Notes Client PLatforms: Tool Availability

OS/2 Windows95 and 98

Windows NT

AIX HP-UX Sun SPARC

@DbFunction Yes Yes Yes Yes Yes Yes

LS:DO Yes Yes Yes Yes Yes Yes

DB2LSX Yes(1) Yes Yes No No No

LC LSX Yes Yes Yes Yes Yes Yes

JDBC Yes Yes Yes Yes Yes Yes

DECSRealtime Notes

No No No No No No

NotesPump(2) No No No No No No

MQSeries and CICS Connections for Domino

Yes Yes Yes Yes Yes Yes

API Yes Yes Yes Yes Yes Yes

(1) Version 1.1.0 only(2) Although the NotesPump server can run on a Lotus Notes client, you can only define Notes links to Notes databases residing on a Domino server.


Table 11 on page 74 lists the tools available on the Domino server platforms.

Table 11. Domino Server Platforms: Tool Availability

9.2 Tools

When considering developing a Domino application that uses DB2 data, you must take many factors into account to choose the right tool. In this section we list application, data, and environment criteria that affect your choice, but you must consider these factors in your own environment. For example, the programming skills of the development team may need to be enhanced through education, or the security level of the application must be the highest available.

9.2.1 Application CriteriaTable 12 on page 77 is a matrix of the tools and the application criteria.

OS/2 Windows 95 and 98

Windows NT

AIX HP-UX Sun SPARC

OS/400 OS/390

@DbFunction Yes Yes Yes Yes Yes Yes Yes Yes

LS:DO Yes Yes Yes Yes Yes Yes Yes Yes

DB2LSX Yes(1) Yes Yes No No No No No

LC LSX Yes Yes Yes Yes Yes Yes No No

JDBC Yes(3) Yes(3) Yes(3) Yes(3) Yes(3) Yes(3) Yes(5) No

DECSRealtime Notes

Yes(4) Yes(4) Yes(4) Yes(4) Yes(4) Yes(4) No No

NotesPump Yes Yes Yes Yes Yes Yes Yes (Yes)(2)


Yes Yes Yes Yes Yes Yes Yes(6) Yes(6)

API Yes Yes Yes Yes Yes Yes Yes Yes

Notes(1) Version 1.1.0 only(2) IBM intends to provide NotesPump on S/390.(3) Domino Version 4.6 or higher to support Domino Java agents(4) Domino Release 4.63 required(5) AS/400 Toolbox for Java required(6) MQLSX only - in beta version


Triggered ProcessesThe application architecture can be based on one or more of the real-time, scheduled, and event-driven processes:

• Real-time process

These are the processes starting an activity the moment a user performs some action. On a Lotus Notes client, real-time processes can be triggered by:

• Opening, closing, saving, or deleting a document • Clicking on an action button in a form or view • Entering or exiting a particular field within a form • Calling a Lotus Notes agent

Unlike a Lotus Notes client, a Web browser does not itself monitor events but can trigger a real-time process by:

• Opening, submitting (saving), or deleting a document • Submitting a URL that runs a Lotus Notes agent on the Domino server.

• Scheduled process

These are two ways to schedule data transfer processes in the Domino environment:

• Agents executed on a Domino server or a Lotus Notes client workstation

Agents can be scheduled to run as frequently as every 30 minutes and as infrequently as once a month.

• NotesPump activities executed on the Domino server

NotesPump activities can be scheduled to run as frequently as every minute and as infrequently as many months.

• Event-driven process

Data transfer processes can be triggered by an event or specific action. The events need not necessarily occur within the confines of a Lotus Notes database. Additionally one event can in turn trigger another process.

Events that can trigger a data transfer process with Domino are:

• Lotus Notes Agent events, such as new or modified documents (if Documents Have Been Created or Modified option), pasted documents (if Documents Have Been Pasted option), or new mail (if New Mail Has Arrived option)

Choosing the Right Tool or Product 75

• NotesPump Polling activity, which triggers a data transfer activity if a specific condition is met. The condition can occur within the external data source, such as DB2.

Data FlowThe tools can support two types of application data flow:

• From Domino

The application is started on the Domino server or the Lotus Notes client and accesses the DB2 data (for example, a Web user application).

• To Domino

The application is started on the DB2 server machine and accesses the Domino environment. Examples of such applications are the MQSeries Trigger Monitor for Lotus Notes or the NotesPump Direct Transfer activity.

Data TypeThe tools can support two types of application data:

• Operational data, that is, the application requires access to the operational data directly and cannot work with copy of the data.

• Copied data, that is, the application accepts a local copy of the operational data.

Activity TypesMost of the tools support applications that perform simple and complex activities:

• A simple activity only copies or accesses data from one source to one target.

Examples of simple activities are data access and lookup, linear copy, and document deletion or insertion.

• A complex activity transfers data from multiple sources to multiple targets or utilizes a parameterized algorithm when doing a transfer.

Examples of complex activities are computational access, multiple data copies, replication, and access with immediate modification.

ModelUsing the tools, the application can be designed following two models:

• Real-time model, where users are waiting for data access before continuing their activities. For example, to fill an order form, the clerk must have immediate access to the customer’s data as well as the product information.


• Batch model, where users start a process that is known to take some time. For example, once the order form is ready, its processing can occur during the night, and the clerk will know the result of the order request the next day.

Access TypeWith some tools, applications can only read data, whereas with other tools, applications can read and write data.

Table 12. Tools and Application Criteria

TriggeringProcess

Data flow Data Type ActivityType

Model AccessType

@DbFunction Real time From Domino

Operational Simple Real time Read

LS:DO Real timeSchedule

From Domino

Operational Simple and complex

Real time or batch

Read and write

DB2LSX Real timeScheduleEvent driven

From Domino


Real time or batch

Read and write

LC LSX Real timeScheduleEvent driven

From Domino


Real time or batch

Read and write

JDBC Real timeScheduleEvent driven

From Domino


Real time or batch

Read and write

DECSRealtime Notes

Real time From Domino

Operational Simple and complex(2)

Real time Read and write

NotesPump (1) ScheduleEvent driven

From and to Domino

Copy Simple and complex(2)

Batch Read and write


Real timeScheduleEvent driven

From and to Domino


Real time or batch

Read and write

API Real timeScheduleEvent driven

From Domino


Real time or batch

Read and write

Notes(1) Excluding NotesPump Realtime Notes activities. (2) Complex activities using pre- and post-event formulas


9.2.2 Data CriteriaTable 13 on page 79 is a matrix of the tools and data criteria.

Data SourceDepending on the tool used, the application accesses data in the following data sources:

• Lotus Notes data managed by Domino

• DB2 data managed by DB2 UDB or a DRDA DB2 server

• Data managed by a DBMS providing an ODBC driver or supporting a vendor ODBC driver

• Data managed by an S/390 DBMS such as IMS or VSAM

DB2 Data TypeDepending on the tool and the DB2 CLI or ODBC driver used, an application can access the following DB2 data types:

• Standard data types, such as text, number, or date

Using the DB2 CLI only, an application can also access the following data types:

• Large object data types, such as binary or character

• User-defined data types

Data VolatilityThe data involved in the application can be:

• Volatile, that is, updated frequently by other applications. In such cases, the application must access the operational data, as a copy may be out of sync.

• Stable, that is, accessed mainly for read with few updates by other applications. In such cases, the application can possibly copy the data locally and work on the local copy.

Volume of DataYou need to understand the volume of data that the application needs to run:

• If the volume is moderate, you can develop an application that accesses remote data. The performance overhead due to the network transfer is not important.

• If the volume is high, you have to tune the network utilization. You may need to implement optimization techniques, such as data blocking, to transfer the data to the local machine.


Table 13. Tools and Data Criteria

Data Features Data Source DB2 Data Type Volatility Volume

@DbFunction DB2 and all ODBC-compliant data sources

Text, number, date High Moderate

LS:DO DB2 and all ODBC-compliant data sources


DB2LSX DB2 and all ODBC-compliant data sources (2)

Text, number, date Binary and character large objects user-defined

High Moderate

LC LSX DB2 and all ODBC-compliant data sources (2)


High Moderate

JDBC DB2 and all ODBC-compliant data sources


DECSRealtime Notes

DB2 and all ODBC-compliant data sources


High Moderate

NotesPump (1) DB2 and all ODBC-compliant data sources


Low High


DB2, IMS, VSAM or any file through the MQ program


API DB2 or any file through the local program


Notes(1) Exluding NotesPump Realtime Notes activities.(2) Access any ODBC data source using ODBC


9.2.3 Environment CriteriaTable 14 on page 81 is a matrix of the tools and the environment criteria.

DB2 Data AccessTo define the DB2 data requested, you can use:

• SQL

• Non-SQL definitions, such as the DECS field mapping panel or the LC LSX Fieldlist connection methods

DB2 ProgrammingTo access DB2 data, you can use:

• ODBC APIs, which are also supported on other DBMSs with no modifications

• CLI APIs, which allow access to DB2-unique features such as BLOBs, CLOBs, or UDFs.

• JDBC APIs, which allow Java applications and applets to access DB2 data

• Static SQL, which offer the greatest performance and full security

• Dynamic SQL, which offer great flexibility

• Stored procedures, which allow DB2 server resources to be used as part of the application

Domino Application ProgrammingTo create the Domino application, you can use:

• macro language, which allows you to create quickly limited applications

• LotusScript, which allows you to create BASIC-like full-function Domino applications

• Java, which allows you tu use Java to create full-function Domino applications.

SupportThe tools can be used on either a Lotus Notes client or a Domino server. In both cases, a connection to the DB2 database must exist from the platform. DB2 CAE, DB2 Connect, or a DB2 server must be installed and customized on the platform.


Table 14. Tools and Environment Criteria

DB2 Data Access

DB2 Programming Domino Application Programming

Support(3)

@DbFunction ODBC Yes, macro language using three functions

Lotus Notes clientDomino server

LS:DO SQL ODBCStored procedures(2)

Yes, full LotusScript environment


DB2LSX SQL ODBCStored procedures(2)



LC LSX SQL not required but available

ODBCStored procedures(2)

Yes, full LotusScript and Java environments


JDBC SQL JDBC-ODBC driverDB2 JDBC driversStored procedures(2)

Yes, full Java environment


DECSRealtime Notes

SQL not required but available


No Domino server

NotesPump (1) SQL not required but available


Not required but available

Domino server


SQL Static or dynamic embedded SQL CLI Stored procedures(2)



API SQL Static or dynamic embedded SQLCLIStored procedures(2)

Yes, full LotusScript or Java environment


Notes(1) Excluding NotesPump Realtime Notes activities.(2) The function or stored procedure has to be developed using C, C++, COBOL, or Java (3) Requires DB2 CAE or a DB2 server on the Lotus Notes or Domino platform


Chapter 10. Installation

In this chapter, we explain how to install the different tools that support using DB2 in a Domino environment.

10.1 Millennium Cafe Sales Tools Plus Application

For Lotussphere 98 in Berlin, the marketing team developed the Millennium Cafe Sales Tools application, a sample application that illustrates some tools to access DBMS data from a Domino application. For this project we enhanced that application and created the Millennium Cafe Sales Tools Plus application, to explain each tool. Figure 14 on page 83 shows our test environment.

Figure 14. Millennium Cafe Sales Tools Plus Environment

The Millennium Cafe Sales Tools Plus database contains a sample application that illustrates methods of accessing databases using the following tools:

• @DbFunctions

• LS:DO

• DB2LSX


• LC LSX

• Java server agents and servlets using the JDBC API

• DECS

• NotesPump

The sample application can access either a local DBASE file or a DB2 database. DB2 can be installed easily on the same machine or remote machine.

The sample application is set up to be a Domino application for use by Web browser clients. Minimum functions work for Lotus Notes clients. However, you could modify this application to work with both Web browsers and Lotus Notes clients, by changing agent triggers and placing some of the agent scripts in the appropriate forms.

We installed this environment on two servers:

• Domino server running:

• Domino Server Version 4.6.1, available as a 90-day evaluation version on the Lotus developer Web site

• LS:DO, included in the Domino server product

• DB2LSX Release 1.2.0, available on the Lotus Enterprise Integration Web site

• DECS beta version

• NotesPump Version 2.5, available as an evaluation version on the Lotus Enterprise Integration Web site

• DB2 CAE, included in the DB2 UDB server

• DB2 JDBC Driver, shipped with DB2 CAE

• DB2 Universal Database Version 5.0, available as an evaluation version on the IBM DB2 Web site

A Lotus Notes database containing the Millennium Cafe Sales Tools Plus application is available for download on the IBM Redbooks Web site. Click on the Additional Materials button, select the SG244918 directory, and select the files to download.

CafePlus.nsf is the Lotus Notes database containing the Millennium Cafe Sales Tools Plus application.


For the URLs for the above Web sites, see Appendix I.3, “Other Publications and Web Sites” on page 198.

In our environment, the Domino server supporting Web users ran on a Windows NT Version 4.0 platform. It accessed two DB2 databases, one managed by DB2 UDB on a Windows NT platform, and the other managed by DB2 for OS/390 on an OS/390 platform. We used TCP/IP as the connection protocol.

In the sections that follow, we explain the steps required to install and customize the products and illustrate them by giving the configuration used in our environment.

10.2 DB2 CAE Configuration

Table 15 on page 85 shows the TCP/IP values used to configure the configuration between the DB2 server and the DB2 CAE..

Table 15. DB2 UDB TCP/IP Configuration Information

On the DB2 UDB server, we created, using the db2sampl command, the SAMPLE database. The creation program does not create qualified tables. As we logged in using CHRISTO as the user ID, the table names have to be qualified by CHRISTO in order to access them. We used the CREATE ALIAS statement to define aliases to the tables:

Parameter Description Value

hostname Hostname of the server. To resolve this parameter, issue the hostname command at the server.

ob

ip_address IP address of the server. To resolve this parameter, issue the ping s_hostname command.

9.1.150.60

svcename The connection service name is an arbitrary name used to represent the port number (Port_number) on the client. (The svcename parameter is located in the database manager configuration file on the server.)

db2tcp

Port_number/tcp The port number for the client must be the same as the port number to which the svcename parameter maps in the services file on the server.

3700/tcp

Installation 85

CREATE ALIAS CAFE.EMPLOYEE FOR CHRISTO.EMPLOYEE

CREATE SYNONYN is accepted as an alternative for CREATE ALIAS.

If you are using DB2 CAE or DB2 Connect to access your DB2 database, you first have to catalog the node where the database is located and then catalog the database.

To catalog the node and the database using DB2 CAE or DB2 Connect on Windows NT, you can use either the client configuration assistant or the command line processor.

In our environment, we used the following commands with the command line processor:

• To catalog the node:

catalog tcpip node db2nt remote ob server db2tcp

where:

• db2nt is the name of the node • ob is the host name of the DB2 UDB server • db2tcp is the connection service name defined in the local services file

for TCP/IP support

• To catalog the database:

catalog database sample as demo at node db2nt

where:

• sample is the alias of the database on the DB2 UDB server • demo is the local nickname on the client

• To test the connection:

connect to demo user db2admin using db2admin

You must be logged on to the system as a user with system administrative (SYSADM) or system controller (SYSCTRL) authority.


10.3 DB2 Connect Configuration

Table 16 shows the TCP/IP values used to configure DB2 Connect.

Table 16. DB2 for OS/390 TCP/IP Configuration Information


hostname Hostname of the OS/390 server. For DB2 for OS/390 remote hosts, the hostname appears in the DSNL004I message (DOMAIN=hostname) when the Distributed Data Facility (DDF) is started.

wtsc48

ip_address IP address of the server. To resolve this parameter, issue the ping s_hostname command.

9.12.14.207

svcename The connection service name is an arbitrary name used to represent the port number (Port_number) on the client.

drda

Port_number/tcp Port number 446 has been registered as the default port number for DRDA. For DB2 for OS/390 remote hosts, the port number is defined in the boot strap data set as PORT and is also provided in the DSNL004I message (TCPPORT=portnumber) when the DDF is started.

446/tcp

Security Type For TCP/IP nodes, SECURITY SOCKS is an option specifying that the node will be SOCKS-enabled, in which case the SOCKS_NS and SOCKS_SERVER environment variables are mandatory and must be set to enable SOCKS.

NONE

Installation 87

To enable a DRDA connection, you have to update the DB2 Connect directories, using the client configuration assistant or the command line processor. Table 17 shows the DRDA values used to configure DB2 Connect.

Table 17. DB2 for OS/390 DRDA Configuration Information

We used the following commands in our environment:

• Node directory

catalog tcpip node db2390 remote wtsc48 server drda

• DCS directory

catalog dcs database db51t as db51

• System directory

catalog database db51t as db51t at node db2390 authentication dcs

• We tested the connection, using:

connect to db51t user db2admin using db2admin

db2admin must be a registered user in RACF, the MVS security subsystem.


Target Database Name

The database on the DRDA server system:- OS/390 The LOCATION value is defined in the DB2 for OS/390 BSDS LOCATION=locname field and is also provided in the DSNL004I message (LOCATION=location) when the DDF is started. - OS/400 The relational database name (RDBNAME)

db51

ApplicationRequester

The name of the application requester that forwards SQL requests to DRDA application servers. The application requester handles requests on behalf of an application program.

default

Parameter If you want to change some of the default values such as the name of an SQLCODE mapping file, the disconnection from the DRDA server, the interruption, the SYSPLEX support, and the date formatting support

default


10.4 Binding the DB2 Utilities

Before DB2 CLI or ODBC applications can access DB2, the DB2 CLI packages must be bound on the server. Although binding occurs automatically on the first connection if you have the required authority , we recommend that you bind the packages with each version of the client on each platform that accesses the server.

You must bind the database utilities (import, export, reorg, the command line processor, and DB2 CLI) to each database before they can be used with that database. In a network environment, if you are using multiple clients that run on different operating systems or are at different versions of DB2, you must bind the utilities once for each operating system and DB2 version combination.

Binding a utility creates a package, which is an object that includes all of the information that is needed to process specific SQL statements from a single source file.

The bind files are grouped together in different .lst files in the bind directory under the installation directory.

You can use the client configuration assistant or, on all operating systems, the command line processor. To bind the utilities to DEMO, we used the following commands in the bind directory in the CAE install path (c:\sqllib\bnd), with the command line processor:

• We connected to database DEMO:

connect to demo user db2admin using db2admin

• We bound the utilities and the CLI:

bind @db2ubind.lst messages bind.msg grant publicbind @db2cli.lst messages clibind.msg grant public

bind.msg and clibind.msg are the output message files, and EXECUTE and BIND privileges are granted to public.

• We reset the connection to the database:

connect reset

To bind the utilities to DB51T, we used the following commands:

connect to db51t user db2admin using db2adminbind @ddcsmvs.lst blocking all grant public

Installation 89

ddcsmvs.lst contains the list of the bind files that must be bound to the DB2 for OS/390. Replace ddcsmvs.lst by ddcs400.lst if your DRDA application server is on OS/400.

Here is an example of the message you get when you try to access data before you have bound the DB2 utilities:

SQL0805N Package "NULLID.SQLC2B3" was not found. SQLSATE=51002

10.5 Domino Settings

You may have to modify the Lotus Notes initialization file (notes.ini) to support the tools.

HTTP ServerTo load the Domino HTTP Web server task automatically, add the following line:

ServerTask=HTTP

When you restart the server, it loads the HTTP Web server task. The following line appears on the server console:

01/01/98 11:23:36 AM HTTP Web Server started

JavaUserClassesNotes needs to be able to find any classes of a server agent or servlet, not just the agent or servlet itself. The act of compiling the agent does not pull in the outside packages; they are just referenced by the class. There is no concept of static linking in Java because every class is dynamically linked in at run time. When the JVM in Notes loads the agent class, it also resolves and tries to load other classes that the agent class uses. If it cannot find a class that it needs, you get the ClassNotFoundException. The JVM in Notes looks for classes in three places:

• JavaUserClasses

If you have a JavaUserClasses setting in notes.ini, this list is searched for any needed classes. This list is similar in format to the more familiar CLASSPATH environment variable. It can contain directories, jar files, and/or zip files.

• Notes and Java core classes

The various Notes and Java core class archives are searched next, such as Notes.jar, icsclass.jar, rt.jar, and i18n.jar.

• Attached with the agent


These are any classes, resources, or whatever else you decided to include when you defined the agent. The JVM runs through the list of attachments and looks for the needed class. If any of the attachments are jar or zip files, they are searched internally for the required class or resource.

If after looking in these three places the JVM cannot find the class or resource, you get an appropriate error message.

In Java applications the CLASSPATH environment variable is set properly to find the package. To minimize outside interference and sources of strange errors, Domino does not use CLASSPATH; rather it constructs its own internal class path, using the JavaUserClasses setting and its own core classes.

Enabling Java Servlet SupportIn Domino, support for servlets is disabled by default. To enable servlet support, add the following line:

DominoEnableJavaServlets=1

When you restart the server, it loads the JVM and locates the ServletManager Java class, adding the icsclass.jar file to the CLASSPATH environment variable automatically. As the servlet support is loading, the following three lines appear on the server console:

01/01/98 11:23:36 AM HTTP Web Server started01/01/98 11:23:38 AM JVM: Java Virtual Machine initialized01/01/98 11:23:38 AM Java Servlet Manager initialized

Installing ServletsTo install a servlet, whether one you wrote or a pre-built one, you create a Servlets subdirectory in the Domino server data directory and copy the compiled servlets into that subdirectory. Add a setting for JavaUserClasses to include a path for the subdirectory. For example:

JavaUserClasses=c:\lotus\notes\data\domino\servlets

DECS ProcessThe DECS installation program adds the following line:

EXTMGR_ADDINS=ndescext.dll

It also declares the DECS task as a server task:

ServerTask=DECS

When you restart the server, it loads the DECS addins task. The following line appears on the server console:

01/01/98 11:23:36 AM DECS Server started

Installation 91

NotesPump Realtime Notes Activity ProcessWhen using NotesPump Realtime Notes activities, add the following line:

EXTMGR_ADDINS=lnpext.dll

Agent SchedulingWhen using scheduled agents, add the following lines:

AMgr_DocUpdateAgentMinInterval=1AMgr_DocUpdateEventDelay=1

The agent manager responds to events as soon as possible.

You may have to enable locally scheduled agents in the UserPreferences section under File/Tools.

10.6 ODBC Registration

The DB2 CLI run-time environment and the ODBC driver are included with DB2 CAE. This support enables applications developed with ODBC and DB2 CLI APIs to work with any DB2 server.

You need first to verify that the Microsoft ODBC driver manager and the DB2 CLI/ODBC driver are installed. In the Microsoft ODBC Administrator from the icon in the Control Panel, check that IBM DB2 ODBC Driver is shown in the list of drivers.

You need to register the DB2 database with the ODBC driver manager as a data source. The ODBC driver manager does not read the DB2 catalog information; instead it references its own list of data sources. We registered DEMO as a system data source to make the data source available to all users of the system. Three methods are available:

• Using the client configuration assistant

Select the DB2 database alias (DEMO), click on the Properties button, and select the Register this database for ODBC check box.

• Using the Microsoft 32bit ODBC Administration tool

Select the System DSN tab, click on the Add button, double-click on the IBM DB2 ODBC Driver in the list, select the DB2 database alias (DEMO) to add, and click on OK.

• Using the command line processor

CATALOG system ODBC DATA SOURCE demo


Various CLI/ODBC configuration keywords can be set to modify the behavior of the DB2 CLI/ODBC and the applications using it.

If you followed the above steps to install ODBC support, and added DB2 databases as ODBC data sources, your ODBC application is now be able to access the DB2 databases.

10.7 LS:DO

The LS:DO is included with all Notes 4.5 or + release clients and servers, on the following platforms:

• Windows 3.1

• Windows 95

• Windows NT

• OS/2

• Solaris SPARC

• Solaris x86

• HP-UX

• AIX

• AS/400

LS:DO release 4.5a for System/390 is available for download on the IBM S/390 Web site.

10.8 DB2LSX

DB2LSX Release 1.2.0 is available for Windows NT and Windows 95 platforms. DB2LSX Release 1.1.0 is available for OS/2. You can download it from the Lotus Enterprise Integration Web site.

To use DB2LSX Release 1.2.0, you must have Lotus Notes Release 4.6.1 and DB2 CAE installed on your machine.

To set up a DB2LSX environment, follow these steps:

1. Download the DB2LSX file from the Web into a directory of your choice.

2. Unzip the file.

3. Run SETUP.EXE.

Installation 93

The download package includes an online help database (db2dahlp.nsf) and a sample database (db2samp.nsf) showing how to use methods in the DB2 Data Access classes to read and write large data objects in DB2 databases.

10.9 Java

In this section we explain the installation and settings needed to support Java and JDBC.

10.9.1 Java Development KitIf you want to develop Java applets or applications, you need to install JDK Version 1.1 or higher on the server. JDK Version 1.1 is available on the Sun Web site for Windows platforms, and on the IBM Java Web site for IBM platforms (AIX, OS/2, OS/390 (UNIX Services), OS/400, and VM/ESA).

10.9.2 Java Servlet Development Kit The Java Servlet Development Kit (JSDK) contains a simple servlet engine for developing and testing servlets, the javax.servlet package sources, and API documentation. JSDK Version 2.0 is available on the Sun Web site for Windows platforms.

10.9.3 JDBCTo create DB2 JDBC applets or agents for use in a Domino application, you have to install DB2 (server or client) on the same machine as your Domino server.

DB2 UDB Version 5 includes support for the JDBC API, as distributed with JDK 1.1. JDBC is available as a no-charge feature to all DB2 for OS/390 Version 5 customers. The AS/400 Toolbox for Java, a library of Java classes that give Java programs easy access to AS/400 data and resources, includes a JDBC driver to access DB2/400 databases.

With DB2 UDB Version 5, you can use DB2 JDBC support to run the following types of Java programs:

• Java applications, which rely on DB2 CAE to connect to DB2

• Java applets, which do not require any other DB2 component code on the client.

Java can also be used on the server to write user-defined functions, stored procedures, and table functions.


DB2 Java Application SupportTo test a Java application, you can just start it from the desktop or command line, like any other application. The DB2 JDBC driver handles the JDBC API calls from your application and uses DB2 CAE to communicate the requests to the server and receive the results.

DB2 Java Applet SupportBecause Java applets are delivered over the Web, you treat them a bit differently from Java applications.

To run your applet, you need a Java-enabled Web browser on the client machine. When you load your HTML page, the applet tag downloads the Java applet to your machine, which then downloads the Java class files, including the COM.ibm.db2.java.sql and COM.ibm.db2.jdbc.net classes and DB2's JDBC driver. When your applet calls the JDBC API to connect to DB2, the JDBC driver establishes separate communications with the DB2 database through the JDBC applet server residing on the DB2 server.

To run your applets, follow these steps:

1. Start the DB2 JDBC applet server on your Web server by entering:

db2jstrt portno

where portno is the number of the unused TCP/IP port that you specified in the applet file.

2. On your client system, start your Web browser and load the HTML file that embeds your applet.

10.9.4 Environment VariablesTo run Java programs, the system must be able to access the required Java class files. Table 18 on page 95 gives the different values that must be added to the CLASSPATH environment variable.

Table 18. CLASSPATH Environment Variable Values

Directory Java Package

. (dot) Local package and class files

c:\notes\notes.jar Lotus Notes

c:\jdk1.1.3\lib\classes.zip JDK 1.1.3

c:\jsdk2.0\lib\jsdk.jar Java servlet

c:\sqllibjava\db2java.zip DB2

Installation 95

The PATH variable includes the sqllib\bin directory as it is set up during the DB2 installation.

10.9.5 Java Servlet and Domino ServerTo use a Java servlet with Domino, you have to:

1. Enable Java servlet support (refer to Chapter 10.5, “Domino Settings” on page 90).

2. Install the servlet (refer to Chapter 10.5, “Domino Settings” on page 90)

3. Register the servlet.

4. Access the servlet through the Web.

Registering the ServletTo access a servlet from the Web, it must be registered in a Domino servlet configuration file, servlet.cnf, which you create in the Domino data directory. When the server starts up, it checks this configuration file to see whether there are any servlets to load. In the servlet configuration file, you must specify each servlet by name. Optionally, you can specify initialization parameters, a servlet class for URL mapping, and instructions for loading the servlet at startup time.

The following example registers the ReportServletNative servlet with the initialization parameters that load the servlet at startup and map it to a URL:

# Register a servletServlet ReportServletNative{url=jdbc:db2://127.0.0.1:2200/demo userid=db2adminpassword=passwordGO_LOAD_AT_STARTUP=Yes}#Map the servlet to a specific URLService ReportServletNative /servlet/ReportServletNative

Accessing a Servlet from the WebOnce the servlet is registered and mapped to a specific URL, you can access the servlet with that URL, using full URL syntax. For example, entering http://myserver//servlet/ReportServletNative runs the ReportServletNative servlet registered in the previous step.


10.10 LC LSX and DECS

We used the beta versions of LC LSX and DECS, which were available on the Lotus Enterprise Integration Web site. LC LSX is installed automatically when installing DECS.

System RequirementsYou need at least 10 MB of disk space to install DECS. DECS require Domino Release 4.63 running on the following platforms:

• Windows NT 4.0

• Windows 95

• OS/2

• AIX

• Solaris Intel Edition

• Solaris SPARC

• Windows NT Alpha

• HP-UX

InstallationBefore using DECS, you need to ensure you have established connectivity from the Domino server to the external data source, in our case DB2. DECS provides a program (nlctest for Windows NT and 95) to test connectivity from the Domino server to external data sources.

Using the beta version on Windows NT, we ran the DECS installation program, ndecsins.

When you start Domino Release 4.63, DECS and the LC LSX are part of the Domino installation process. The installation program copies all of the DECS program files into the Domino program directory and makes the appropriate modifications to the notes.ini.

After DECS is installed, you have to restart the Domino server. You can see the DECS server task, DECS Server, initialize when the Domino server is started.

10.11 NotesPump

We used NotesPump Version 2.5 for Windows NT, available on the Lotus Enterprise Integration Web site.

Installation 97

System RequirementsNotesPump is available on the following platforms:

• Windows NT

• OS/2

• HP-UX

• AIX

• Solaris SPARC

• Solaris Intel Edition

• OS/400

It is IBM’s intent to provide NotesPump on S/390 to facilitate the interchange of business data between Domino applications and CICS, IMS, and DB2 applications.

The NotesPump Administrator database requires Lotus Notes Release 4.5 or later. The NotesPump server requires Lotus Notes Release 4.11a or later (for HP-UX and Solaris, excluding Notes Release 4.5 and 4.5A).

NotesPump is installed as a separate service on an existing Domino server or Lotus Notes client, for the purpose of providing activities such as data transfer services to applications and users.

InstallationWhen installing NotesPump, you have to decide whether you want to install it on a separate machine or on the same machine as the Domino server. The decision is influenced by the load of both systems, the network configuration, and the use of the Realtime Notes activity. If you plan to use this activity, then NotesPump has to be installed on the same machine as the Domino server, and you have to edit the notes.ini to add the real time activity task:

EXTMGR_ADDINS=lnpext.dll

NotesPump installation creates four databases:

• NotesPump Administrator database

• NotesPump Script Vault database

• NotesPump Log database

• NotesPump Documentation database


Once NotesPump has been installed, you can start by either selecting the NotesPump icon or running the NotesPump program, lnpump, at the NotesPump Server console:

c:\npump>lnpump

On the NotesPump machine you need to have a connection to the DB2 database through either DB2 CAE or DB2 Connect. You can test the connection between NotesPump and DB2 with the db2test command:

C:\npump>db2test

DB2 Connection Verification

Copyright 1995 Lotus Development Corporation--------------------------------------------This utility will verify connectivity from this machine to thespecified DB2 server.At the prompts, enter a valid DB2 database, username, and password

Database: demoUsername: db2adminPassword: db2admin

Attempting to connect to DB2 demo as db2adminSuccessfully ConnectedSuccessfully Disconnected

Connectivity to DB2 Verified.

You can test the connection between NotesPump and the Domino server with the nottest command:

D:\npump>nottest

Lotus Notes Server Connection Verification

Copyright 1996 Lotus Development Corporation--------------------------------------------This utility will verify connectivity from this machine to thespecified Lotus Notes Server.At the prompt, enter the Notes Server name you wish to connect to.Initializing...Lotus Notes Server: china/asiaAttempting connection...Connectivity to Server china/asia Verified.

Installation 99

Chapter 11. Programming the Tool

In this chapter we describe how to use each tool. All samples are based on the DB2 SAMPLE database shipped with the DB2 UDB server.

11.1 Millennium Cafe Java Sales Tools Plus Application Structure

In this section we describe the structure of the Millennium Cafe Java Sales Tools Plus application. (Refer to Chapter 10.1, “Millennium Cafe Sales Tools Plus Application” on page 83 for instructions downloading the application.)

The "About Database" DocumentThe "About Database" document is used as the main menu for this application. As shown in Figure 15, you select the different sections of the application through a hotspot.

Figure 15. "About Database" Document

When you select one option in the Query & Update Employee list, the hotspot triggers a command to display the Sales Representative Information Request form such as:


@Command([Compose];"Request FunctionName "

When you select one option in the Sales Reporting list, the hostspot tiggers a command to display the Custom Sales Report form such as:

@Command([Compose];"Report FunctionName "

Table 19 on page 102 shows the name of the functions for each tool used.

Table 19. Function Names

Tool Function Name

LS:DO Connection using a DBASE ODBC driver DBASE

LS:DO connection using a DB2 ODBC driver ODBCDB2

DB2LSX connection using a DB2 CLI driver DB2LSX

DB2LSX connection using a DB2 CLI driver includingBLOB and stored procedure support

DB2LSXBLOB

LC LSX connection using a DB2 CLI driver DB2LDC

Java server agent using the ODBC bridge JavaBridge

Java server agent using the DB2 CLI driver JavaNative

Java servlet using the ODBC bridge JavaServletBridge

Java servlet using the DB2 CLI driver JavaServletNative

Programmatic access with native SQL DLL

Java applet using the DB2 CLI driver Applet

DECS DECS


11.1.1 Query and Update Employee OptionsFigure 16 show the Sales Representative Information Request form.

Figure 16. Sales Representative Information Request Form

In the request form, you select an employee from a list of IDs generated using an @DbFunction. In the request form, the $$Return hidden field then triggers the display of the Sales Representative Information Report form (see Figure 17 on page 104), using the following formulas:

dbname := "/" + @Subset(@DbName; -1 );"[" + dbname + "/RepInfo FunctionName ?OpenForm&" + HR_ID + "]"

When loading the Sales Representative Information Report form, the WebQueryOpen event triggers the LoadEmployeeFunctionName agent

Programming the Tool 103

Figure 17. Sales Representative Information Report Form

When you click on the Update button, a WebQuerySave event triggers an @Command that starts an agent:

@Command([ToolsRunMacro]; "UpdateEmployee FunctionName ")

This agent reads the information from the form and updates the employee information in the DB2 database. It then redisplays the Sales Representative Information Report form.


11.1.2 Sales Reporting OptionsFigure 18 on page 105 shows the Custom Sales Report form.

Figure 18. Custom Sales Report Form

In this request form, you enter the name of a customer and/or an employee ID and specify some options for the search. The SQL hidden field generates the SQL statement according to the values and options entered.

When you click on the Search button, a WebQuerySave event triggers a @Command that starts an agent

@Command([ToolsRunMacro];"Report FunctionName ").

The agent then uses the SQL statement to access the DB2 tables, creates a result set, and uses the Print function to generate an HTML page (see Figure 19 on page 106).


Figure 19. Query Results Form

11.2 LotusScript Programs

In this section we explain how to create LotusScript programs that use LotusScript extensions and include some tips and tricks on how to program.

11.2.1 StructureA LotusScript program is divided into multiple sections:

• Options

In this section, you define the LSX and script library routines that are used by the program. The uselsx statement defines either:

• The name of the library containing the extension:

UseLSX "c:\db2lsx\nlsxdb2.dll"

or

• The name that is associated with the LSX in the LSX class registry

UseLSX "*LSXDB2"

The use statement defines the script libraries containing subroutines and functions.

• Globals


In this section you define all of the global variables. Once initiated, the global variables keep their values in all called script libraries.

• Initialize

The code in this section is executed when the program is called, for example, by Domino or Lotus Notes in case of a scheduled agent.

• Terminate

The code in this section is executed when an agent is terminated. In the Terminate section you should do housekeeping, such as closing all result sets and open connections.

• Private functions and subroutines

All of the private functions and subroutines can be added to a scripting activity.

LotusScript type-checks all references to the new classes in the script program against the registered class definitions. Furthermore, when, in the programming pane, you check the Show browser option and select the Notes:classes option in the combo box, the registered LSX classes are displayed, including their properties and methods.

11.2.2 InvocationIf you write a Domino application that needs to support Lotus Notes clients and Web users, you may find it useful to use a script library to develop the application functions. Lotus Notes users and Web users do not trigger the application in the same way. You detect a QueryOpen event of a form displayed on a Lotus Notes client when you detect a WebQueryOpen event of a form displayed on the Web. However, the same script library code can be called from both events. Therefore, you only have to write and maintain the code in one place. Figure 20 on page 108 and Figure 21 on page 108 show how the scripts are accessed.


Figure 20. Lotus Notes Client Event

Figure 21. Web Browser Event

Database

Web Query Open

Query Open Agent

ScriptLibrary

DB2

Lotus Notes

Database

Web Query Open

Query Open Agent

ScriptLibrary

DB2

Domino


11.3 @DbFunctions

Table 20 summarizes the @DbFunctions

Table 20. @DbFunctions

11.3.1 @DbColumn@DbColumn generates a keyword list from either a Notes database or an external ODBC-compliant database.

When the application accesses data outside the current document and database, @DbColumn returns all of the values in a specified column of a view in a Notes database.

When the application accesses an external database through ODBC, @DbColumn returns all of the values in one column of a table, or all distinct values.

@DbColumn can only retrieve data. It cannot add, delete, or modify data or perform other operations.

In Figure 22 on page 110, an @DbColumn gets the EMPNO column of the Employee table.

@DbFunction Description SQL Equivalent

@DbColumn Generates a keyword list. Returns a specified column from all rows in the specified table

SELECT DISTINCT column FROM table

@DbLookup Performs a lookup. Returns a specified column value in the row that matches the specified condition

SELECT column FROM table WHERE condition

@DbCommand Triggers stored procedures and queries in DB2

Any SQL statement


Figure 22. @DbColumn

The format of the @DbColumn is:

@DbClumn("ODBC":"NoCache" ; "ds" ; "userID" ; "password" ; "table" ;"column" ; "Distinct":"sort" )

where:

ODBC indicates that you are accessing an ODBC data source

NoCache ensures that Notes retrieves the latest information on every lookup. Omit NoCache if you want the results of the lookup to be cached, that is, stored for reuse in the next lookup.

ds the name of the external data source being accessed.

userID the user ID needed to connect to the data source. You can specify up to two IDs, depending on the DBMS being accessed.

password the password required by the user ID

table the name of the database table being accessed

column the name of the column from which data is being retrieved

Distinct keyword; removes duplicate values from the list before returning data

sort Specify Ascending to sort the list in ascending order, Descending to sort the list in descending order before it is returned.

11.3.2 @DbLookupWhen the application accesses data outside the current document and database, @DbLookup looks up a specified value in the first sorted column of a view in a Notes database. For each document that matches the search values, @DbLookup returns the value of a specified field.


When the application accesses an external database through ODBC, @DbLookup returns selected values in one column of a table, by matching keys.

@DbLookup can only retrieve data. It cannot add, delete, or modify data or perform other operations

In Figure 23, a @DbLookup function gets the last name from the row of the Employee table where the employee number is 000100.

Figure 23. @DbLookup

The format of the @DbLookup is:

@DbLookup("ODBC":"NoCache" ; "ds" ; "userID" ; "password" ; "table","column" ; "key_column" ; "key_value" ; "Distinct":"sort" )

where:



ds the name of the external data source being accessed



table the name of the database table being accessed

column the name of the column from which data is being retrieved


key_column the name of the column used for key matching

key_value the value to be looked up in key_column

Distinct keyword; removes duplicate values from the list before returning data

sort Specify Ascending to sort the list in ascending order, Descending to sort the list in descending order before it is returned.

11.3.3 @DbCommand@DbCommand works only with ODBC data sources.

When the application accesses an external database through ODBC, @DbCommand passes a command to the external DBMS and returns the results.

@DbCommand can retrieve data or send other SQL statements that can change the data.

In Figure 24, an @DbCommand gets the last name of all employees belonging to department D11.

Figure 24. @DbCommand

The format of the @DbCommand is:

@DbCommand("ODBC":"NoCache" ; "ds" ; "userID" ; "password" ; "string" )

where:




ds the name of the external data source being accessed



string an SQL statement, command statement, or name of a procedure to be executed

11.3.4 IDs and PasswordsDB2 requires one ID. If you replace it with a null string (""), the user will be prompted for it by DB2 CAE where DB2 CAE is installed. Therefore, for Web users, you have to provide the function with a user ID and password; otherwise, the prompt will be generated on the server. The user ID and password must be included in formulas that run automatically, such as an agent, because they do not prompt for information.

11.4 LS:DO

LS:DO consists of three classes (see Figure 25 on page 114):

• ODBCConnection, which represents the ODBC data access features for connecting to a data source

• ODBCQuery, which represents the ODBC data access features for defining SQL statements

• ODBCResultSet, which represents the ODBC data access features for performing operations on a result set


Figure 25. LS:DO Classes

To retrieve data from an OBDC data source, LotusScript must:

1. Create an ODBCConnection object and use it to connect to a database.

2. Create an ODBCQuery object, associate it with the connection object, and specify a query in the form of an SQL statement.

3. Create an ODBCResultSet object, associate it with the query object, execute the query, and work with the result set rows to get and set field values.

11.4.1 A Step-by-Step ExampleTo use LS:DO to access DB2 data, follow these steps:

1. Initialize LS:DO

2. Connect to the DB2 database

3. Query the table

4. Examine the result set

5. Add, change, or delete rows in the result set

6. Disconnect from the DB2 database

In this section we describe how we created the LoadEmployeeODBCDB2 agent (see Appendix A.1, “LoadEmployeeODBCDB2 Agent” on page 163).

Initialize LS:DOWe specified the Uselsx statement in the (Options) event of the (Globals) object of our Notes application. This statement makes the LS:DO classes


available to the program. If the LS:DO is registered on your machine, you can code the statement like this:

UseLSX "*LSXODBC"

To declare the LS:DO classes, we added the following code in the Event (Declarations): of the (Globals) variables of the agent:

Dim Con As ODBCConnectionDim Qry As ODBCQueryDim Result As ODBCResultSet

To create the new objects' instances, we added the following code in the Initialize event of the agent:

Set Con = New ODBCConnectionSet Qry = New ODBCQuerySet Res = New ODBCResultSet

Connect to the DB2 DatabaseYou now have to establish a connection to the data source (ds). Optionally, you can specify the ID (uid) and the password (pw) of the user referenced in DB2. We used the ConnectTo method. The result of the connection (successful or not) is returned as a boolean value (status):

status = con.ConnectTo(ds,uid, pw)

Query the TableOnce the agent is connected to DB2, we can query it and get some results.

To get data from the data source, we used the ODBCQuery and ODBCResultSet classes, in the following steps:

1. Associate the query object with the connection object:

Set Qry.Connection = Con

2. Associate the query object with the result set object:

Set Res.Query = Qry

3. Specify the SQL statement that defines the data we want:

Qry.SQL = "Select * from CAFE.EMPLOYEE"

4. Execute the SQL query, using the Execute method:

Res.Execute

5. Check the execution, using the IsResultSetAvailable method of ODBCResultSet. This method returns False if an error occurs or the result set does not contain any data.


An SQL query can contain parameters that will be replaced by values at run time. To query with a parameter, follow these steps:

1. Specify the SQL statement that defines the data you want. The following query contains one parameter (EMPNO):

Qry.SQL = "Select * from CAFE.EMPLOYEE where EMPNO =?hr_id?"

2. You must give the parameter a value before executing the query. The SetParameter method assigns a value, given the name or the position of the parameter and the value:

Call Res.SetParameter(1,hr_id)

Examine the Result SetAfter the query is executed, the result set contains fields (columns) and rows depending on what the SELECT query fetches from the data source. The ODBCResultSet class provides properties and methods to examine the result set.

• Columns

The columns of a result set are identified by number and name. Column numbers are integers starting with 1 and ending with the return value of the NumColumns method.

You can use the following methods to retrieve column information: NumColumns, FieldID, FieldInfo, FieldName, FieldSize.

• Rows

The rows of a result set are identified by number. Row numbers are integers starting with 1 and ending with the return value of the NumRows method. (NumRows does not return an accurate value until the entire result set is fetched.)

To navigate through the rows, use the FirstRow, NextRow, PrevRow, LastRow, and LocateRow methods. The CurrentRow property returns the number of the row that is in position for processing.

The IsEndOfData and IsBeginOfData methods return True on the last and first rows, respectively.

• Values

We used the GetValue method to copy the value of the column of the current row—in our sample, the result set contains only one row—into the document field. The column can be specified by name:

doc.LastName= Res.GetValue("LASTNAME")

or number:


doc.LastName= Res.GetValue(3)

Use the IsValueNull method to check for null values

Add, Change, or Delete Rows Updates include changing, deleting, and adding rows within a table, and creating and deleting tables. To prevent updating, set the ReadOnly property of the ODBCResultSet object to True.

The UpdateEmployeeODBCDB2 agent is triggered when the user clicks on the Update button on the Sales Representative Information Request form (see Appendix A.2, “UpdateEmployeeODBCDB2 Agent” on page 165).

• Changing values in a row

To change the values in the current row, call the SetValue method one or more times to specify the new value for each field that is changing, then call the UpdateRow method. Specify the column by number or name:

status = Res.SetValue(1, column1Value)status = Res.SetValue(2, column2Value)...status = Res.UpdateRow

• Deleting rows

To delete the current row, call the DeleteRow method, then call the UpdateRow method:

status = Res.DeleteRow(tableName)status = Res.UpdateRow

• Adding rows

To add a row, call the AddRow method , call the SetValue method one or more times to specify the value for each field, and then call the UpdateRow method:

status = Res.AddRowstatus = Res.SetValue(1, column1Value)status = Res.SetValue(2, column2Value)...status = Res.UpdateRow

• Update status

The following methods provide update status:

• IsValueAltered tells whether SetValue altered a column value.

• GetRowStatus tells whether the result set row has changed since the result set was created.


• HasRowChanged tells whether values in the database have changed since the result set was created; that is, whether the database table value differs from the result set value as fetched.

Disconnect from the DB2 DatabaseTo clean up a connection to DB2:

• Free the result set:

If Not Res Is Nothing Then Res.Close(DB_CLOSE)

• Close the ODBC database connection:

If Not Con Is Nothing Then Con.Disconnect

• Delete the LS:DO objects:

Delete ConDelete QryDelete Res

Error HandlingODBCConnection, ODBCQuery, and ODBCResultSet contain the following methods:

• GetError returns the integer error number for the last operation performed by an object of one of the above classes.

• GetErrorMessage returns the error text for the last operation performed by an object of one of the above classes.

• GetExtendedErrorMessage returns extended error text for the last operation performed by an object of one of the above classes. If the error is originally reported by the data source, the extended error text contains the data source error message.

These methods are similar for the three classes.

If an operation is successful, the return number is DBstsSUCCESS. Any other number indicates an error.

You can test operations in general with an On Error statement. If an On Error action with no error number is in effect, any operation that returns an error number other than DBstsSUCCESS invokes the On Error action. Your error code should test GetError for all objects that might cause the error. The following code shows the technique for trapping any database errors and exiting:

On Error Goto errorHandler

con.ConnectTo("DEMO")


qry.SQL = "SELECT * FROM CAFE.EMPLOYEE"result.Execute

errorhandler:If con.GetError <> DBstsSUCCESS Then Messagebox con.GetExtendedErrorMessage,, _ con.GetError & " " & con.GetErrorMessageEnd If

If qry.GetError <> DBstsSUCCESS Then Messagebox qry.GetExtendedErrorMessage,, _ qry.GetError & " " & qry.GetErrorMessageEnd IfIf result.GetError <> DBstsSUCCESS Then Messagebox result.GetExtendedErrorMessage,, _ result.GetError & " " & result.GetErrorMessageEnd IfExit Sub

Handling EventsEvents precede and follow many methods, as listed in the Online Help database. They have names such as BeforeConnectTo, AfterConnectTo, BeforeNextRow, and AfterNextRow. If you write a code segment and make it a condition of the event, using the On Event statement, the code segment is called when the event occurs. The code segment is known as an event handler, and it is said to be bound to the event. The On Event statement must state the name of the event and the name of the ODBCConnection, ODBCQuery, or ODBCResultSet object that activates the event.

LS:DO Error CodeThe current release returns error numbers greater than 500 as LS:DO errors, and LotusScript returns error numbers less than 500.

11.5 DB2LSX

DB2LSX consists of three classes.

• DB2Connection, which represents the DB2 data access features for connecting to a data source

• DB2Query, which represents the DB2 data access features for defining SQL statements.

• DB2ResultSet, which represents the DB2 data access features for performing operations on a result set

Figure 26 shows the DB2LSX classes and their relationships.

Figure 26. DB2LSX Access Classes

To retrieve data from DB2, LotusScript must:

1. Create a DB2Connection object and use it to connect to a database

2. Create a DB2Query object, associate it with the connection object, and specify a query in the form of an SQL statement

3. Create a DB2ResultSet object, associate it with the query object, execute the query, and work with the result set rows to get and set field values.

11.5.1 A Step-by-Step ExampleTo use DB2LSX to access DB2 data, you can use the same steps as LS:DO. In addition you can also use DB2LSX to access and manipulate large objects such as BLOBs, CLOBs, and DBCLOBs.

In this section we describe how we created the LoadEmployeeDB2BLOB agent (see Appendix B.1, “LoadEmployeeDB2BLOB Agent” on page 169).

Initialize DB2LSXAs DB2LSX has be registered on the machine during the installation, we specified the Uselsx statement in the (Options) event of the (Globals) variables of the agent:

UseLSX "*LSXDB2"

To declare the DB2LSX access classes, we added the following code in the Event: (Declarations) of the (Globals) variables of the agent:


Dim Con As DB2ConnectionDim Qry As DB2QueryDim Res As DB2ResultSet

To create the new object's instances, we added the following code in the Initialize event of the agent:

Set Con = New DB2ConnectionSet Qry = New DB2QuerySet Res = New DB2ResultSet

Connect to the DB2 DatabaseWe now have to establish a connection to the database, using the ConnectTo method. We had to specify the user ID and password known on the DB2 system. The result of the connection (successful or not) is returned as a boolean value:

Dim status As integerstatus = con.ConnectTo("DEMO";"db2admin";"db2admin")

Status, the return value, is a boolean and returns True if the connection is successful and False if the connection fails.

If the connection is successful, you access the database. If the connection fails, you must do some alternate processing:

If status Then' insert code to perform if connection has been made

Else' insert code to perform if connection failed

End If

Query the TableOnce the agent is connected to the database, we can query it and get some results.

To get data from the database, we used the DB2Query and DB2ResultSet classes in the following steps:

1. Associate the query object with the connection object:

Set Qry.Connection = Con

2. Associate the query object with the result set object:

Set result.Query = Qry

3. Set the SQL statement that defines the data we want:

Qry.SQL = "Select * from CAFE.EMPLOYEE where EMPNO = ’A00’"


4. Execute the query SQL, using the Execute method:

status = Res.Execute

5. Check the execution, using the IsResultSetAvailable method of DB2ResultSet. This method returns False if an error occurs or the result set does not contain any data.

Note: When you no longer need a result set, close it with the Close method of DB2ResultSet.

Examine the Result SetAfter executing the query, the result set contains fields (columns) and rows depending on what the SELECT query fetches from the table. The DB2ResultSet class provides the same properties and methods as the ODBCResultSet class to examine the result set (see “Examine the Result Set” on page 116).

Add, Change, or Delete RowsUpdates include changing, deleting, and adding rows within a table, and creating and deleting tables. To prevent updating, set the ReadOnly property of the DB2ResultSet object to True. The DB2ResultSet class provides the same properties and methods as the ODBCResultSet class to add, change, or delete rows in the result set (see “Add, Change, or Delete Rows” on page 117).

Add and Retrieve Large Object DataFour methods, specific to DB2LSX, are available to add and retrieve large object data:

• Adding large objects to DB2

• The AppendChunk method sets character values for DB2 columns containing large objects one chunk at a time, when the values are too long to store in a single LotusScript variable.

• The SetValueAsFile method sets binary values in a column.

• Retrieving large objects from DB2

• GetChunk gets character values for DB2 columns containing large objects (CLOBs, DBCLOBs) one chunk at a time, when the values are too long to store in a single Lotus Script variable.

• GetValueAsFile gets binary data (BLOB) into a LotusScript application without conversion to character format.


Add and Retrieve CLOBs and DBCLOBsTo change a column of CLOBs or DBCLOBs in the current row, call the AppendChunk method one or more times to construct the new value; then call the UpdateRow method. In the following sample, we are adding to a DB2 CLOB (DB2_CLOB) the large object contained in a document field (DOM_CLOB). The size of the chunk (chSize) is 500 bytes.

chSize = 500offset = 1Do While offset <= Len(doc.GetItemValue)(0))

Chunck= Mid$(doc.GetItemValue("Resume")(0), offset, chSize)status = Res.AppendChunk("RESUME", Chunck)offset = offset + chSize

Loop

AppendChunk fails if the current column has a value that is not a string. You can use the FieldSetExpectedDataType method to update binary data in the database with a character value, because the database will convert from character to binary. You must pass a character representation of your binary data as a chunk. LotusScript currently has no binary data type; therefore, to set a binary value directly, without conversion to character and back, put it in a file and use the SetValueAsFile method.

To retrieve the CLOB from DB2, use the GetChunk method. This method returns the specified number of characters starting at the specified position within the column's value:

chSize = 500offset = 1Do

Chunck= Res.getChunk("RESUME", offset , chSize) doc.Resume = doc.Resume(0) & Chunckoffset = offset + chSize

Loop Until Len(Chunck) < chSize

If the offset exceeds the size of the value, an error is raised. If fewer than length number of characters are available, the number actually available is returned. You can get the number actually returned by using the Lotus Script Len function.

Add and Retrieve BLOBsAs LotusScript does not support the binary data type, you need to add and retrieve binary data, using an intermediate file that contains the data. To add a row that contains BLOBs, create a workspace to build the row, using AddRow, and, using SetValueAsFile, set a column value that is of binary data type to the file name of the binary large object:

photo = uidoc.fieldgettext("PhotoFile")Call Res.SetValueAsFile("body",photo) Gformat =Right$(PhotoFile,3)Call Res.SetValue("BODYFORMAT", Gformat)

The SetValueAsFile method sets the string or binary value of a column to the contents of a file. To retrieve BLOBs from DB2, use the GetValueAsFile method. This method retrieves the value of a column into a file. The value currently stored for the column must be of type DB_CHAR, DB_DBCHAR, or DB_BINARY

The SetValueAsFile and GetValueAsFile methods are most useful for columns containing a large amount of data such as BLOBs, CLOBs, and DBCLOBs. However, they can also be used for columns of other data types containing binary or string data. This is the only way to set binary data from your LotusScript application without first converting it to character data, because LotusScript currently has no binary data type that can be passed through the SetValue or AppendChunk methods.

You can specify the name of a file in which you want the value to be stored by providing the optional input parameter. If you omit this parameter, the method generates a file name. In either case, the method provides the name of the file used as its return value. The name includes the full path of the file.

FileName = "Pic_" & HR_ID & ".gif"PicFile = Res.GetValueAsFile("PICTURE", "data/domino/html/" + FileName)doc.Photo = "[<img src=/" + FileName + ">]"

Displaying Binary Objects on the WebThis script fetches the image of a product in real time out of the DB2 database. The image is stored in a DB2 BLOB. Because there is no binary data type in LotusScript, we used the GetValueAsFile method to save the BLOB value— a .gif file—in the HTML directory of the Domino server. The name of the file is created using the ID of the employee, and its extension is gif. So a browser can have immediate access to the file, without the need to store it in a Lotus Notes document first. In the document, the script generates a URL pointing to the file in the HTML directory.

For example, we saved the photo of employee 000130 in the following file:

c:\notes\data\domino\html\ProdPic\pic000130.gif.

When we generated the form to display the employee information on the Web, we added a field, only to be read by a browser, that contains the following HTML tag for showing the image:

[<IMG src=’/Pic000130.gif’>].

The brackets are needed for Domino to interpret the text as HTML.

DB2LSX Error HandlingDB2Connection, DB2Query, and DB2ResultSet contain the same methods as LS:DO to handle errors (see “Error Handling” on page 118):

• GetError

• GetErrorMessage

• GetExtendedErrorMessage

Commit the UpdatesIn DB2LSX, additions and changes are not final in the database until you use the Transact method on the DB2Connection object.

status = Con.Transact(param)

with param, which must be one of the following:

• DB_COMMIT to commit all the changes

• DB_ROLLBACK to roll back all the changes

The result of the connection (successful or not) is returned as a boolean value.

11.6 Lotus Domino Connector LSX

LCs provide native access to a wide variety of DBMS products including DB2, ODBC, the platform file system, ERP systems, and OLTPs. The LC LSX extends these connectors to LotusScript.

The LC provides external data and system access to the Domino LotusScript environment. The LC LSX consists of the following classes:

• LCSession

The LCSession class provides error information useful in error handlers. It also provides for query and lookup of available Lotus Connectors.

• LCConnection

The LCConnection class represents an instance of a Lotus Connector. This class provides query and data access to the external system. Multiple connections may be allocated to a single Connector.

• LCFieldlist


The LCFieldlist class is the primary class for manipulating data through a connection. It binds a group of fields together with names and an implied order.

Fieldlists are used primarily for a number of connection operations; result sets and selection criteria, as well as reading and writing data.

• LCField

LCField is the storage class that contains one or more data values. The data type of a field is for all values contained within and may be any of the four advanced data type classes (LCStream, LCNumeric, LCCurrency, and LCDatetime), as well as long integer and double precision floating point, and, in some advanced usage, fieldlist or connection.

11.6.1 A Step-By-Step ExampleTo use LC LSX to access DB2 data, follow these steps:

1. Initialize LC LSX

2. Connect to the DB2 database

3. Query the table

4. Examine the result set

5. Add, change, or delete rows in the result set

6. Disconnect from the DB2 database

In this section, we describe how we created the LoadEmployeeDB2LDC agent (see Appendix C.1, “LoadEmployeeDB2LDC Agent” on page 173).

Initialize LC LSXAs LSX LC has be registered on the machine during the installation, we specified the Uselsx statement in the (Options) event of the (Globals) variables of the agent:

UseLSX "*LSXLC"

We defined the error handler and the objects needed during the process:

On Error Goto HandlerDim src As LCConnection Dim KeyLst As New LCFieldList Dim field As LCField Dim FieldOut As New LCFieldListDim count As LongDim Session As New LCSession


Connect to the DB2 DatabaseWe now have to establish a connection to the database, using the Connect method of the connection object. We specify the type of the database (DB2), the metadata, that is, the DB2 table (CAFE.EMPLOYEE), and the user ID and password known on the DB2 system:

Set src = New LCConnection ("db2") src.Database = "demo"src.Metadata ="CAFE.EMPLOYEE"src.UserID = "db2admin"src.Password = "db2admin"src.Connect

Query the TableTo query the table, we specify the columns needed, using the FieldNames method:

src.FieldNames = "FIRSTNME,MIDINIT,LASTNAME,WORKDEPT,JOB,SALARY,BONUS"

and the access key name and its value:

Set field = KeyLst.Append ("EMPNO", LCTYPE_TEXT)field.Flags = LCFIELDF_KEYfield.Value = hr_id

This operation generates an SQL statement to the DB2 table. The Select connection method creates a result set of all records from DB2 that match the KeyLst key list. We can now execute the query to generate a result set. The selection returns one of three values: the number of records selected; zero (0) if no matching records where found; or LCCOUNT_UNKNOWN, when records were found but the connection does not know the total:

count = src.Select(KeyLst, 1, FieldOut)

Examine the Result SetThe result set has been created but has not retrieved the data. We use the Fetch connection method to read the data from DB2 into the FieldOut field list. In our sample, we access a unique row so there is no need to enter a loop. We can then copy each field of the field list into the corresponding document fields.

count = src.Fetch(FieldOut) doc.FirstName= FieldOut.FIRSTNME(0)doc.Initial= FieldOut.MIDINIT(0)doc.LastName= FieldOut.LASTNAME(0)doc.CostCenter= FieldOut.WORKDEPT(0)doc.Title= FieldOut.JOB(0)doc.Salary= FieldOut.SALARY(0)


Add, Change, or Delete RowsTo update or delete a row in the result set, you have to create a writeback result set. A writeback result set is an optimized form of result set supported by some Connectors. It provides both sequential read and write operations on the data and can be used for efficient update and remove operations by directly operating on the most recently fetched record in the result set, rather than having to locate the information in the external system a second time. Some Connectors may implement locking in the back end for writeback result sets.

Set src = New LCConnection ("db2") src.Database = "demo"' set the writeback propertysrc.Writeback = "1"src.Metadata ="CAFE.EMPLOYEE"src.UserID = "db2admin"src.Password = "db2admin" src.Connect

We can now create a result set for the same key value (EMPNO) using the Select connection method. We fetch the row, using the Fetch connection method, look up the field value given its name, change the value, and update the row, using the Update connection method:

' Specify the key to access the tableSet field = KeyFields.Append ("EMPNO", LCTYPE_TEXT)field.Flags = LCFIELDF_KEYfield.Value = doc.HR_ID(0)' Select the rowcount = src.Select (KeyFields, 1, Fields)' Fetch the rowcount = src.Fetch ( Fields)' Set Database fields Set field = Fields.Lookup ("FIRSTNME", LCTYPE_TEXT)field.Value = doc.FirstName(0) ' Update with the new valuescount = src.Update(Fields)

Disconnect from the DB2 DatabaseAt the end of the process, when a connection to the database is no longer needed, we can use the Disconnect method of the connection object.

src.Disconnect


Error HandlingWe use the status property of the LSX session class to determine whether the error handler was triggered by an LSX error or a LotusScript error and display a message accordingly:

Handler: If (session.status <> LCSUCCESS) Then

Messagebox session.GetstatusText, 0, + "The following Lotus Connector error has occured"

ElseMessagebox Error$, 0, "The following LotusScript error has occured"

End IfEnd

11.7 DB2 Stored Procedures

An application using stored procedures must be written in two separate procedures. The calling procedure is contained in the client application and executes on the client. It can be written in any of the supported host languages. The stored procedure executes at the location of the database on the database server and must be written in one of the supported languages for that database server.

In our sample, the client application is an agent written with LotusScript. We could have used Java to write the agent or even DECS or a NotesPump Realtime Notes activity to call the stored procedure. The stored procedure runs on the DB2 server machine. It is written in C. We could have used any of the DB2 supported languages such as COBOL, REXX, or Java.

The two procedures must be built in separate steps.

Calling a DB2 Stored ProcedureWe used the ExecProcedure method to call the stp4918 stored procedure. You must catalog the stored procedure in the database on which it will execute, using the CREATE PROCEDURE SQL statement (see Appendix E.2, “Registration” on page 185). You can pass up to 30 parameters—a LotusScript limitation—to the stored procedure. Whether these parameters are used for input, output, or both depends on how the arguments were defined when the stored procedure was cataloged.

The LoadEmployeeDB2BLOB agent, the client application, executes on the client and performs the following actions:

1. Declares, allocates, and initializes storage for the optional data structures and host variables:

Dim SalaryMedian As LongDim workdept As String

2. Connects to a database:

retcode% = Con.ConnectTo( "DEMO", "db2admin", "db2admin" )

3. Invokes the stored procedure through the ExecProcedure method:

rc = res.ExecProcedure ("STP4918" , SalaryMedian , workdept)

where:

STP4918 the registered name of the stored procedure

SalaryMedian an output parameter that receives the value from the stored procedure

workdept an input parameter to the stored procedure

4. Receives the value from the stored procedure:

doc.SalaryMedian= SalaryMedian

5. Disconnects from the database, performing an implicit COMMIT to the database:

If Not Res Is Nothing Then Res.Close(DB_CLOSE) If Not Con Is Nothing Then Con.Disconnect

Writing a DB2 Stored ProcedureWhen invoked, the stored procedure performs the following actions:

1. Accepts the SQLDA data structure from the client application. The host variables are passed through an SQLDA data structure generated by the database manager when the ExecProcedure method is executed.

SQL_API_RC SQL_API_FN stp4918(void *reserved1, void *reserved2, struct sqlda *inout_sqlda, struct sqlca *ca)

2. Assigns the data from the SQLDA to local variables, checking the SQLTYPE of the data sent by the Domino program and the NULL indicator

if ((inout_sqlda->sqlvar[1].sqltype == 449) /* with null indicator */|(inout_sqlda->sqlvar[1].sqltype == 448)) /* w/o null indicator */strcpy(WorkDept, (char*)inout_sqlda->sqlvar[1].sqldata+2);

3. Executes the complete process on the database server under the same transaction as the client application. Here the stored procedure returns the median salary of a group of employees (c1 is the cursor for string s1).

/* Prepare a Statement to Obtain and Order all Salaries */strcpy( stmt, "SELECT salary FROM CAFE.EMPLOYEE WHERE WORKDEPT = '");


strcat( stmt, WorkDept) ;strcat( stmt, "' ORDER BY salary" );EXEC SQL PREPARE s1 FROM :stmt;

/*Determine the Total Number of Records */EXEC SQL SELECT COUNT(*) INTO :num_records FROM CAFE.EMPLOYEE

WHERE WORKDEPT = :WorkDept;

/* Fetch Salaries until the Median Salary is Obtained */EXEC SQL OPEN c1;while ( counter++ < num_records/2 + 1 )

EXEC SQL FETCH c1 USING DESCRIPTOR :*inout_sqlda;EXEC SQL CLOSE c1;EXEC SQL COMMIT;

4. Returns SQLCA information. The output data is returned to the client application using the SQLDA.

/* Return the SQLCA to the Calling Program */memcpy( ca, &sqlca, sizeof( struct sqlca ) );return(SQLZ_DISCONNECT_PROC);

The stored procedure executes when called by the client application. Control is returned to the client when the server procedure finishes processing. You can take several stored procedures and put them into one library.

11.8 JDBC

Whether you are writing an application or applet, you would typically call JDBC APIs to:

• Import the appropriate Java packages and classes (java.sql.*).

• Load the appropriate JDBC driver (sun.jdbc.odbc.JdbcOdbcDriver for JDBC-ODBC driver, COM.ibm.db2.jdbc.app.DB2Driver for applications, COM.ibm.db2.jdbc.net.DB2Driver for applets).

• Connect to the database, specifying the location with a URL (as defined in Sun's JDBC specification) and using the DB2 subprotocol. For applets, you must also provide the user ID, password, host name, and the port number for the applet server; for applications, DB2 CAE provides the required values.

• Pass SQL statements to the database.

• Receive the results.

• Close the connection.

After coding your program, compile it as you would any other Java program. You do not have to perform any special precompile or bind steps.

11.8.1 Distributing and Running a JDBC AppletLike other Java applets, you distribute your JDBC applet over the Web by using either an HTML page or a Domino form or document.

HTML PageYou can embed the applet in an HTML page. For example, to call an applet called TESTApplt.java, code the following tag in an HTML page:

<applet code="TESTApplt.class" width=325 height=275 archive="db2java.zip">

To run your applet, you need a Java-enabled Web browser on the client machine. When you load your HTML page, the applet tag downloads the Java applet to your machine, which then downloads the Java class files, including the COM.ibm.db2.jdbc.net class, which is DB2's JDBC driver. When your applet calls the JDBC API to connect to DB2, the JDBC driver establishes separate communications with the DB2 database through the JDBC applet server on the Domino server.

For your applets to run, you must ensure that the correct files are installed in the proper places and that the DB2 JDBC applet server is started on your Domino server.

Domino Form or DocumentYou can insert the Java applet in a Domino form or document in several different ways:

• Import a copy of an applet into a form or document.

• Copy an applet from an existing document into a different form or document.

• Reference an applet through a URL to the location where the applet is located.

For more information about Domino and applet support, refer to the redbook Developing Web Applications Using Lotus Notes Designer for Domino 4.6, SG24-2183.

11.8.2 Creating a Java Server Agent, Using JDBCDomino supports Java server agents that are Notes API programs written using Java. A Java server agent can use JDBC with either:

• The JDBC-ODBC bridge

• The DB2 JDBC applet driver

or

• The DB2 JDBC application driver

as the Java agent is running on the Domino server and therefore has access to the Notes object interface (NOI).

Writing a JDBC application or applet is similar to writing an ODBC or CLI application, but in Java. Because a Java applet cannot use the NOI, the following sample is valid only for Java applications. The LoadEmployeeNative Java Server agent accesses and manipulates DB2 data through a series of steps (see Appendix D.1, “LoadEmployeeNative Java Server Agent” on page 175):

1. Import the correct JDBC and Lotus Notes packages:

import java.sql.*import lotus.notes.*

2. Create the appropriate JDBC driver object with the appropriate driver manager:

• JDBC-ODBC bridge

java.sql.Driver dr =(java.sql.Driver)Class.forName("sun.jdbc.odbc.JdbcOdbcDriver").newInstance()

• DB2 application JDBC driver

java.sql.Driver dr = (java.sql.Driver)Class.forName("COM.ibm.db2.jdbc.app.DB2Driver").newInstance();

• DB2 applet JDBC driver

java.sql.Driver dr = (java.sql.Driver)Class.forName("COM.ibm.db2.jdbc.net.DB2Driver").newInstance();

3. Register the driver:

DriverManager.registerDriver(dr);

4. Pass the URL to the JDBC driver and its driver manager to connect to the database. The protocol is jdbc.


String url = "jdbc:ODBC:DEMO


String url = "jdbc:db2:demo";



String url = "jdbc:db2://"server+":"+port+"/DEMO";

where:

server the host name of the Domino server

port the TCP/IP port number where the DB2 JDBC applet server is listening

5. Access the Notes session and document context object:

Session session = getSession();AgentContext ac = session.getAgentContext();Document doc = ac.getDocumentContext();

6. Connect to the data source:

Connection con = DriverManager.getConnection(url, userid, password );

7. Create and execute SQL statements to the database:

Statement stmt = con.createStatement();String sql = "Select LASTNAME,SALARY from CAFE.EMPLOYEE where EMPNO = '000100’";)

ResultSet res = stmt.executeQuery( sql );

8. Receive the result set and populate the Notes fields:

boolean rc = res.next();if ( rc ){

doc.replaceItemValue("LastName", res.getString(3));doc.replaceItemValue("Salary", new Double(res.getDouble(6)));

}

9. Close the statements and result sets:

stmt.close();

10.Close the database connection:

con.close();

11.8.3 Running a JDBC Java Server AgentA Java server agent is created by attaching a Java program (.class file) to an agent in a Domino environment. The Java program must be written first and can use JDBC to access DB2 data. The Java agent must be included in the Domino environment, using the agent design pane to import the Java files into the agent. In our sample, we created the LoadEmployeeJavaNative agent to run the LoadEmployeeNative Java program.

1. We created the LoadEmployeeNative agent inside the Domino database (see Figure 27 on page 135).


Figure 27. Java Agent: Creation

2. With the agent in Design mode, we selected the Java option in the design pane and clicked on Import Class Files... The Define Java Agent Files window appears (see Figure 28 on page 135). We selected the directory and the .class files of the LoadEmployeeNative Java agent.

If you have multiple files, you can use the up and down arrows to designate the order in which Domino should load them at run time.

Figure 28. Java Agent: Import Java Files


3. We saved the LoadEmployeeJavaNative agent.

As the Java agent uses DB2 CAE to communicate with the DB2 server, you have no special security concerns; authority verification is performed by the CAE.

11.8.4 Creating a Java Servlet, Using JDBCTo write a servlet, you extend the Servlet class and define Java methods for establishing and managing connections. Servlets offer valuable features such as thread-safe code, automatic memory management, and built-in networking support.

HTTP Servlet ClassOur ReportServletNative extends the Domino server that uses HTTP to interact with clients. We extended the base HTTP servlet class, the javax.servlet.http.HttpServlet class:

// HTTP Classimport javax.servlet.*;import javax.servlet.http.*;// JDBC Classesimport java.sql.*;import COM.ibm.db2.*;

Init MethodThe init method is called once when the Web server loads the servlet. During initialization, the servlet prepares the resources it manages. In our case, we connect to the DB2 DEMO database.

1. We get the initialization parameters from the servlet.cnf file, using the getInitParameter method:

// Get the urlString url = getInitParameter("url");// Get id DB2 userid and passwordString userid = getInitParameter("userid");String password = getInitParameter("password");

2. We create the appropriate JDBC driver object with the appropriate driver manager:


java.sql.Driver dr =(java.sql.Driver)Class.forName("sun.jdbc.odbc.JdbcOdbcDriver").newInstance()



java.sql.Driver dr = (java.sql.Driver)Class.forName("COM.ibm.db2.jdbc.app.DB2Driver").newInstance();


java.sql.Driver dr = (java.sql.Driver)Class.forName("COM.ibm.db2.jdbc.net.DB2Driver").newInstance();

3. We register the driver:

DriverManager.registerDriver(dr);

4. We connect to the data source:

con = DriverManager.getConnection(url, userid, password );

Service MethodThe service method is called each time the servlet is requested. The Domino server passes two parameters to the service method:

• resp, an HttpServletResponse that contains an output string for writing information back to the Web browser.

• req, an HttpServletRequest that contains an input stream for reading the browser’s request

1. We get the Domino database path and the user name for preparing the report:

// Get database path and username for reportdbpath = req.getParameter("Path");user = req.getParameter("User");

2. We set the query, using the getSQL method:

// Get SQL QueryString query = getSQL( req );

The getSQL method gets the elements to build the SQL query:

// Get ParametersString client = req.getParameter("Client");String match = req.getParameter("Match");.......// Set Select ClauseString selectClause = "SELECT EMPID, CLIENT, CREATED, PRODUCT,

TYPE, UNITCOST, QUANTITY FROM CAFE.CONTRACT";// Contruct the where clause from Client and/or Employee ID...... // return SQL Statementreturn selectClause + whereClause + orderByClause;

3. We create a JDBC Statement, that is, an object associated with a connection and used to request an execution of an SQL string:


Statement stmt = con.createStatement();

4. We execute the query:

res = stmt.executeQuery( query );

5. We set up the printing to the browser:

resp.setContentType("text/html");out = resp.getOutputStream();

6. We print the banner:

printBanner();

7. We print the HTML page, using the printContent method:

printContents();

The printContent method creates an HTML page containing the results of the SQL query. It contains:

• The title

out.println("<html>");out.println("<head><title>Query Results</title></head>");out.println("<body>");out.println("<H3>Query Results (ReportServlet) for: "

+ user + "</H3>" );out.println("<HR>");

• The column headings

int numColumns = meta.getColumnCount();out.println("<TABLE COLS=" + String.valueOf(numColumns) +

" BORDER=1 CELLSPACING=0 NOWRAP><TR>");// Print Column HeadingsString label;for( int i = 1; i <= numColumns; i++ ){

label = meta.getColumnLabel(i);out.println("<TH>" + label + "</TH>");

}// Print Extra SubTotal Column that is dynamically createdout.println("<TH>SubTotal</TH>");out.println("</TR>");

• For each SQL row, a line on the HTML page formatting the variables correctly for the page:

out.println("<TR>");for( int j = 1; j <= numColumns; j++ ){value = res.getString(j);

........out.println("</TR>");}while (res.next());

• The total:

out.println("<TR><TD><TD><TD><TD><TD><TD>");

out.println("<TD> TOTAL ");

8. We close the statement and the connection:

stmt.close();

A Domino Form Calling a ServletFigure 29 on page 139 shows the Web page that triggers a servlet. When the Web browser requests to run a servlet, it has to pass:

• The name of the servlet

• The parameters of the servlet required to build the query

Figure 29. Requesting a Servlet

In our example, when you click the Search button, the Web browser program generates the HTTP request (all in one line):

http://china/servlet/ReportServletNative?Client=John&Match=1&ID=000010&Order=CREATED&AscDesc=ASC&Path=/SG244918/Cafe46srl.nsf

&User=Anonymous

where:

china IP name of the serverservlet Servlet directoryReportServletNative

Name of the servletClient, Match, ID, Order, AscDesc

Parameters requested by the servletPath Name of the Domino databaseUser Web user identification

To generate that complex request, we created a Domino form that embeds a JavaScript program.

The JavaScript program searches on the form for the different values entered or selected by the user and concatenates those values with the servlet names and location. The final value is the HTTP request generated.

function performSearch(form){var values = "Client=" + form.ClientName.value + "&" +"Match=" + getCheckBox(form) + "&" +"ID=" + form.EmployeeID.value + "&" +"Order=" +form.OrderByCol.options[form.OrderByCol.selectedIndex].value + "&" +"AscDesc=" + getRadioButton(form) + "&" +"Path=" + form.dbpath.value + "&" +"User=" + form.user.value;var new_href = "http://" + window.location.host +

"/servlet/ReportServletNative?" + values;window.location.href=new_href}

The getCheckBox and getRadioButton functions check whether the Match Exactly check box and the Asc Desc radio buttons have been checked.

11.8.5 Java Development EnvironmentFollow these steps to develop a Java program:

1. Use a text editor or an IDE such as VisualAge for Java.

2. On Windows NT, update the PATH and CLASSPATH variables. The CLASSPATH should contain the JDK, Notes, and DB2 Java packages. For example:


PATH=c:\jdk1.1.3;c:\notes\;CLASSPATH=c:\jdk1.1.3\lib\classes.zip;c:\notes\notes.jar;

c:\sqllib\java\db2java.zip

3. If you are developing a servlet, update the CLASSPATH to add the javax.servlet package:

CLASSPATH=c:\jdk1.1.3\lib\classes.zip;c:\notes\notes.jar;c:\sqllib\java\db2java.zip;c:\jsdk2.0\lib\jsdk.jar

4. Compile the Java program:

javac LoadEmployee

5. Depending on the type of the Java program:

• Copy the compiled servlet into the servlet directory (see “Java Servlet and Domino Server” on page 96)

• Import the server agent class file in the Domino agent (see “Running a JDBC Java Server Agent” on page 134)

11.9 DECS

To create a DECS Realtime activity, you have to create in the DECS Administrator database two documents:

• A Lotus Connection document that defines the connection to the external data source

• A Realtime Activity document that defines a Realtime activity between your Notes application and your external data source

In this section we create a Realtime activity that provides synchronous access from the EmployeeDECS form in the CafePlus.nsf Lotus Notes database and the Employee table in the DEMO DB2 database.

11.9.1 Lotus Connection DocumentWe used the Lotus Connection Document wizard to define the connection to DB2:

1. When we clicked on the Create Connection icon, a list of supported data sources appeared (see Figure 30 on page 142).


Figure 30. Lotus Connection Document: Supported Data Sources List

We selected Connection to DB2 to define our connection.

2. The Lotus Connection document appears (see Figure 31 on page 142). We entered the database name (DEMO), the user ID (db2admin), and the password (db2admin) for the connection.

Figure 31. Lotus Connection Document: Connection to DB2


Clicking on the Owner down-arrow button enables you to select a table by owner name. We selected the owner.

Clicking on the Name down-arrow button displays the list of the tables. We selected the EMPLOYEE table.

Lotus Connection documents are named automatically by the DECS task with a convention that specifies the external system, the database, and the table name. When applicable, the user name required for login to the data source is shown in parentheses.

11.9.2 Realtime Activity DocumentYou use the Realtime Activity wizard to create a Realtime activity. The wizard either prompts you through the steps of creating a Realtime activity or displays a blank Realtime Activity document, which you can fill in to define the activity. In the sample that follows, we used the wizard.

1. We click on the Realtime Activity icon to get a list of Domino databases (see Figure 32 on page 143). We select CafePlus.nsf , which contains the Notes form we want to monitor.

Figure 32. Realtime Activity Document: Domino Database Selection

2. A list of forms within the selected database appears. We select the RepInfoDECS form (see Figure 33 on page 144).


Figure 33. Realtime Activity Document: Notes Form Selection

3. We select the external data source (see Figure 34 on page 144).

.

Figure 34. Realtime Activity Document: Connection Selection

4. The Key and Data Field Mapping dialog box appears (see Figure 35 on page 145).


.

Figure 35. Realtime Activity Document: Key and Data Field Mapping

In this dialog box, we specify:

• The key fields between the Lotus Notes documents and the table rows (EMPNO)

• The mapping of the document’s fields and the table’s columns

5. The Realtime Event Selection dialog box appears (see Figure 36 on page 145).

.

Figure 36. Realtime Activity Document: Realtime Event Selection

In this dialog box, you can select when the Realtime activity is triggered. Four events are available: create, open, update, and delete document.


6. You can then select specific options such as monitoring the order of multiple activities, setting the maximum number of connections to DB2 to open simultaneously, and disabling caching in the HTTP server. You can also execute a Notes formula or a DB2 stored procedure before or after the event depending on its type (see Figure 37 on page 146).

Figure 37. Realtime Activity Document: Options

In our sample, we do not specify any options.

7. We save the activity, naming it DECSEmployeeRealtime.

11.9.3 Running the ActivityAs we created a new database, the documents are not yet created. We used the Initialize Keys command to initialize the documents in the Lotus Notes database, that is, using the form Employee, create a document containing the EMPNO key for each row of the DB2 EMPLOYEE table.

Then, we start the activity. With this Realtime Activity definition, each time we open a document using the RepInfoDECS form, in the CafePlus.nsf Lotus Notes database, the activity gets the corresponding information from the DB2 table and displays it in the fields of the form.


11.10 NotesPump

NotesPump is an nonprogrammatic alternative to accessing DB2 data from a Domino document. Because NotesPump copies data from one environment to another, the application can use a local copy of the data. Data replication enables remote users with slow network connections or mobile users without any connection to work with a local copy. The application should not require real-time data such as stock values but allow some discrepancy between the copy and the source data. Data copy is especially useful for reference data such as product descriptions or customer information. However, from an administration point of view, you must carefully plan the data replication to understand how to restore the data in case of a failure of one or both copy partners.

11.10.1 Links We first defined the DB2 and Notes links. A link defines how NotesPump accesses DB2 and Notes. It provides NotesPump with all the information required to locate the data.

• To define a link to a Notes database, you must know its name and the name of the server where it is located. We defined our connection to the Notes server, using the following information:

Link Name : NotesLinkNotes Server : china/asiaNotes Database : CafePlus.nsfCategory : Notes Link

• To define a link to a DB2 database, you need to know its name as referenced in DB2 CAE, and the user ID and password that is to be used for connecting. For example:

Link Name : DB2LinkDatabase : DEMOUser Name : db2adminPassword : db2adminCategory : DB2 Link

When the links are created, you can test them, using the lnktest command. lnktest.exe uses native APIs to test native connectivity.

C:\NPUMP>lnktest "DB2Link"Testing DB2LinkDB2Link Connect Successful

C:\NPUMP>lnktest "Noteslink"


Testing NotesLinkNotesLink Connect Successful

11.10.2 ActivitiesIn this section we describe how to create NotesPump activities between the DB2 DEMO database and the Lotus Notes CafePlus.nsf database.

Note : As we tried to use the same names in the DB2 table and the Notes forms, the DB2 column names are in capital letters, and as the Notes fields are in lower case in the description that follows.

Direct Transfer ActivityA Direct Transfer activity transfers data from one database to another, for example, from the DB2 departments tables to the CafePlus.nsf Lotus Notes database. To define the activity, we created a Direct Transfer activity document with the following information:

Activity Name : department Direct TransferLinks

Source : DB2LinkDestination : NotesLink

MetadataSource Table Name : CAFE.DEPARTMENTDestination Form Name : department

Field MappingMap Field By Name

Command StatementSELECT * FROM CAFE.DEPARTMENT

Direct Transfer OptionsCreate Metadata if Necessary

Activity OptionsDesignated Server : NpumpX

Email NotificationMail Recipients : AdministratorSend Log Report and Status : On Error

SchedulingEnable/Disabled : Schedule Disable

Category : DB2 To Notes Direct Transfer

Realtime Notes Activity Like a DECS Realtime activity, a NotesPump Realtime Notes activity provides synchronous access to DB2 from a Lotus Notes application. It intercepts and acts on Lotus Notes database events (for example open, create, update, or delete documents), obtaining real-time access from the Lotus Notes form to DB2.


We set up a Realtime Notes activity that accesses DB2 department records when opening a CafePlus.nsf department form.

First, we created the department documents that contain the key for each row of the DB2 table. We used a Direct Transfer activity to transfer the key only.

Activity Name : Department Direct Transfer (Key Only)Field Mapping

Map Field as User DefineSource Field List : DEPTNODestination Field List : deptno

Then, to define the activity, we created a Realtime Notes activity document with the following information:

Activity Name : Employee Realtime NotesLinks

Notes Database: CafePlusExternal Link : DB2Link

MetadataNotes Form Name : departmentNotes Key List : deptnoNotes Field List : admrdept, deptname, mgrnoDB2 Table Name : CAFE.DEPARTMENTDB2 Key List : DEPTNODB2 Field List : ADMRDEPT, DEPTNAME, MGRNO

Realtime Notes EventsIntercept Document Open




Category : DB2 To Notes Realtime Notes

When the Realtime Notes activity has started, each time a department form in the Lotus Notes database is opened, the activity accesses in real-time the department table, reads the DB2 columns, and displays the values in the corresponding Notes fields in the form.

Primary Key Replication ActivityWe created a replication activity that replicates department D11 employee records between the DB2 EMPLOYEE table and the Notes Employee form.


We created a Direct Transfer activity that copies DB2 employee records to the CafePlus.nsf database:

Activity Name : Employee Direct TransferLinks

Source : DB2LinkDestination : NotesLink

MetadataSource Table Name : CAFE.EMPLOYEEDestination Form Name : employee

Field MappingMap Field By Name

Command StatementSELECT * FROM CAFE.EMPLOYEE

Direct Transfer OptionsCreate Metadata if Necessary




Category : DB2 To Notes Direct Transfer

We ran the Direct Transfer activity to create the Notes documents for each row of the EMPLOYEE table.

We added a new date and time field (called DTM) in the Employee form, computed with the following formula:

@if(@IsDocBeingSaved;@Now;@Modified)

We created the employeeB form, a copy the Employee form. In the NotesPump Administrator, we created a replication activity between the two Notes documents, using a primary key.

Activity Name : Employee ReplicationLinks

Link A : NotesLinkLink B : NotesLink

ReplicationLink A

Form Name : employeeKey Field : empnoConditional Clause : @Contains(workdept; "D11")

Link BForm Name : employeeB


Key Field : empnoMap Fields By Name

Conflict ResolutionLink A is Master




Category : Notes To Notes Replication

When running this activity, you create a duplicate set of employee documents using the EmployeeB form. You can create a view to display them. When you update any document using the EmployeeB form, the update is replicated to the equivalent document that uses Employee form.

Primary Key/Timestamp Replication ActivityWe transformed the Primary Key Replication activity into a Primary Key/Timestamp Replication activity by adding the timestamp field in the Replication activity document:

ReplicationLink A

Form Name : employeeKey Field : empnoConditional Clause : @Contains(workdept; "D11")Timestamp Field : DTM

Link BForm Name : employeeBKey Field : DempnoTimestamp Field : DTM

Using a Primary Key/Timestamp activity, we can replicate the two sets of documents that have been updated after the last replication only.

11.11 Programmatic Solution

In this example, we created a sample C program that our sample application calls. When the LoadEmployeeDLL agent is started, it calls the db24918 C language DLL with the appropriate parameters. The C language function then parses the employee ID, accesses the EMPLOYEE table, and retrieves the employee record based on the employee ID.


Notice that this DLL runs on the Domino server and therefore accesses the DB2 server at each SQL request. However, you can combine this solution with a DB2 stored procedure to possibly gain some performance benefits.

11.11.1 Domino AgentIn this section we describe how we created the Domino agent that calls the DLL.

DeclarationA Lotus Notes application such as an agent can issue calls to external C language functions that reside in a DLL. The DLL must be declared in the agent in the declaration section. We declared the db24918 function with all its input and output parameters and its return value.

Declare Function db24918 Lib "g:\sg244918\storProc\db24918.dll" _(Byval db2empID As String, _Byval db2FirstName As String, _Byval db2Initial As String, _Byval db2Lastname As String, _Byval db2Title As String , _Byval db2CostCenter As String , _db2Salary As Long, _db2Bonus As Long ) _As Integer

UsageIn the initialize event of the agent, we just have to initialize the parameters that are exchanged with the function, setting the string fields to the maximum length and the numeric values to 0.

hr_id = Mid( doc.query_string(0), 10 ) ' Initialize the variables given the right lenghtfirstname = "123456789012" Initial = "1"Lastname = "123456789012345 "Title = "12345678"CostCenter = "123"Salary = 0Bonus = 0

We can then call the function, giving all the parameters.

Dim status As Integerstatus = db24918( hr_id ,Firstname, Initial, Lastname, _

Title, CostCenter, Salary , Bonus )


If the call is successful, that is, status=0, we can move the return values to the fields of the form that is displayed.

doc.DHR_ID= hr_iddoc.FirstName= Firstnamedoc.Initial= Initialdoc.LastName= Lastnamedoc.CostCenter= Costcenterdoc.Title= Titledoc.Salary= Salarydoc.Bonus= Bonus

11.11.2 DB2 Dynamic Link LibraryWhen invoked, the DB2 DLL, running on the Domino server and using the DB2 CAE, performs the following actions:

1. Accepts the parameters passed from the Domino agent

SQL_API_RC SQL_API_FN db24918( char * L_EmpNo , char * L_FirstName , char * L_MidInit , char * L_LastName , char * L_Job , char * L_WorkDept , long int * L_Salary , long int * L_Bonus )

2. Declares the host variables used to move data between DB2 and the DLL environments

EXEC SQL BEGIN DECLARE SECTION;char EmpNo[7]= " " ;char FirstName[13] =" " ;char MidInit[2] = " " ;char LastName[16] = " " ;char Job[9] = " " ;char WorkDept[4] = " " ;long int Salary = 0 ;long int Bonus = 0 ;

EXEC SQL END DECLARE SECTION;

3. Creates a context, allowing the Domino thread to access the DB2 environment

rc = sqleBeginCtx ( NULL, SQL_CTX_BEGIN_ALL ,


NULL, &sqlca);

4. Connects to the database

EXEC SQL CONNECT TO demo USER db2admin USING db2admin ;

5. Executes the query

strcpy ( EmpNo , L_EmpNo ) ;EXEC SQL DECLARE C1 CURSOR FOR SELECT EMPNO, FIRSTNME, MIDINIT, LASTNAME,

JOB, WORKDEPT, SALARY, BONUS FROM CAFE.EMPLOYEE WHERE EMPNO = :EmpNo ;EXEC SQL OPEN C1 ;EXEC SQL FETCH C1 INTO :EmpNo, :FirstName, :MidInit , : LastName ,

:Job , :WorkDept , :Salary , :Bonus ;EXEC SQL CLOSE C1 ;

6. Moves the data back to the passed structure

*L_Salary = Salary ;.......strcpy ( L_EmpNo , EmpNo ) ;.....strcpy ( L_WorkDept , WorkDept ) ;

7. Resets the connection to the database

EXEC SQL CONNECT RESET;

8. Deletes the context

rc = sqleEndCtx (NULL,SQL_CTX_END_ALL ,NULL,&sqlca);

The DLL executes on the client machine when called by the client application. control is returned to the client application when the DLL finishes processing.


Chapter 12. Implementation

When implementing an integrated Domino application that uses DB2 data, you have to understand the requirements and concerns in the following areas:

• Security

• Backup and recovery

• Availability

12.1 Security

Security mechanisms, such as user authentication and access control, are important to protect applications and data from unauthorized access.

In a Domino environment that supports Web users and uses NotesPump to integrate corporate data, security management is complex as it covers four different areas:

• Domino application

• Lotus Notes client users

• Web access

• Enterprise data

12.1.1 Domino ApplicationIn addition to authenticating users and checking whether they are authorized to access the resources they are requesting, Domino offers different levels of security according to the access from the Lotus Notes client or the Web browser:

• Database level security, using the database’s access control list (ACL) to assign different access levels to different users or groups of users

• Form and view level security, which restricts the use of a particular form or view

• Document level security, allowing the owner of a document to restrict access to specific users or groups of users, in both read-only and update mode

• Field level security, which restricts access to certain fields of documents to specific users or groups of users, in both read-only and update mode


12.1.2 Lotus Notes Client UsersThe Domino server authenticates Lotus Notes client users through certificates based on public and private keys. It compares the certificate presented by the user with certificates in its possession. If any of the certificates presented by the user were issued and signed by an entity that issued and signed one of the server’s own certificates, or if the server issued a certificate to the user, the server can use that fact to establish the identity of the user. This certification scheme is a common method of authentication, used not only by Lotus Notes but also in other software security implementations.

12.1.3 Web AccessUsers are granted access to the Domino Web server through basic authentication, the standard for Web security based on a challenge/response mechanism. Web users are challenged for a user name and password; after giving the correct response, they are given access to the Web site's databases.

Unless you want all Web users to access the Domino server anonymously, you must set up Web user authentication at the server. For each Web user who is allowed to access the Domino server, you have to create a Person document and add an HTTP password. The Domino Web site has a sample registration application available for you to download.

Although basic Web authentication is not considered as secure as Lotus Notes public key certificate-based authentication as it does not involve a certifier who validates the user’s identity, it does allow Domino to serve users through the Internet.

Any Web user who does not supply a name and password is referred to within Domino as Anonymous. To control access, you create an Anonymous entry in the Name and Address book of the Domino server and assign the appropriate access in the ACL: Reader access for an information database, Author access for an interactive database, No Access to prevent access.

Alternatively you can prevent server access by anonymous Web users. If the administrator deselects the Allow anonymous connections option in the Security section of the Server document, all anonymous Web users receive an authorization failure message when they access the server. This setting overrides individual database access controls for anonymous users.


You can force users to supply a name and password even after they have been authenticated by appending &Login as an argument to a URL command, such as OpenDatabase, OpenView, and OpenDocument.

12.1.4 EncryptionDomino offers encryption to secure the transmission of data through the network.

For Lotus Notes clients, encryption is implemented using a pair of matched keys. Messages are encrypted and decrypted using a public key and a private key. One key is useless without the other, that is, a message encrypted with a public key can only be decrypted with the associated private key.

For Web clients, encryption is implemented by using the Secure Sockets Layer (SSL) protocol, which provides communication privacy and authentication over the Internet. When the Domino Web server is configured for SSL transactions, it can encrypt data that passes between Web clients and the server. Enabling SSL ensures that HTTP data is encrypted to and from clients. Privacy is ensured during transactions as an encoded message digest accompanies data to detect any message tampering, and the server's digital signature accompanies messages to assure clients that they received their message from the correct server.

12.1.5 DB2 DataTo access data you must have the authority to access the database and the privilege to perform the action. Two levels of security control access to DB2 data and functions: authentication and authorization.

Access to DB2 is managed by facilities specific to the operating system. On Windows NT, a user must first be declared in the Windows NT user manager with an ID and a password. To access DB2 for Windows NT resources, the user gives the ID and password, which is checked by the DB2 Security server. Once this process is done, the user is authenticated, that is, the system has checked that the user is really who he or she claims to be.

Once the user is authenticated, DB2 obtains information about the authenticated user that indicates the database operations he or she may perform and which data he or she can access. This information is stored in some system DB2 tables.

Implementation 157

12.1.6 NotesPumpNotesPump, as a Lotus Notes application, follows the Domino security mechanisms. The Notes ID running the NotesPump server is identified by Domino in the same manner as is a Lotus Notes user. The ACL of the NotesPump Administrator database should allow the NotesPump server to create documents and run agents. The NotesPump Administrator database provides Author privileges at the document level.

NotesPump, as a bridge between the Domino environment and the database environment, provides the mapping between Lotus Notes authentication and DB2 authentication. When opening a document, the user—from either the Web, Lotus Notes, or the NotesPump server—is authenticated to the Domino environment with a Notes ID that is unknown in the database environment. To access DB2, NotesPump switches to a DB2 user ID and password to be authenticated by the DB2 environment. The mapping is defined in the Link document, in the user ID and password fields.

The DBMS security system may require password change. For example, RACF, an MVS security manager, requires that passwords be changed after a certain predefined number of days. In this case, the NotesPump activity connecting to a DB2 for MVS database is also required to change its password stored in the NotesPump Link document.

Pay special attention to security when using a Realtime Notes activity. Because all users—from Lotus Notes clients and Web browsers— use a single login to the database, security must be at the Notes document level, by using Reader or Author fields to restrict access to the Notes document. Once in the Notes document, a user can access that data from the database, using the Realtime Notes activity.

12.1.7 User MappingBoth Domino and DB2 have their own security management. In both environments, users have to identify and authenticate themselves, using a valid user ID and password. Once users are authenticated, they can run only the applications for which they are authorized.

Apart from the identification mechanism used by Domino for its own purposes, user identification can be managed by using:

• A unique ID to access the DB2 database

• Multiple IDs, one ID for each user accessing the DB2 database


Unique ID With the unique ID approach, security is fully handled by Domino. Each user, using his or her Notes ID and the associated password, logs on to the server where the application resides. The Domino application logs on to DB2, using a unique ID and password on behalf of its clients. All user queries are transmitted under this unique ID, which requires the highest authorization level of the application's routines; that is, if the application has three routines that require three different levels of authorization, the application should access the back-end system, using the highest level.

From an administration point of view, the unique ID approach requires that users maintain their passwords associated with their Notes IDs. The system administrator maintains passwords associated with the Notes unique IDs. Specifically, in MVS, passwords are valid only for a limited amount of time, typically 30 days. Whenever the password expires, the system administrator has to reset it.

Domino controls access through the ACL. It manages the users' rights to access Domino resources. Because the user IDs are translated to the unique IDs when users connect to the back-end system, Lotus Notes is also responsible for allowing users to perform the routines on the back-end system.

If needed, logging of events is to be managed from the Domino environment. The back-end system does not know who is performing the routine as all the Domino users get the same unique ID on the back-end system. Domino does not provide a logging function, and one has to be developed.

Multiple IDsWith the multiple ID approach, a different user ID is used for each user to access the back-end system. When you are using, for example, the DB2 CLI driver to DB2, if you do not provide a user ID and password, you are prompted for one.

Of course, the multiple ID approach is more complicated than the unique ID approach because users have to remember different IDs and passwords. This may cause confusion because users have to log on twice in the same application to two different environments: one local on the Domino server, one remote on the DB2 server.

From an administration point of view, the multiple ID approach requires users to maintain two IDs, one for the Domino environment and one for the DB2 server.

Implementation 159

With the multiple ID approach Domino manages access control for its own environment, and the enterprise application manages access control for its own environment. Each is responsible for its own security.

A full control and audit can be done because logging of events can be managed by the back-end system as each user is correctly identified to it.

12.2 Backup and Recovery

Recovery, in its broadest sense, means repositioning, after a failure, each system component to a known stable state such that no important information is lost. To perform a system or application recovery, operations personnel restore an image—the backup—of that system or application and apply on that image all modifications—kept in the log files—that occur between the backup and the failure. In a DB2 environment, recovery has mainly been a system function activated by operation personnel.

In a Domino environment, at least one replica copy of each database is maintained, but this cannot prevent a corrupted database portion from being replicated. Because Domino does not provide a logging function, backup is done by either developing in the application itself some logging functions or using the system backup, which covers Domino databases as a portion of the whole system.

When a Domino application is integrated with DB2, for backup and recovery purposes, both have to apply their own procedure to ensure the recoverable status of each environment. There is no coordination between the system backup implemented in Domino and the backup implemented in DB2. This fact has to be taken into account during application design as it has several implications:

• The scope of the units of work should be limited to one environment.

• The relationship between Domino data and DB2 data should not include referential integrity. If the unit of work is to cross both environments, access in one environment should be limited to read only. There is no DUW implemented between Domino and DB2.

• A Domino application should directly access DB2 data only for information browsing, not for updating, to prevent jeopardizing DB2 data integrity.

12.3 Availability

When applications integrate both environments, they depend on the availability of three major software components:


• Domino server

• DB2 server

• Connector

and, of course, the availability of the network.

You need to have all the components available to use the application.

However, there are some ways to minimize the impact of the unavailability of one component. Using NotesPump activities, you can duplicate the DB2 data to the Domino server. If DB2, the connector, or the network fails, you may be able to use the application in a backup mode, using local copies of the data instead of the operational data. When the components are up and running again, you have to provide a function to resynchronize the local data managed by Domino with the operational data managed by DB2.

Implementation 161

Appendix A. LotusScript Data Option Agent

In this appendix we list the agents using an ODBC connction to DB2.

A.1 LoadEmployeeODBCDB2 Agent

Option PublicUselsx "*LSXODBC"

Dim Con As ODBCConnection 'LSDO Connection ObjectDim Qry As ODBCQuery 'LSDO Query Object Dim Res As ODBCResultSet 'LSDO Result Set Object

Sub Initialize 'Create Connection object Set Con = New ODBCConnection 'Connect to data source 'DEMO' Dim ds As String, user As String, pw As String ds = "DEMO" user = "db2admin" pw = "db2admin" retcode% = Con.ConnectTo( ds, user, pw ) 'Exit if Connection failed If ( retcode% = False ) Then Msgbox "Could not connect to datasource " + ds error% = conn.GetError extendedMessage$ = conn.GetExtendedErrorMessage(error%) Msgbox extendedMessage$ Exit Sub End If 'Create Query object Set Qry = New ODBCQuery 'Assign Connection to Query Set Qry.Connection = Con 'Access NotesSession object and Document Context Object Set sess = New NotesSession Set doc = sess.DocumentContext 'Strip HR_ID from Query_String field Format :"OpenForm&000123"


Dim hr_id As String hr_id = Mid( doc.query_string(0), 10 ) 'Assign SQL Query Qry.SQL = "Select FIRSTNME,MIDINIT,LASTNAME,WORKDEPT, " _ + "JOB,SALARY,BONUS from CAFE.EMPLOYEE " _ + " where EMPNO ='" + hr_id+"'" 'Create ResultSet Object Set Res = New ODBCResultSet 'Assign Query to ResultSet Set Res.Query = Qry 'Execute Query retcode% = Res.Execute 'Exit if Execute failed If ( retcode% = False ) Then Msgbox "Could not execute query :" + Qry.SQL error% = data.GetError extendedMessage$ = data.GetExtendedErrorMessage(error%) Msgbox extendedMessage$ Exit Sub End If 'If No ResultSet then Exit sub If Not Res.IsResultSetAvailable() Then Msgbox "No rows returned " Exit Sub End If 'Otherwise Populate fields doc.HR_ID= Format(hr_id,"000000") doc.DHR_ID= doc.HR_ID doc.FirstName= Res.GetValue("FIRSTNME") doc.Initial= Res.GetValue("MIDINIT") doc.LastName= Res.GetValue("LASTNAME") doc.CostCenter= Res.GetValue("WORKDEPT") doc.Title= Res.GetValue("JOB") doc.Salary= Res.GetValue("SALARY") doc.Bonus= Res.GetValue("BONUS") End SubSub Terminate 'Free Result Set


If Not Res Is Nothing Then Res.Close(DB_CLOSE) 'Disconnect from datasource If Not Con Is Nothing Then Con.Disconnect End Sub

A.2 UpdateEmployeeODBCDB2 Agent

Option PublicUselsx "*LSXODBC"

Dim Con As ODBCConnection 'LSDO Connection ObjectDim Qry As ODBCQuery 'LSDO Query Object Dim Res As ODBCResultSet 'LSDO Result Set Object

Sub Initialize 'Create Connection object Set Con = New ODBCConnection 'Connect to data source 'DEMO' Dim ds As String, user As String, pw As String ds = "DEMO" user = "db2admin" pw = "db2admin" retcode% = Con.ConnectTo( ds, user, pw ) 'Exit if Connection failed If ( retcode% = False ) Then Msgbox "Could not connect to datasource " + ds error% = conn.GetError extendedMessage$ = conn.GetExtendedErrorMessage(error%) Msgbox extendedMessage$ Exit Sub End If 'Create Query object Set Qry = New ODBCQuery 'Assign Connection to Query Set Qry.Connection = Con 'Access NotesSession object and Document Context Object Dim session As New NotesSession

LotusScript Data Option Agent 165

Dim doc As NotesDocument Set doc = session.DocumentContext 'Assign SQL Query Qry.SQL = "Select FIRSTNME,MIDINIT,LASTNAME,WORKDEPT," _ + " JOB,SALARY,BONUS from CAFE.EMPLOYEE " _ + " where EMPNO ='" +doc.HR_ID(0)+"'" 'Create ResultSet Object Set Res = New ODBCResultSet 'Assign Query to ResultSet Set Res.Query = Qry 'Execute Query retcode% = Res.Execute 'Exit if Execute failed If ( retcode% = False ) Then Msgbox "Could not execute query :" + Qry.SQL error% = data.GetError extendedMessage$ = data.GetExtendedErrorMessage(error%) Msgbox extendedMessage$ Exit Sub End If 'If No ResultSet then Exit sub If Not Res.IsResultSetAvailable() Then Msgbox "No rows returned " Exit Sub End If 'Otherwise Set Database fields Call Res.SetValue("FIRSTNME", doc.FirstName(0) ) Call Res.SetValue("MIDINIT", doc.Initial(0) ) Call Res.SetValue("LASTNAME", doc.LastName(0) ) Call Res.SetValue("WORKDEPT", doc.CostCenter(0) ) Call Res.SetValue("JOB", doc.Title(0) ) Call Res.SetValue("SALARY", doc.Salary(0) ) Call Res.SetValue("BONUS", doc.bonus(0) ) 'Update the database If Not Res.UpdateRow Then Msgbox" Update FAILED" End If End Sub


Sub Terminate 'Free Result Set If Not Res Is Nothing Then Res.Close(DB_CLOSE) 'Disconnect from datasource If Not Con Is Nothing Then Con.Disconnect End Sub

LotusScript Data Option Agent 167

Appendix B. DB2LSX Agent

In this appendix we list the agent developed with DB2LSX.

B.1 LoadEmployeeDB2BLOB Agent

Option PublicUselsx "*LSXDB2"

Dim Con As DB2Connection 'DB2 Connection ObjectDim Qry As DB2Query 'DB2 Query Object Dim Res As DB2ResultSet 'DB2 Result Set Object

Sub Initialize Dim FileName As String, chSize As Integer Dim offset As Integer , chunck As String 'Create Connection object Set Con = New DB2Connection 'Connect to data source 'DEMO' Dim ds As String, user As String , pw As String ds = "DEMO" user = "db2admin" pw = "db2admin" retcode% = Con.ConnectTo( ds, user, pw ) 'Exit if Connection failed If ( retcode% = False ) Then Msgbox "Could not connect to datasource " + ds error% = conn.GetError extendedMessage$ = conn.GetExtendedErrorMessage(error%) Msgbox extendedMessage$ Exit Sub End If 'Create Query object Set Qry = New DB2Query 'Assign Connection to Query Set Qry.Connection = Con 'Access NotesSession object and Document Context Object Set sess = New NotesSession Set doc = sess.DocumentContext


'Strip HR_ID from Query_String field Format :"OpenForm&000123" Dim hr_id As String Dim SalaryMedian As Long Dim workdept As String hr_id = Mid( doc.query_string(0), 10 ) 'Assign SQL Query Qry.SQL = "Select FIRSTNME,MIDINIT,LASTNAME,WORKDEPT, " _ + " JOB,SALARY,BONUS, PICTURE, RESUME " _ + " from cafe.EmpPhotoResume where EMPNO ='" + hr_id +"'" 'Create ResultSet Object Set Res = New DB2ResultSet 'Assign Query to ResultSet Set Res.Query = Qry 'Execute Query retcode% = Res.Execute 'Exit if Execute failed If ( retcode% = False ) Then Msgbox "Could not execute query : " + Qry.SQL error% = data.GetError extendedMessage$ = data.GetExtendedErrorMessage(error%) Msgbox extendedMessage$ Exit Sub End If 'If No ResultSet then Exit sub If Not Res.IsResultSetAvailable() Then Msgbox "No rows returned " Exit Sub End If 'Otherwise Populate fields doc.HR_ID= Format(hr_id,"000000") doc.DHR_ID= doc.HR_ID doc.FirstName= Res.GetValue("FIRSTNME") doc.Initial= Res.GetValue("MIDINIT") doc.LastName= Res.GetValue("LASTNAME") doc.CostCenter= Res.GetValue("WORKDEPT") doc.Title= Res.GetValue("JOB") doc.Salary= Res.GetValue("SALARY") doc.Bonus= Res.GetValue("BONUS")


' BLOB FileName = "Pic_" & HR_ID & ".gif" PicFile = Res.getValueAsFile("PICTURE", "data/domino/html/" _ + FileName) doc.Photo = "[<img src=/" + FileName + ">]" ' CLOB chSize = 500 offset = 1 Do Chunck= Res.getChunk("RESUME", offset , chSize) doc.Resume = doc.Resume(0) & Chunck offset = offset + chSize Loop Until Len(Chunck) < chSize ' Stored Procedure workdept = "A00" j= res.ExecProcedure ("STP4918" , SalaryMedian , workdept) doc.SalaryMedian= SalaryMedian End SubSub Terminate 'Free Result Set If Not Res Is Nothing Then Res.Close(DB_CLOSE) 'Disconnect from datasource If Not Con Is Nothing Then Con.Disconnect End Sub

DB2LSX Agent 171

Appendix C. Lotus Connector LSX agent

In this appendix we list the agent developed with LC LSX.

C.1 LoadEmployeeDB2LDC Agent

Option PublicUselsx "*lsxlc"

Sub Initialize On Error Goto Handler Dim src As LCConnection Dim keyLst As New LCFieldList Dim field As LCField Dim FieldOut As New LCFieldList Dim count As Long Dim Session As New LCSession session.ClearStatus 'Connect to DB2 and database DEMO Set src = New LCConnection ("db2") src.Database = "demo" src.Metadata ="CAFE.EMPLOYEE" src.UserID = "db2admin" src.Password = "db2admin" src.Connect 'Access NotesSession object and Document Context Object Set sess = New NotesSession Set doc = sess.DocumentContext 'Strip HR_ID from Query_String field Format :"OpenForm&000123" Dim hr_id As String hr_id = Mid( doc.query_string(0), 10 ) 'We specify which columns are needed src.FieldNames = "FIRSTNME,MIDINIT,LASTNAME," _ + "WORKDEPT,JOB,SALARY,BONUS" ' Specify the key to access the table Set field = keyLst.Append ("EMPNO", LCTYPE_TEXT) field.Flags = LCFIELDF_KEY ' and its value field.Value = hr_id ' Execute the query


count = src.Select(keyLst, 1, FieldOut) ' Fetch the unique row count = src.Fetch(FieldOut) ' And Populate fields doc.HR_ID= Format(hr_id,"000000") doc.DHR_ID= doc.HR_ID doc.FirstName= FieldOut.FIRSTNME(0) doc.Initial= FieldOut.MIDINIT(0) doc.LastName= FieldOut.LASTNAME(0) doc.CostCenter= FieldOut.WORKDEPT(0) doc.Title= FieldOut.JOB(0) doc.Salary= FieldOut.SALARY(0) doc.Bonus= FieldOut.BONUS(0) Exit Sub Handler: If (session.status <> LCSUCCESS) Then Messagebox session.GetstatusText, 0, _ + "The following Lotus Connector error has occured" Else Messagebox Error$, 0, _ + "The following LotusScript error has occured" End If End End SubSub Terminate End Sub

Appendix D. JDBC Agent and Servlet

In this appendix we list the Java JDBC agent and servlet.

D.1 LoadEmployeeNative Java Server Agent

import lotus.notes.*;import java.sql.*;import COM.ibm.db2.*; public class LoadEmployeeNative extends AgentBase{ public void NotesMain() { try { String userid = "db2admin"; String password = "db2admin";

// // Uncomment the following lines for DB2 applet JDBC Driver // // URL //String server = "127.0.0.1"; //String port = "2200"; //String url = "jdbc:db2://"+server+":"+port+"/sample"; // // Create JDBC Driver object (DB2 applet JDBC Driver) //java.sql.Driver dr = (java.sql.Driver) // Class.forName("COM.ibm.db2.jdbc.net.DB2Driver").newInstance();

// the following lines define the DB2 application JDBC Driver // URL String url = "jdbc:db2:sample";

// Create JDBC Driver object (DB2 application JDBC Driver) java.sql.Driver dr = (java.sql.Driver) Class.forName("COM.ibm.db2.jdbc.app.DB2Driver").newInstance();

// Register Driver DriverManager.registerDriver(dr);

// Connect to data source Connection con = DriverManager.getConnection(url, userid, password );

// Create a JDBC Statement. A JDBC Statement is an // object associated to a connection


// and used to request an execution of a SQL String. Statement stmt = con.createStatement();

// Access Session and DocumentContext object Session session = getSession(); AgentContext ac = session.getAgentContext(); Document doc = ac.getDocumentContext();

// get HR_ID from Query_String field Format: "OpenForm&XXXXXX" String query_string = doc.getItemValueString("Query_String"); String hr_id = query_string.substring(9);

// Create SQL String String sql = "Select FIRSTNME,MIDINIT,LASTNAME,WORKDEPT, " + " JOB,SALARY,BONUS from EMPLOYEE " + " where EMPNO = '" + hr_id + "'";

// Execute Query ResultSet res = stmt.executeQuery( sql );

// The method next() needs to be called // first to access the first row boolean rc = res.next();

// Populate Fields if ( rc ) { doc.replaceItemValue("HR_ID", hr_id ); doc.replaceItemValue("DHR_ID", hr_id ); doc.replaceItemValue("FirstName", res.getString(1)); doc.replaceItemValue("Initial", res.getString(2)); doc.replaceItemValue("LastName", res.getString(3)); doc.replaceItemValue("CostCenter", res.getString(4)) doc.replaceItemValue("Title", res.getString(5)); doc.replaceItemValue("Salary",new Double(res.getDouble(6))); doc.replaceItemValue("Bonus", new Double(res.getDouble(7))); } // Close statement and connection stmt.close(); con.close(); } catch ( Exception e ) { e.printStackTrace(); } }}


D.2 ReportServletNative Java Servlet

import java.io.*;import java.text.*;import javax.servlet.*;import javax.servlet.http.*;import java.sql.*;import COM.ibm.db2.*;

public class ReportServletNative extends HttpServlet{ private ServletOutputStream out; private ResultSet res; private static Connection con = null; private String dbpath, user;

public void init(ServletConfig conf ) throws ServletException { try super.init(conf);

// Set Database URL to specify a specific database and protocol to use // DB2 Native Driver accessing a local DB2 Server // e.g. "jdbc:db2://127.0.0.1:2200/demo" String url = getInitParameter("url"); // Create Driver object from JDBC:DB2 Driver java.sql.Driver dr = (java.sql.Driver) Class.forName("COM.ibm.db2.jdbc.net.DB2Driver").newInstance();

// Register Driver DriverManager.registerDriver(dr);

// Get id DB2 userid and password from String userid = getInitParameter("userid"); String password = getInitParameter("password");

// Connect to data source con = DriverManager.getConnection(url, userid, password ); } catch ( Exception e ) { e.printStackTrace(); } }

JDBC Agent and Servlet 177

public void service(HttpServletRequest req, HttpServletResponse resp)throws IOException{try { // Get database path and username for report dbpath = req.getParameter("Path"); user = req.getParameter("User"); // Get SQL Query String query = getSQL( req ); // Create a JDBC Statement. A JDBC Statement is // an object associated to a connection // and used to request an execution of a SQL String. Statement stmt = con.createStatement();

// Execute Query res = stmt.executeQuery( query );

// Set up Printing to Browser resp.setContentType("text/html"); out = resp.getOutputStream();

// Print Banner printBanner();

// Print HTML Page printContents();

// Close statement and connection stmt.close(); } catch ( Exception e ) { e.printStackTrace(); } }

private void printBanner() throws IOException{out.println("<CENTER>");out.println("<A HREF=\"" + dbpath + "?OpenDatabase\"><IMG align=top SRC=\"" + dbpath +"/Web+Reference/navbull/$File/navbull.gif\" border=0>" + "Home</A>");out.println("<A HREF=\"/domguide.nsf?OpenDatabase\"><IMG align=top SRC=\"" + dbpath +"/Web+Reference/navbull2/$File/navbull2.gif\" border=0>" + "Help</A>");

out.println("</CENTER>");}

private void printContents() throws IOException{try{// Print Titleout.println("<html>");out.println("<head><title>Query Results</title></head>");out.println("<body>");out.println("<H3>Query Results (ReportServlet) for: " + user + "</H3>" );out.println("<HR>");

// Print Resultsif ( !res.next() ){out.println("No rows Returned");}else{// Get Properties of result set via ResultSetMetaData objectResultSetMetaData meta = res.getMetaData();

// Define table columnsint numColumns = meta.getColumnCount();out.println("<TABLE COLS=" + String.valueOf(numColumns) + " BORDER=1 CELLSPACING=0 NOWRAP><TR>");

// Print Column HeadingsString label;for( int i = 1; i <= numColumns; i++ ) { label = meta.getColumnLabel(i); out.println("<TH>" + label + "</TH>"); }

// Print Extra SubTotal Column that is dynamically createdout.println("<TH>SubTotal</TH>");out.println("</TR>");

// Loop through the result set datadouble subtotal = 0.0, total = 0.0, cost = 0.0;int qty = 0;String value = "";NumberFormat currency = NumberFormat.getCurrencyInstance();do {

out.println("<TR>"); for( int j = 1; j <= numColumns; j++ ) { value = res.getString(j); // if the EMPID column, Make a URL link out of the EMPID if ( meta.getColumnLabel(j).equals("EMPID") ) value = "<A HREF=\"" + dbpath + "/RepInfoJavaNative?OpenForm&" + value + "\">" + value + "</A>"; else if ( meta.getColumnLabel(j).equals("UNITCOST") ) { cost = new Double(value).doubleValue(); value = currency.format(cost); } else if ( meta.getColumnLabel(j).equals("QUANTITY") ) { qty = new Double(value).intValue(); value = String.valueOf(qty); } out.println("<TD>" + value ); } // Get Subtotal of unitcost * quantity and print subtotal value subtotal = cost * qty; out.println("<TD>" + currency.format(subtotal));

// keep running total of subtotals total = total + subtotal; out.println("</TR>");}while (res.next());

// Print Totalout.println("<TR><TD><TD><TD>" + "<TD><TD><TD>");out.println("<TD> TOTAL ");out.println("<TD>" + currency.format(total) + "");out.println("</TR>");

out.println("</TABLE>");out.println("</body></html>");}}catch( SQLException ex ) { ex.printStackTrace(); }}

private String getSQL(HttpServletRequest req ){// Get ParametersString client = req.getParameter("Client");String match = req.getParameter("Match");String id = req.getParameter("ID");String order = req.getParameter("Order");String ascdesc = req.getParameter("AscDesc");

// Set Select ClauseString selectClause = " SELECT EMPID, CLIENT, CREATED, PRODUCT, " + " TYPE, UNITCOST, QUANTITY FROM CAFE.CONTRACT";

// Set where clause from Client and/or Employee IDString op = "=", matchch = "'";

if (match.equals("0") ) { op = " LIKE "; matchch = "%'"; }op += "'";String tmpClient = "";if (!client.equals("")) { tmpClient = "CLIENT" + op + client + matchch; if ( !id.equals("")) tmpClient += " AND "; }

String tmpId = "";if (!id.equals("")) tmpId = "EMPID=\'" + id + "'";

String where = ""; if (!(tmpClient + tmpId).equals("")) where = " WHERE ";

String whereClause = where + tmpClient + tmpId;

// Create Order By ClauseString orderByClause = "";

if (!order.equals("None")) { orderByClause = " ORDER BY " + order; if ( ascdesc.equals("DESC") )


orderByClause += " DESC"; }// return SQL Statementreturn selectClause + whereClause + orderByClause;}

public String getServletInfo(){return "Reporting Servlet";}

public void destroy(){try { if (con != null) con.close(); }catch ( Exception e ){e.printStackTrace();}}}


Appendix E. Stored Procedure

In this appendix we list the C-language stored procedure that we developed for the application. This stored procedure runs on the DB2 server machine and is called by the Lotus Notes LoadEmployeeDB2BLOB agent. We also show the SQL statement used to register the stored procedure in the DB2 UDB catalog tables.

E.1 Code

/**** SG24-4918 Using DB2 in a Domino ENvironment**** Source file name = stp4918**** This sample program demonstrates stored procedures** called from a DB2LSX**** External dependencies:** - existence of database for precompile purpose** - Precompile with the SQL precompiler (PREP in DB2)** - Bind to a database (BIND in DB2)** - Compile and Link with IBM VisualAge for C++****/

#include <memory.h>#include <string.h>#include <sqlenv.h>#include <sqlutil.h>#include <stdio.h>#include "util.h"

SQL_API_RC SQL_API_FN stp4918(void *reserved1, void *reserved2, struct sqlda *inout_sqlda, struct sqlca *ca){/* Declare a local SQLCA */ EXEC SQL INCLUDE SQLCA;

/* Declare Host Variables */ EXEC SQL BEGIN DECLARE SECTION ; char WorkDept[3] ; short num_records;

char stmt[512]; EXEC SQL END DECLARE SECTION;

/* Declare Miscellaneous Variables */ int counter = 0;

EXEC SQL WHENEVER SQLERROR GOTO error_exit; EXEC SQL WHENEVER SQLWARNING CONTINUE; EXEC SQL DECLARE c1 CURSOR FOR s1;

/* Assign the data from the SQLDA to local variables */ /* check of the sqltype that is returned by the caller */ if ((inout_sqlda->sqlvar[1].sqltype == 449) /* with null indicator */ |(inout_sqlda->sqlvar[1].sqltype == 448)) /* w/o null indicator */ /*NotesPump returns a VARCHAR for a TEXT field */ strcpy(WorkDept, (char*)inout_sqlda->sqlvar[1].sqldata+2); else if ((inout_sqlda->sqlvar[1].sqltype == 453) /* with null indicator */ |(inout_sqlda->sqlvar[1].sqltype == 452)) /* w/o null indicator */ /* DB2LSX returns a CHAR for a TEXT field */ strcpy(WorkDept, (char*)inout_sqlda->sqlvar[1].sqldata);

/* Prepare a Statement to Obtain and Order all Salaries */ strcpy( stmt, "SELECT salary FROM CHRISTO.EMPLOYEE WHERE WORKDEPT = '"); strcat( stmt, WorkDept) ; strcat( stmt, "' ORDER BY salary" ); EXEC SQL PREPARE s1 FROM :stmt;

/*Determine the Total Number of Records */ EXEC SQL SELECT COUNT(*) INTO :num_records FROM CHRISTO.EMPLOYEE

WHERE WORKDEPT = :WorkDept;

/* Fetch Salaries until the Median Salary is Obtained */ EXEC SQL OPEN c1; while ( counter++ < num_records/2 + 1 ) EXEC SQL FETCH c1 USING DESCRIPTOR :*inout_sqlda; EXEC SQL CLOSE c1; EXEC SQL COMMIT;

/* Return the SQLCA to the Calling Program */ memcpy( ca, &sqlca, sizeof( struct sqlca ) ); return(SQLZ_DISCONNECT_PROC);

error_exit: /* An Error has occurred -- ROLLBACK and return to Calling Program */ EXEC SQL WHENEVER SQLERROR CONTINUE; memcpy( ca, &sqlca, sizeof( struct sqlca ) ); EXEC SQL ROLLBACK;

return(SQLZ_DISCONNECT_PROC);}

E.2 Registration

Stored procedures must to be registered in DB2 UDB in the SYSCAT.PROCEDURES and SYSCAT.PROCPARMS tables. These tables are available in DB2 UDB Version 5 only. Here is the SQL statement to register a stored procedure:

DROP PROCEDURE STP4918;CREATE PROCEDURE STP4918 (INOUT WORKDEPT CHAR(3),INOUT SALARY INTEGER)EXTERNAL NAME 'stp4918'LANGUAGE CPARAMETER STYLE DB2DARI;

Stored Procedure 185

Appendix F. C Program

In this appendix we list the C language program that we developed for the application. It runs as a DLL on the Domino server and is called by the LoadEmployeeDLL agent.

/**** SG24-4918 Using DB2 in a Domino Environment**** Source file name = db24918**** This sample program demonstrates how to create a DLL that** is called from a Domino agent to access DB2 data**** External dependencies:** - existence of database for precompile purpose** - Precompile with the SQL precompiler (PREP in DB2)** - Bind to a database (BIND in DB2)** - Compile and Link with IBM VisualAge for C++****/

#include <memory.h>#include <string.h>#include <sqlenv.h>#include <sqlca.h>#include <sqlutil.h>#include <stdio.h>#include "util.h"

SQL_API_RC SQL_API_FN db24918( char * L_EmpNo , char * L_FirstName , char * L_MidInit , char * L_LastName , char * L_Job , char * L_WorkDept , long int * L_Salary , long int * L_Bonus ){

FILE *logfile; long L_SQLCODE ; int rc ;

/* Declare a local SQLCA */ EXEC SQL INCLUDE SQLCA;

/* Declare Host Variables */ EXEC SQL BEGIN DECLARE SECTION; char EmpNo[7]= " " ; char FirstName[13] =" " ; char MidInit[2] = " " ; char LastName[16] = " " ; char Job[9] = " " ; char WorkDept[4] = " " ; long int Salary = 0 ; long int Bonus = 0 ; EXEC SQL END DECLARE SECTION;

/* Create a context */ rc = sqleBeginCtx ( NULL, SQL_CTX_BEGIN_ALL , NULL, &sqlca);

/* Declare Miscellaneous Variables */ EXEC SQL WHENEVER SQLERROR GOTO error_exit; EXEC SQL WHENEVER SQLWARNING CONTINUE;

/* Open the log file */ logfile = fopen("test.log", "a"); fprintf(logfile, "-- Start -- db24918\n");

fprintf(logfile, "Step Connection \n") ; EXEC SQL CONNECT TO SAMPLE USER db2admin USING db2admin ;

strcpy ( EmpNo , L_EmpNo ) ; fprintf(logfile, "column value : %s\n", EmpNo) ;

/* Execute the query */ EXEC SQL DECLARE C1 CURSOR FOR SELECT EMPNO, FIRSTNME, MIDINIT, LASTNAME,

JOB, WORKDEPT, SALARY, BONUS FROM EMPLOYEE WHERE EMPNO = :EmpNo ;

/* Open, fetch, and close the cursor */ EXEC SQL OPEN C1 ; EXEC SQL FETCH C1 INTO :EmpNo, :FirstName, :MidInit , : LastName ,

:Job , :WorkDept , :Salary , :Bonus ;


fprintf(logfile, " Fetch from C1, SQLCODE= %d\n", SQLCODE) ; EXEC SQL CLOSE C1 ;

fprintf(logfile, "row fetched, LastName : %s\n", LastName) ; /* Set pointers to the integer */ *L_Salary = Salary ; *L_Bonus = Bonus ;

/* Set Pointers to Strings */ strcpy ( L_EmpNo , EmpNo ) ; strcpy ( L_FirstName , FirstName ) ; strcpy ( L_MidInit , MidInit ) ; strcpy ( L_MidInit , MidInit ) ; strcpy ( L_LastName , LastName ) ; strcpy ( L_Job , Job ) ; strcpy ( L_WorkDept , WorkDept ) ;

/* Check SQLCA code for errors */ if (SQLCODE == 0) EXEC SQL COMMIT ; else EXEC SQL ROLLBACK ;

/* reset the connection to the database */ EXEC SQL CONNECT RESET;

/* Delete the context */ rc = sqleEndCtx ( NULL, SQL_CTX_END_ALL , NULL, &sqlca);

/* Close the log file */ fclose(logfile);

return (0) ;

error_exit: /* An Error has occurred -- ROLLBACK and return to Calling Program */ fprintf(logfile, " End Error Connection to Sample, SQLCODE= %d\n", SQLCODE) ; /* Keep the SQLCODE to return it to the agent */ L_SQLCODE = SQLCODE ;

EXEC SQL WHENEVER SQLERROR CONTINUE; EXEC SQL ROLLBACK;

C Program 189

EXEC SQL CONNECT RESET;

/* Delete the context */ rc = sqleEndCtx ( NULL, SQL_CTX_END_ALL , NULL, &sqlca);

fprintf(logfile, " Error Exit\n") ; /* Close the log file */ fclose(logfile);

/* return the SQLCODE */ return(L_SQLCODE);}


Appendix G. DB2 for Domino

DB2 for Domino is a solution enabler that provides Lotus Notes users and Lotus Domino application developers with easy, unlimited access to the relational data management capabilities of DB2. DB2 for Domino describes the Lotus and IBM software that is covered by pricing terms and conditions that make it easy and cost-effective for Lotus Notes and Domino clients and applications to work with relational data stored in a DB2 Universal Database.

The DB2 for Domino application connectors are the connectivity software by which Domino or Notes applications on a Domino server or Notes client access data stored in a DB2 Universal Database. There are two DB2 for Domino application connectors:

• DB2LSX, the DB2 for Domino application connectors for coding applications

• NotesPump, the DB2 for Domino application connectors for configuring applications

DB2 was the first relational database to support JDBC, and Lotus developers have begun to exploit it using the new Domino 4.6 Java agent support. Using VisualAge for Java, a developer can create Domino agents that access the native DB2 JDBC client interface.

For DB2 Universal Database Workgroup Edition customers, IBM is making available for purchase a server authorization, the DB2 for Domino Connections Entitlement, for unlimited access of local DB2 data from Domino server and Lotus Notes applications through the DB2 for Domino application connectors. Together, The DB2 for Domino application connectors and the DB2 for Domino Connections Entitlement allow Notes developers to extend their applications' functionality at a price that fits their customer's budget. In combination, these DB2 for Domino mechanisms establish a more comprehensive linkage between Notes and DB2 than what is currently available in the market.

To encourage customer use of the combination of DB2 with Domino server or Lotus Notes applications, IBM has changed the terms and conditions of DB2 Universal Database Enterprise Edition (EE) and DB2 Universal Database Enterprise - Extended Edition (EEE) programs to allow customers more flexibility when determining DB2 licensing requirements. Customers of EE and EEE no longer need to obtain DB2 user entitlements for access to local DB2 data through either Domino server or Lotus Notes applications.


The following conditions require DB2 use authorizations (refer to the Software Announcement 297-364, dated September 16, 1997):

• Lotus customers who are accessing DB2 data outside their Lotus Notes/Domino server application

• Lotus customers accessing data on host systems through DB2 Connect

• DB2 users not accessing DB2 through Domino server or Lotus Notes applications

As well, IBM is making available license authorizations that allow unlimited access to data on a DB2 Universal Database Workgroup Edition (WE) server from Lotus Notes or Domino applications. To utilize this DB2 for Domino licensing arrangement, a customer has to purchase one additional entitlement, or Lotus Notes/Domino connection, for each DB2 Universal Database Workgroup Edition server.


Appendix H. Special Notices

This publication is intended to help information systems architects, database administrators, and Lotus Notes developers integrate Domino applications with a DB2 data store. The information in this publication is not intended as the specification of any programming interfaces that are provided by DB2 or Lotus Domino. See the PUBLICATIONS section of the IBM Programming Announcement for DB2 for more information about what publications are considered to be product documentation.

References in this publication to IBM products, programs or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent program that does not infringe any of IBM's intellectual property rights may be used instead of the IBM product, program or service.

Information in this book was developed in conjunction with use of the equipment specified, and is limited in application to those specific hardware and software products and levels.

IBM may have patents or pending patent applications covering subject matter 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 the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, NY 10594 USA.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Dept. 600A, Mail Drop 1329, Somers, NY 10589 USA.

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The information contained in this document has not been submitted to any formal IBM test and is distributed AS IS. The information about non-IBM ("vendor") products in this manual has been supplied by the vendor and IBM assumes no responsibility for its accuracy or completeness. The use of this information or the implementation of any of these techniques is a customer responsibility and depends on the customer's ability to evaluate and integrate them into the customer's operational environment. While each item may have


been reviewed by IBM for accuracy in a specific situation, there is no guarantee that the same or similar results will be obtained elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk.

Any pointers in this publication to external Web sites are provided for convenience only and do not in any manner serve as an endorsement of these Web sites.

Any performance data contained in this document was determined in a controlled environment, and therefore, the results that may be obtained in other operating environments may vary significantly. Users of this document should verify the applicable data for their specific environment.

Reference to PTF numbers that have not been released through the normal distribution process does not imply general availability. The purpose of including these reference numbers is to alert IBM customers to specific information relative to the implementation of the PTF when it becomes available to each customer according to the normal IBM PTF distribution process.

The following terms are trademarks of the International Business Machines Corporation in the United States and/or other countries:

The following terms are trademarks of the Lotus Development Corporation in the United States and/or other countries:

The following terms are trademarks of other companies:

C-bus is a trademark of Corollary, Inc.

Java and HotJava are trademarks of Sun Microsystems, Incorporated.

Microsoft, Windows, Windows NT, and the Windows 95 logo are trademarksor registered trademarks of Microsoft Corporation.

PC Direct is a trademark of Ziff Communications Company and is used

AIX AS/400DB2 DPROPROS/400 OS/390IBM MVSESA OS/2

Lotus DominoLotus Notes NotesNotesPump


by IBM Corporation under license.

Pentium, MMX, ProShare, LANDesk, and ActionMedia are trademarks orregistered trademarks of Intel Corporation in the U.S. and othercountries.

UNIX is a registered trademark in the United States and othercountries licensed exclusively through X/Open Company Limited.

Other company, product, and service names may be trademarks orservice marks of others.

Special Notices 195

Appendix I. Related Publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this redbook.

I.1 International Technical Support Organization Publications

For information on ordering these ITSO publications see “How To Get ITSO Redbooks” on page 195.

The other books of the Lotus Solution for the Enterprise Collection are:

• Volume 1 - Lotus Notes: An Enterprise Application Platform, SG24-4837

• Volume 3 - Using the IBM CICS Gateway for Lotus Notes, SG24-4512

• Volume 4 - Lotus Notes and the MQSeries Enterprise Integrator, SG24-2217

• Volume 5 - NotesPump: The Enterprise Data Mover, SG24-5255

These publications are also relevant as further information sources:

• Enterprise Integration with Domino.Connect, SG24-2181

• Lotus Notes Release 4.5: A Developer’s Handbook, SG24-4876

• Designing Web Applications Uisng Lotus Notes Designer for Domino 4.6, SG242183

• The Domino Defense: Security in Lotus Notes and the Internet, SG24-4848

• Java Network Security, SG24-2109

• Enterprise Integration with Domino for S/390, SG24-5150

• The Universal Connectivity Guide to DB2, SG24-4894

I.2 Redbooks on CD-ROMs

Redbooks are also available on CD-ROMs. Order a subscription and receive updates 2-4 times a year at significant savings.

CD-ROM Title Subscription Number

Collection Kit Number

System/390 Redbooks Collection SBOF-7201 SK2T-2177Networking and Systems Management Redbooks Collection SBOF-7370 SK2T-6022


I.3 Other Publications and Web Sites

These publications and Web sites are also relevant as further information sources:

I.3.1 Domino

• Publications

The Application Developer Doc Pack (Lotus SKU 027645) contains the following publications:

• Lotus Notes Designer for Domino 4.6 Application Developer's Guide

• Lotus Notes Designer for Domino 4.6 Programmer's Guide

• Lotus Notes Designer for Domino 4.6 Release Notes

• Lotus Notes Release 4.5 Database Manager's Guide

• LotusScript 4.6 Classes Poster

• Application Development Roadmap

• Lotus Notes 4.6 Release Notes

• Lotus Domino 4.6 Release Notes

• LotusScript 3.1 Language Reference Manual

• LotusScript Programmer's Guide

• Web Sites

• http://www.lotus.com, for information about Lotus

• http://domino.lotus.com, for information about Domino

• http://www.eicentral.lotus.com, for information about Lotus Enterprise Integration, including DB2LSX, NotesPump, LEI, LC, and DECS

Transaction Processing and Data Management Redbook SBOF-7240 SK2T-8038Lotus Redbooks Collection SBOF-6899 SK2T-8039

Tivoli Redbooks Collection SBOF-6898 SK2T-8044AS/400 Redbooks Collection SBOF-7270 SK2T-2849RS/6000 Redbooks Collection (HTML, BkMgr) SBOF-7230 SK2T-8040

RS/6000 Redbooks Collection (PostScript) SBOF-7205 SK2T-8041RS/6000 Redbooks Collection (PDF Format) SBOF-8700 SK2T-8043Application Development Redbooks Collection SBOF-7290 SK2T-8037

CD-ROM Title Subscription Number

Collection Kit Number


• http://www.lotus-developer.com for information about Lotus products including Domino for developers

• http://www.s390.ibm.com/products/domino, for information about Domino for S/390

• http://www.as400.ibm.com/notes, for information about Domino for AS/400

• http://www.ibm.com/java for IBM information about Java

• http://www.software.ibm.com/data/db2/java for DB2 Java support

• http://java.sun.com/products/jdk/1.1 for Sun information about the JDK 1.1

I.3.2 DB2

• Publications

• IBM DB2 Universal Database Administration Getting Started, S10J-8154

• IBM DB2 Universal Database Administration Guide Version 5, S10J-8157

• IBM DB2 Universal Database Messages Reference Version 5, S10J-8168

• IBM DB2 Universal Database Roadmap to DB2 Programming, S10J-8155

• IBM DB2 Universal Database SQL Reference Version 5, S10J-8165

• Web Sites

• http://www.software.ibm.com/data/db2/udb, for information about DB2 Universal Database Version 5

Related Publications 199

How to Get ITSO Redbooks

This section explains how both customers and IBM employees can find out about ITSO redbooks, CD-ROMs, workshops, and residencies. A form for ordering books and CD-ROMs is also provided.

This information was current at the time of publication, but is continually subject to change. The latest information may be found at http://www.redbooks.ibm.com/ .

How IBM Employees Can Get ITSO Redbooks

Employees may request ITSO deliverables (redbooks, BookManager BOOKs, and CD-ROMs) and information about redbooks, workshops, and residencies in the following ways:

• Redbooks Web Site on the World Wide Web

http://w3.itso.ibm.com/

• PUBORDER – to order hardcopies in the United States

• Tools Disks

To get LIST3820s of redbooks, type one of the following commands:

TOOLCAT REDPRINT TOOLS SENDTO EHONE4 TOOLS2 REDPRINT GET SG24xxxx PACKAGE TOOLS SENDTO CANVM2 TOOLS REDPRINT GET SG24xxxx PACKAGE (Canadian users only)

To get BookManager BOOKs of redbooks, type the following command:

TOOLCAT REDBOOKS

To get lists of redbooks, type the following command:

TOOLS SENDTO USDIST MKTTOOLS MKTTOOLS GET ITSOCAT TXT

To register for information on workshops, residencies, and redbooks, type the following command:

TOOLS SENDTO WTSCPOK TOOLS ZDISK GET ITSOREGI 1998

• REDBOOKS Category on INEWS

• Online – send orders to: USIB6FPL at IBMMAIL or DKIBMBSH at IBMMAIL

For information so current it is still in the process of being written, look at "Redpieces" on the Redbooks Web Site (http://www.redbooks.ibm.com/redpieces.html ). Redpieces are redbooks in progress; not all redbooks become redpieces, and sometimes just a few chapters will be published this way. The intent is to get the information out much quicker than the formal publishing process allows.

Redpieces


How Customers Can Get ITSO Redbooks

Customers may request ITSO deliverables (redbooks, BookManager BOOKs, and CD-ROMs) and information about redbooks, workshops, and residencies in the following ways:

• Online Orders – send orders to:

• Telephone Orders

• Mail Orders – send orders to:

• Fax – send orders to:

• 1-800-IBM-4FAX (United States) or (+1) 408 256 5422 (Outside USA) – ask for:

Index # 4421 Abstracts of new redbooksIndex # 4422 IBM redbooksIndex # 4420 Redbooks for last six months

• On the World Wide Web

In United StatesIn CanadaOutside North America

IBMMAILusib6fpl at ibmmailcaibmbkz at ibmmaildkibmbsh at ibmmail

[email protected]@[email protected]

United States (toll free)Canada (toll free)

1-800-879-27551-800-IBM-4YOU

Outside North America(+45) 4810-1320 - Danish(+45) 4810-1420 - Dutch(+45) 4810-1540 - English(+45) 4810-1670 - Finnish(+45) 4810-1220 - French

(long distance charges apply)(+45) 4810-1020 - German(+45) 4810-1620 - Italian(+45) 4810-1270 - Norwegian(+45) 4810-1120 - Spanish(+45) 4810-1170 - Swedish

IBM PublicationsPublications Customer SupportP.O. Box 29570Raleigh, NC 27626-0570USA

IBM Publications144-4th Avenue, S.W.Calgary, Alberta T2P 3N5Canada

IBM Direct ServicesSortemosevej 21DK-3450 AllerødDenmark

United States (toll free)CanadaOutside North America

1-800-445-92691-800-267-4455(+45) 48 14 2207 (long distance charge)

Redbooks Web SiteIBM Direct Publications Catalog

http://www.redbooks.ibm.comhttp://www.elink.ibmlink.ibm.com/pbl/pbl

For information so current it is still in the process of being written, look at "Redpieces" on the Redbooks Web Site (http://www.redbooks.ibm.com/redpieces.html ). Redpieces are redbooks in progress; not all redbooks become redpieces, and sometimes just a few chapters will be published this way. The intent is to get the information out much quicker than the formal publishing process allows.

Redpieces


IBM Redbook Order Form

Please send me the following:

We accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card notavailable in all countries. Signature mandatory for credit card payment.

Title Order Number Quantity

First name Last name

Company

Address

City Postal code

Telephone number Telefax number VAT number

Invoice to customer number

Country

Credit card number

Credit card expiration date SignatureCard issued to

203

Glossary

@DbFunction. A fast and easy-to-use read-only access method to ODBC-compliant DBMSs.

access control list . (1) A collection of all access rights for one object. (2) A list associated with an object that identifies all subjects that can access the object and their access rights; for example, a list associated with a file that identifies users who can access the file and their access rights to that file.

application programming interface (API). A set of calling conventions defining how a service is invoked through a software package.

agent. A Lotus Notes routine that automates tasks. Agents perform routine Lotus Notes tasks in the background. You can program agents, using LotusScript or the Lotus Notes formula language.

application unit of work. A set of actions within an application that the designer chooses to regard as an entity. It is up to the designer to decide how, if at all, an application should be subdivided into application units of work, and whether any application unit of work will consist of one, or many, logical units of work (LUWs).

authentication . (1) Verification of the identity of a user or the user's eligibility to access an object. (2) Verification that a message has not been altered or corrupted. (3) A process used to verify the user of an information system or protected resources.

authorization . (1) The right granted to a user to communicate with or make use of a computer system. (2) An access right. (3) The process of granting a user either complete or restricted access to an object, resource, or function.

certificate . A message signed with a public key digital signature stating that a specified public key belongs to someone or something with a specified name.

certification authority . An entity—typically a company—that issues digital certificates to

© Copyright IBM Corp. 1998

other entities (organisations or individuals) to allow them to prove their identity to others

certification. In Lotus Notes, the process of having an authorized (the certifier) person authenticate the identity of a user or server.

call level interface (CLI). A callable API for database access, which is an alternative to the embedded SQL API. In contrast to embedded SQL, CLI does not require precompiling or binding by the user but instead provides a standard set of functions to process SQL statements and related services at runtime.

client. As in client/server computing, the application that makes requests to the server and, often, deals with the interaction necessary with the user.

client/server computing. A form of distributed processing, in which the task required to be processed is accomplished by a client portion that requests services and a server portion that fulfills those requests. The client and server remain transparent to each other in terms of location and platform. See client, distributed processing, and server.

commit. An operation that applies all changes made during the current unit of work.

database. (1) A collection of interrelated data stored together with controlled redundancy according to a scheme to serve one or more applications. (2) All data files stored in the system. (3) A set of data stored together and managed by a database management system. (4) In Lotus Notes, a group of documents and their forms and views, stored under one file.

distributed processing. An application or systems model in which function and data can be distributed across multiple computing resources connected on a local area network or wide area network. See client/server computing.

document. In Lotus Notes, an object containing text, graphics, video, or audio data or any kind of rich text data.

205

Domino . Lotus Domino is an applications and messaging server with an integrated set of services that enable you to easily create secure, interactive business solutions for the Internet and corporate intranets.

electronic messaging. The creation, transfer, storage, and retrieval of text, graphics, image, or voice data by electronic means.

environment. The collective hardware and software configuration of a system.

form . In Lotus Notes, forms are used to author, read, and edit documents. Application developers design forms as templates for document creation, or as a way to view document data. Forms are comprised of other design elements such as text, fields, buttons, and programming code.

formula. A Lotus Notes programming language that contains a set of built-in macros, functions, and commands.

graphical user interface (GUI). A style of user interface that replaces the character-based screen with an all-points-addressable, high-resolution graphics screen. Windows display multiple applications at the same time and allow user input by means of a keyboard or a pointing device such as a mouse, pen, or trackball.

host. (1) In a computer network, a computer providing services such as computation, database access, and network control functions. (2) The primary or controlling computer in a multiple computer installation.

index . An ordered set of pointers to the data of a DBMS table. An index allows more efficient access to rows in a table by creating a direct path to the data through the pointers. Each index is stored separately from the table it refers to and is based on the values of data in one or more columns of the table.

intranet. A TCP/IP network that is entirely under the control of a private authority or company. The intranet may or may not have connections to other independent intranets (which would then be referred to as extranets) or the Internet. It may or may not be fully or partially visible to the outside, depending on the implementation.

Internet. Large international, national, and regional backbone networks that allow local and campus networks and individuals access to global resources.

link . A defined connection from the NotesPump server to a specific database product with specific access parameters, such as user IDs and passwords.

Lotus Notes. A groupware application that helps organizations communicate, collaborate, and coordinate business processes.

LotusScript. The Lotus cross-product BASIC scripting language.

logical unit of work (LUW). (1) An update that durably transforms a resource from one consistent state to another consistent state. (2) A sequence of processing actions (for example, database changes) that must be completed before any of the individual actions can be regarded as committed. When changes are committed (by successful completion of the LUW and recording of the syncpoint on the system log), they do not have to be backed out after a subsequent error within the task or region.

metadata . A defining unit of data such as a database table, data file, or Notes form.

metalink . A special kind of NotesPump link that provides preprocessing operations on link data before it is transferred within a defined Activity form. Two metalinks—Order and Collapse/Expand — are supplied with NotesPump 2.5.

middleware. A set of services that allow distributed applications to interoperate on a local area network or wide area network. It shields the developer or end user from the system complexity and enables delivery of service requests or responses transparently across computing resources.

NotesPump. A data distribution server that offers high-volume data exchange and synchronization with DB2, Oracle, Lotus Notes, ASCII/Text file, Sybase, and ODBC databases.

object. A program or a group of data that can behave like a thing in the real world.


Open Database Connectivity (ODBC). A Microsoft developed C database API that allows access to DBMSs through callable SQL, which does not require the use of an SQL preprocessor.

recovery. The use of archived copies to reconstruct files, databases, or complete disk images after they are lost or destroyed.

replication. A Lotus Notes procedure that updates and distributes copies (replicas) of the same Lotus Notes database that are stored on different servers.

rich text. A Lotus Notes field capable of storing a variety of type styles, graphics, and multimedia.

server. Any computing resource dedicated to responding to client requests. Servers can be linked to clients through local area networks or wide area networks to perform services, such as printing, database access, fax, and image processing, on behalf of multiple clients at the same time.

structured query language (SQL). A standard set of statements used to manage information stored in a database. By using these statements, users can add, delete, or update information in a table, request information through a query, and display the result in a report.

stored procedures. A facility to execute procedures that are stored at the server. Stored procedures allow an application program to be run in two parts. One part runs on the client, and the other on the server. Thus one call to a remote database can execute a procedure that may represent several repetitive accesses to the database. The server procedure at the database runs within the same transaction as the client application.

table. A relational database presents data as a collection of tables. A table consists of data logically arranged in columns and rows. The data in the table is logically related, and relationships can be defined between tables. Data can be viewed and manipulated on the basis of mathematical principles and operations called relations. Table data is accessed through SQL.

Transmission Control Protocol/Internet Protocol (TCP/IP). A set of communication protocols that support peer-to-peer connectivity functions for both local and wide area networks.

transaction. A unit of processing (consisting of one or more application programs) initiated by a single request. A transaction can require the initiation of one or more tasks for its execution.

transaction processing. A style of computing that supports interactive applications in which requests submitted by users are processed as soon as they are received. Results are returned to the requester in a relatively short period of time. A transaction processing system supervises the sharing of resources for processing multiple transactions at the same time.

unit of work. A recoverable sequence of operations performed by an application between two points of consistency.

view. (1) In Lotus Notes, views are used to sort, list, filter, and categorize documents. Application developers design views with particular selection criteria so that they will display lists of pertinent documents in a given order. (2) In a relational DBMS, a view is an efficient way of representing data without having to maintain it; it can include all or some of the columns or rows of the tables on which it is defined.

Web. See World Wide Web

Web browser. The client component of the World Wide Web. The Web browser is responsible for formatting and displaying information, interacting with the user, and invoking external viewers for data types that it does not support directly. Examples of Web browsers are Mosaic and Netscape.

Web server. The server component of the World Wide Web. It is responsible for servicing requests for information from Web browsers. The information can be a file retrieved from the server’s local disk or generated by a program called by the server to perform a specific application function.

World Wide Web. (WWW) (W3) (the Web) An Internet client/server distributed information and

207

retrieval system based on HTTP that transfers hypertext documents across a varied array of computer systems.

workstation. (1) A configuration of input and output equipment at which an operator works. (2) A terminal or microcomputer, usually one that is connected to a mainframe or a network, at which a user can perform applications.


List of Abbreviations

API application programming interface

AR application requester

AS application server

ACL access control list

APPC Advanced Program-to-Program Communication

ASCII American National Standard Code for Information Interchange

BLOB binary large object

CAE client application enabler

CCD consistent change data

CGI Common Gateway Interface

CICS Customer Information Control System

CLI call level interface

CLOB character large object

CORBA Common Object Request Broker Architecture

DBCLOB double-byte character large object

DBMS database management system

DB2LSX DB2 LotusScript Extension

DCE distributed computing environment

DDCS Distributed Database Connection Services

DECS Domino Enterprise Connection Services

© Copyright IBM Corp. 1998

DLL dynamic link library

DPROPR DataPropagator Relational

DNS domain name server

DRDA Distributed Relational Database Architecture

DUW distributed unit of work

EBCDIC extended binary coded decimal interchange code

ERP enterprise resource planning

ESA Enterprise Systems Architecture

FTP file transfer protocol

GUI graphical user interface

HTML Hypertext Markup Language

HTTP Hypertext Transfer Protocol

IBM International Business Machines Corporation

IDE integrated development environment

IIOP Internet Inter-ORB Protocol

IMAP Internet Message Access Protocol

ITSO International Technical Support Organization

JDBC Java database connectivity

JDK Java Development Kit

JVM Java virtual machine

LAN local area network

LC Lotus Domino Connector

209

LDAP Lightweight Directory Access Protocol

LEI Lotus Enterprise Integrator for Domino

LS:DO LotusScript Data Option

LSX LotusScript Extension

LUW logical unit of work

MAPI messaging application program interface

MIME Multipurpose Internet Mail Extension

MPP massively parallel processors

MQEI MQSeries Enterprise Integrator

MQI message queue interface

MQLSX MQSeries link LotusScript Extension

MVS Multiple Virtual Storage

MTA message transfer agent

NC network computer

NCF network computing framework

NDS NetWare Directory Service

NetBIOS Network Basic Input/Output System

NNTP NetNews Transfer Protocol

NOI Notes object interface

NOS Notes object store

NT Microsoft Windows NT (new technology)

OCI Oracle call interface

ODBC open database connectivity

OLAP online analytical processing

OLE object linking and embedding

OLTP online transaction processing

ORB object request broker

OS/2 Operating System/2

OSF Open Software Foundation

PC personal computer

PIM personal information manager

POP Post Office Protocol

RACF Resource Access Control Facility

RAD rapid application development

RMI remote method invocation

RSA Rivest Shamir Adleman

RUW remote unit of work

SDK software developer's kit

SET secure electronic transaction

SMP symmetric multiprocessors

SMTP Simple Mail Transfer Protocol

SNA Systems Network Architecture

SNMP Simple Network Management Protocol

SMTP Simple Mail Transfer Protocol

SQL structured query language

SSL secure sockets layer


TCP/IP Transmission Control Protocol/Internet Protocol

UDB Universal Database

UDF user-defined function

UDT user-defined data type

UPM User Profile Manager

URL uniform resource locator

WAN wide area network

211

Symbols$$Return 103&Login 157@Command 102@Commands 33@DbColumn

description 58format 110SQL equivalent 109

@DbCommanddescription 58format 112SQL equivalent 109

@DbFunction 57application criteria 77data criteria 79environment criteria 81platforms availability 74user IDs and passwords 113

@DbLookupdescription 58format 111SQL equivalent 109

@DbName 103@Functions 33@Prompt 33@Subset 103[Compose] 102[ToolsRunMacro] 104

Numerics64 KB limit 58

AAbout Database document 101access

and Domino security model 4Author 156, 158controling 155granting and revoking 13No Access 156Reader 156real time 67type 77

access control listSee ACL

ACL 155, 156ActiveX applet 3

activitydefinition 9description 69type 76

ad hoc process 54AddRow method 117administrator

See also NotesPump Administratoragent

accessing DB2 data 65, 132attaching JAVA ressources 90calling a DLL 152Domino feature 4in Java 36, 65scheduling 65, 92

AIXand DataJoiner 22and DB2 11, 21, 45and DB2 CAE 23, 45and DB2 Connect 23, 45and Domino 1, 44and Lotus Notes client 2, 44tools availability 73

alias 85Allow anonymous connections option 156AMgr_DocUpdateAgentMinInterval 92AMgr_DocUpdateEventDelay 92anonymous 156APPC 24AppendChunk method 122applet

accessing DB2 data 65, 132and Domino 35, 65and Lotus BeanMachine for Java 5DB2 JDBC driver

See DB2 applet JDBC driverHTML parameter 30in a Notes document 3Java definition 30using JDBC 67

AppleTalk 46application

and DBMS replication 25criteria 74DB2 JDBC driver

See DB2 application JDBC driverdevelopment with Domino 29in a Lotus Notes database 5in the ODBC architecture 38

213

Java definition 31management, directory information 3mode 53model 76process and DB2 13synchronization 4template 32using CLI 40using JDBC 67

application requesterSee AR

application serverSee AS

Approach 33AR 19, 88archive 55AS 19ASCII 18attachment, file 3authentication

mapping between environments 158user 4, 155

Authoraccess 156, 158field 158

authority 86authorization failure message 156autocommit 63automatic memory management 136availability

DBMS replication 25of Domino and DB2 160of the tools 73

Bbackup

and recovery 160comparing Domino and DBMS 54in DB2 14using DBMS replication 25

BASIC 33batch 77BEGIN DECLARE SECTION SQL statement 153bidirectional scrolling 62binary large object

See BLOBbind command 15, 41, 89BLOB

adding and retrieving with DB2LSX 123and DB2LSX 63CLI support 40DB2 format 52definition 17displaying with DB2LSX 124supported data type 78

book, Name and AddressSee Name and Address book

boot strap data set 87business intelligence 22, 25, 55business logic 54business rules and stored procedure 42button in a Notes form 6

CC, Lotus Notes API 71cached result 62CAE

and DB2 application JDBC driver 41, 67description 22LS:DO process 59operating systems supported 23supported platforms 45supported protocols 47

CafePlus.nsf 84calendaring 4call level interface

See CLIcatalog

command 86, 88stored procedure 129

cc:Mail 4CCD 9, 69certificate 156challenge/response security mechanism 156change, uncommitted 13character

large objectSee CLOB and DBCLOB

translation between EBCDIC and ASCII 18choice list 52CICS 70class

database 34document 34session 34

ClassNotFoundException 90


CLASSPATH environment variable 90, 95, 140CLI

accessing DB2 80and JDBC 41, 66and standards 37binding the utilities to DB2 89compared to ODBC 39, 40DB2LSX 62description 15

click event 34client

configuration assistant 86, 88, 89, 92mail 4thin client 29

client application enablerSee CAE

CLOBadding and retrieving with DB2LSX 123and DB2LSX 63CLI support 40DB2 format 52definition 17supported data type 78

Close method 118CLOSE SQL statement 131, 154code, reuse 32coding with DECS 68column

in a Lotus Notes view 6in a relational table 11

COM.ibm.db2.java.sql 95COM.ibm.db2.jdbc.app.DB2Driver 131COM.ibm.db2.jdbc.net 95COM.ibm.db2.jdbc.net.DB2Driver 131command

activity 9, 69bind 15, 41, 89catalog 86, 88connect 86connect reset 89Initialize Keys 146prep 14, 41

command line processor 86, 88, 89, 92commit

method 63SQL statement 13two phases 24, 39

CommitTransactions method 63communication protocol 46

complex activity 76compound SQL 39computed text 37concurrency, DBMS applications 13configuration of network, directory information 3conflict

in DBMS replication 28in Lotus replication 27

connect command 86, 89Connect method 127CONNECT TO SQL statement 154connection service 85, 87connectivity 43ConnectTo method 115, 121consistency, database 14consistent change data

See CCDcontext 153control

access 4, 155input 53, 70operation 54

coordination 160copied data 76copy, point-in-time 25CREATE FUNCTION SQL statement 17CREATE PROCEDURE SQL statement 129criteria

application 74data 78environment 80

CurrentDatabase 35CurrentRow property 116cursor 130

Ddamage, recovering from 14data

availability 25consistency 13criteria 78DB2LSX access classes 94definition and manipulation statements 12distribution 55flow 76input control 53integration with DataJoiner 22integrity 52, 70, 160

215

numerical 3relational structure 11scope 52semistructured and structured 3, 51structure 53summarizing 55synchronization 69transfer process 75type 3, 52, 76

data sourceaccess with ODBC 39definition 38registering to the ODBC driver manager 92selecting in DECS 144supported by the tools 78

data store 52data warehouse and mart 55database

and Lotus Notes replication 26consistency 14directed DUW 20in DBMS 11in Lotus Notes 5management system

See DBMSNotes class 34parallel technology 22replica ID 26supported by NotesPump 7

DataJoiner 22DataPropagator Relational

See DPROPRdate, Domino and DB2 format 52DB2

adding large object with DB2LSX 122and DB2LSX 63and DECS 67and DRDA 18and LC 64and network environment 53and ODBC 38and unit of work 54backup and recovery 54binding the utilities 89CAE

See CAECLI support 40data type supported by CLI and ODBC 78DataJoiner 22

defining a NotesPump link document 147description 11Domino integration techniques 57family 20features available to ODBC and CLI 39, 40Java support 94JDBC implementations 41large object 52local or remote access from Domino 48NotesPump link 8object extension 15, 55ODBC driver 60registering a stored procedure 185SDK 23server description 21stored procedure

See stored procedurestructures 11supported platforms 45testing the connection from NotesPump 99

DB2 applet JDBC driver 41, 65, 66, 94creating the JDBC driver object 133using with a servlet 137

DB2 application JDBC driver 41, 65, 66, 94creating the JDBC driver object 133using with a servlet 136

DB2 CLISee CLI

DB2 communication protocols 47DB2 Connect

and TCP/IP 24description 23LS:DO process 59packaging 24supported platforms 45supported protocols 47

DB2 ODBC driver 92DB2 Security server 157DB2 UDB

description 21packaging 24

db24918 152db2cli.lst 89DB2Connection 62, 121db2dahlp.nsf 94db2jstrt 95DB2LSX

accessing DB2 data 120adding and retrieving BLOB 123


adding and retrieving CLOB and DBCLOB 123and LS:DO 63application criteria 77classes 120data access classes 94data criteria 79description 62displaying BLOBs 124displaying large objects on the Web 124environment criteria 81error handling 125installation 93large object support 122platform availability 74process 120registering a DB2 database as an ODBC source 63

DB2Query 62, 121DB2ResultSet 62, 121db2samp.nsf 94db2sampl 85db2test 99db2ubind.lst 89dBase 37DBCLOB

adding and retrieving with DB2LSX 123and DB2LSX 63CLI support 40DB2 format 52definition 17supported data type 78

DBMSand Lotus Notes 158and replication 25and security 157JDBC-ODBC bridge 41ODBC manager 39

DBstsSUCCESS 118DCS directory 88DDCS 23ddcs400.lst 90ddcsmvs.lst 90DECLARE C1 CURSOR SQL statement 154DECS

Administrator database 141and NotesPump 68application criteria 77data criteria 79description 67

environment criteria 81installation 91, 97platform availability 74Realtime activity description 68supporting DB2 stored procedure 129

DECS Realtime activity document 143definition statement 12DELETE SQL statement 12, 62DeleteRow method 62, 63, 117DESCRIPTOR 131design

element 6pane 134

digital signature 4, 157Dim 34Direct Transfer activity 9, 69, 148directional scrolling 62directory 3disable caching 146Disconnect method 118, 128Distributed Database Connection Services

See DDCSdistributed environment and LotusScript 35Distributed Relational Database Architecture

See DRDAdistributed unit of work

See DUWdistribution

data 55document 4level of 20

DLL 153document

distribution, routing, and tracking 4in Lotus Notes 5in the Notes object store 3in the NotesPump administrator 8initilization with DECS 146Java applet support 132Notes class 34security level 155

Documentation database 98Documents Have Been Created or Modified option 75Documents Have Been Pasted option 75domain name server

See DNSDomino

and DECS 67

217

and Java 35, 65and JavaScript 36and LC 64and logging 160and LotusScript 33and LS:DO 60and network environment 53and NotesPump 7and security 155and Web server 2application

development 29programming 80

backup and recovery 54cluster 5communication protocols 46compared to a file server 5DB2 integration techniques 57description 1document 3importing the package 133JDBC-ODBC bridge 41local or remote access to DB2 48LotusScript 32messaging service 4Name and Address book

See Name and Address bookprocessing a @DbFunction 58security 4, 155servlet support 96setting 90supported operating systems 1supported platforms 44user account synchronization with Windows NT 4Web development 37Web server task 90

Domino APIapplication criteria 77data criteria 79environment criteria 81platform availability 74

Domino Enterprise Connection ServicesSee DECS

DominoEnableJavaServlets 91do-while clause 33downloading the sample application 84DPROPR 9DPROPR activity 9, 69

DRDAand DB2 Connect 23and TCP/IP 24default port number 87description 18Domino access to DB2 49target database 88

drivermanager 38registering 133, 137transparency 62

DriverManager class 65duplicate entries 61DUW 20, 24, 39, 160dynamic SQL 14, 80

EEBCDIC 18EDA/SQL

and DECS 67and LC 64NotesPump link 8

editor 34element, design 6embedded

objectin a Notes document 3

SQLand DB2LSX 63and ODBC 40static and dynamic 14

encryption 4, 157engine, full-text search 3Enterprise Edition 24, 46, 49enterprise resource planning

See ERPentry, avoiding duplication 61environment

criteria 80network 53variable

CLASSPATH 90, 95SOCKS_NS and SOCKS_SERVER 87

environment variableCLASSPATH 140SOCKS_NS 87SOCKS_SERVER 87

ERP 64


error handlingLC LSX 129with DB2LSX 125with LS:DO 118

eventagent trigger 4click 34QueryOpen 107selection in DECS 145triggering LotusScript program 35WebQueryOpen 103, 107WebQuerySave 104, 105

ExecProcedure method 129Execute method 115, 122executeQuery method 134, 138export 89extension 34external UDF 17EXTMGR_ADDINS 91, 98

Ffailure 160failure, authorization 156Fetch method 127FETCH SQL statement 154field

DECS mapping 144hidden 103, 105in a Notes form 6mapping panel 80replication based on 27security level 155

FieldID method 116FieldInfo method 116Fieldlist method 80FieldName method 116FieldNames method 127FieldSetExpectedDataType method 123FieldSize method 116file

and LC 64attachment 3NotesPump link 8

file server, compared to a Domino server 5file transfer protocol

See FTPFirstRow method 116for...next clause 34

formand Java applet support 132calling a servlet 139in Lotus Notes 6inserting a Java applet 65security level 155

formula language 33for-to clause 33Freelance 33full-text search engine 3function

in Domino 33scalar 17support using ODBC 39user-defined

See UDF

GgetAgentContext method 134GetChunk method 122getConnection method 137getDocumentContext method 134GetError method 118GetErrorMessage method 118GetExtendedErrorMessage method 118getInitParameter method 136GetRowStatus method 117getSQL method 137GetValue method 116GetValueAsFile method 122global variable 107GO_LOAD_AT_STARTUP 96grant, access 13graphic, a Domino object 3GUI and Domino 32

HHasRowChanged method 118hidden field 103, 105HiTest 71hostname 85, 87hotspot 101HP-UX

and DataJoiner 22and DB2 11, 21, 45and DB2 CAE 23, 45and DB2 Connect 23, 45and Domino 1, 44

219

and Lotus Notes client 2, 44tools availability 73

HTMLand Domino 37applet parameter 30applet tag 132authoring in Notes Designer 3generating a page 105

HTTP 140Domino task 90password 156

HttpServletRequest 137HttpServletResponse 137Hypertext Markup Language

See HTMLHypertext Transfer Protocol

See HTTP

IIDE

description 4Java and Lotus Notes Designer 36

identifier, unique 5identity, user 3if New Mail Has Arrived option 75if...else clause 34image 3image restoration 160IMAP4 4IMG tag 124import

a Java file into a Domino agent 134DB2 utility 89the JDBC and Lotus package 133

IMS 70index

in DB2 12of Notes document 3

informationsending and sharing 4synchronization 4

informational application and replication 25init method 136Initialize Keys command 146input

control 53of a user 3parameter 129

validation 61INSERT SQL statement 12, 62integrated development environment

See IDEintegration

Domino and DB2 51in real time 68methods 57

integrity 52, 54, 70, 160IP address 85, 87IsBeginOfData method 116ISDN 46IsEndOfData method 116ISO 37, 40isolation level 54IsResultSetAvailable method 115, 122IsValueAltered method 117IsValueNull method 117

JJava

and Domino 35, 65and IDE 3and LC 64and Lotus Notes Designer for Domino 36applet

See appletapplication 31compiling a program 141DB2 support 94definition 29Domino development language 80interface to Domino object services 36Lotus Domino Toolkit for Java 71Notes classe 65NotesPump Java activity 70servlet

See servletsupporting DB2 stored procedures 129

Java activity 9, 70Java Development Kit

See JDKJava virtual machine

See JVMjava.sql 65, 133javac 141JavaScript 36, 140JavaUserClasses 90


javax.servlet 94, 141javax.servlet.http.HttpServlet 136JDBC

accessing DB2 80application criteria 77creating the driver object 133data criteria 79DB2 applet driver

See DB2 applet JDBC driverDB2 application driver

See DB2 application JDBC driverdescription 41DriverManager class 65dynamic SQL 41environment criteria 81importing the package 133platform availability 74registering the driver 133, 137statement 137

JDBC-ODBC bridge 41, 65creating the JDBC driver object 133using with a servlet 136

JDK 94JSDK 94JVM 29, 30, 31, 36

Kkey

and field mapping 144list 127primary 5, 12public and private 156, 157

keyword list 57, 109

Llanguage

formula 33procedural and SQL 13support with Notes Global Designer 5used in DB2 12

large objectSee BLOB, CLOB, DBCLOB

LastRow method 116LC 64LC LSX

accessing DB2 data 126application criteria 77classes 125

data criteria 79description 64environment criteria 81error handling 129installation 97platform availability 74

LCConnection 125LCCOUNT_UNKNOWN 127LCCurrency 126LCDatetime 126LCField 126LCFieldlist 125LCNumeric 126LCSession 125LCStream 126LCSUCCESS 129LDAP 4LEI

description 69See also NotesPump

Len function 123level of distribution 20Lightweight Directory Access Protocol

See LDAPlimit of 64 KB 58link

defining 147document, ID and password mapping 158NotesPump definition 8

list of keywords 57lnpext.dll 92, 98lnpump 99LocateRow method 62, 116LOCATION 88locator, object 40locking 13, 28, 54log

in DB2 14, 160NotesPump database 98

logic of business 54look and feel 32lookup 57Lotus Approach 15Lotus BeanMachine for Java 5Lotus connection document 141Lotus Domino Connector

See LCLotus Domino Toolkit for Java 1.1 71Lotus Enterprise Integrator for Domino

221

See LEILotus Notes

and DBMS security 158and LotusScript 33class 34database

See databasedefining a NotesPump link document 147description 1formula language 33NotesPump link 8replication 4

Lotus Notes C API 71Lotus Notes C++ API 71Lotus Notes client

and LS:DO 60and replication 27description 2mail client 4security 156supported platforms 44supported protocols 46

Lotus Notes Designer for Domino 2, 3, 36Lotus Notes Desktop 2Lotus Notes Global Designer 5Lotus Notes HiTest C API 71Lotus Notes Mail 2lotus.notes 133LotusScript

and LC 64compared to @DbFunction 58defining the LSX 106description 33Domino development language 32, 80NotesPump Scripted activity 70portability 35program invocation 107supporting DB2 stored procedure 129

LotusScript Data OptionSee LS:DO

LotusScript ExtensionSee LSX

LotusScript Extension Toolkit 71LS:DO

accessing DB2 data 114and DB2LSX 63application criteria 77data criteria 79description 59

environment criteria 81error handling 118platform availability 74process 59, 114

LSX 32, 34LSXDB2 120LSXLC 126LSXODBC 115

MMacintosh OS

and DB2 CAE 45and Lotus Notes client 2, 44

macro 33, 80mail client 4management application, directory information 3manipulation statement 12MAPI 4mapping of key and fields 144mart 55massively parallel processor

See MPPmaximum number of connections 146memo 55memory management with servlets 136message

authorization failure 156transfer agent

See MTAmessaging

application program interfaceSee MAPI

Domino service 4metadata 127method

AddRow 117AppendChunck 122Close 118Commit 63CommitTransactions 63Connect 127ConnectTo 115, 121DeleteRow 62, 63, 117Disconnect 118, 128ExecProcedure 129Execute 115, 122executeQuery 134, 138Fetch 127


FieldID 116FieldInfo 116Fieldlist 80FieldName 116FieldNames 127FieldSetExpectedDataType 123FieldSize 116FirstRow 116getAgentContext 134GetChunk 122getConnection 137getDocumentContext 134GetError 118GetErrorMessage 118GetExtendedErrorMessage 118getInitParameter 136GetRowStatus 117getSQL 137GetValue 116GetValueAsFile 122HasRowChanged 118init 136IsBeginOfData 116IsEndOfData 116IsResultSetAvailable 115, 122IsValueAltered 117IsValueNull 117LastRow 116LocateRow 62, 116NextRow 116NumColumns 116NumRows 116PrevRow 116printContent 138registerDriver 137Rollback 63RollbackTransactions 63Select 127SetParameter 116SetValue 117SetValue AsFile 122Transact 63, 125Update 128UpdateRow 62, 63, 117

Mid$ 34Millennium Cafe Sales Tools Plus

See sample applicationMIME 4mining, data 55

mobile user 53model of application 76monitoring order 146monitoring with DECS 68MPP 21MQEI 71MQI 71MQLSX 71MQSeries 54MQSeries and CICS Connections for Domino

application criteria 77data criteria 79description 70environment criteria 81platforms availability 74

MQSeries Enterprise IntegratorSee MQEI

MQSeries link LotusScript ExtensionSee MQLSX

MTA 4multimedia 52multiple ID security implementation 159Multipurpose Internet Mail Extension

See MIME

NName and Address book 156named pipes 47navigation using view 6ndescext.dll 91NetBEUI 46NetBIOS 46NetWare and Domino 1, 44network

configuration, directory information 3environment 53traffic and stored procedure 42

network protocol 43NextRow method 116nlctest 97No Access 156node directory 86, 88NOI 133NOS 3Notes object interface

See NOINotes object store

See NOS

223

notes.ini 90NotesPump

accessing DB2 data 147and DECS 68application criteria 77data criteria 79databases 98description 7, 69environment criteria 81installation 97link and activity 8Notes ID 158platform availability 74testing the connection to DB2 99

NotesPump AdministratorACL 158description 8installation 98NotesPump component 8

NULL 130number, Domino and DB2 format 52NumColumns method 116numerical data 3NumRows method 116

Oobject

CLI support 40extension in DB2 15, 55in a document 3interface

See also NOIstore 55

See also NOSODBC

accessing DB2 80administration tool 92and @DbFunctions 57and DECS 67and JDBC 41, 66and LC 64and remote data source access 39architecture 38binding the utilities to DB2 89compared to CLI 39, 40description 37Domino process of an @DbFunction 59driver manager 60, 92

driver transparency 62implementation on non-Windows platforms 39loading the CLI DLL 40LS:DO process 59NotesPump link 8registering a data source 92support by CLI 15

ODBC.INI 39ODBCConnection 59, 115ODBCQuery 59, 115ODBCResultSet 59, 62, 115OLAP 22OLTP 70On Event statement 119one-way replication 25online

processing 53online analytical processing

See OLAPonline transaction processing

See OLTPon-the-fly lookup 61open database connectivity

See ODBCOpen Group 18OPEN SQL statement 131, 154OpenDatabase 157OpenDocument 157OpenView 157operation control 54operational

application and replication 25data 76

optimization, query 22option

Allow anonymous connections 156Documents Have Been Created or Modified 75Documents Have Been Pasted 75if New Mail Has Arrived 75SECURITY SOCKS 87Show browser 107

Optional Advanced Services 5Oracle

and DECS 67and LC 64and ODBC 38call interface

See OCINotesPump link 8


orderin relational table 11monitoring 146of a set of columns 12

OS/2and DB2 11, 21, 45and DB2 CAE 23, 45and DB2 Connect 23, 45and Domino 1, 44and Lotus Notes client 2, 44tools availability 73

OS/390and DB2 11, 21, 46and Domino 1, 45Java support 94tools availability 74

OS/400and DB2 11, 22, 46and Domino 1, 44Java support 94tools availability 74

output parameter 129

Ppackage 89packaging 24pane, design 134parallel database technology 22parameter, query 116passing parameters to a stored procedure 129Pass-thru HTML 37password 113, 156, 157, 158performance and ODBC 39permanent, change in DB2 13Person document for Web user 156Personal Edition 24, 46, 49PIM 3ping 85platform

installing a Lotus Notes client or Domino server 44

platform-specific resource 35pointer 12point-in-time 25, 51Polling activity 9, 69, 76POP3 4port number 85, 87portability

and ODBC 39LotusScript 35

Post Office ProtocolSee POP3

preference, user 3prep command 14, 41PREPARE SQL statement 131PrevRow method 116primary key 5, 12, 150Print 105printContent method 138private key 156, 157procedural language and SQL 13process

ad hoc 54event driven 75type of 75workflow 4

processing, online 53programming code in a Notes form 6property

CurrentRow 116ReadOnly 117

protocol for communication 46public key 156

Qqualifier 85query

and LS:DO 61optimization 22products 15with parameters 116

QueryOpen event 107

RRACF 88, 158RDBNAME 88Reader

access 156field 158

ReadOnly property 117real-time

access using DECS 67application model 76integration 68process 75

Realtime Notes activity 9, 148

225

and security 158application criteria 77compared to DECS Realtime activity 68data criteria 79description 69environment features 81installation 92platform availability 74supporting DB2 stored procedure 129

recoverable sequence of operation 13recovery 14, 54, 160referential integrity 52, 160registerDriver method 137registered user 88registering

a DB2 database 92the JDBC driver 133, 137

relation 12remote unit of work

See RUWremote user 53reorg 89replica 26, 160replication

and DBMS 25and Lotus Notes 4, 26, 54definition 25field-based 27NotesPump activity 9, 69, 149

report 55resource 13, 35Resource Access Control Facility

See RACFresult set

and LS:DO 61scrolling 62search 62

result, cached 62reuse of code 32revoke, access 13REXX 15rich text 3, 52, 65Rollback method 63ROLLBACK SQL statement 13RollbackTransactions method 63routing, document 4row in a relational table 11running on dissimilar machines 35RUW 20

Ssample application

About Database document 101description 83downloading 84

SAMPLE database 85scalar function 17schedule

agent 65Domino service 4

scheduled process 75SCO OpenServer and DB2 11, 21SCO UnixWare

and DB2 45and DB2 CAE 45

scope of data 52script library 107Script Vault database 98Scripted activity 9, 70scrolling the result set 62SDK 23search

document 3engine, full-text 3result set 62

secure sockets layerSee SSL

securityand Domino 4and SSL 157and the Web 156directory information 3Domino 155in a Domino environment 155in relational DBMS 11mechanisms 155server, DB2 157using a transaction 70

SECURITY SOCKS option 87Select method 127SELECT SQL statement 12semistructured data 51server

and replication 27and stored procedures 42directory information 3NotesPump engine 7

ServerTask 90, 91servlet


accessing DB2 data 65, 136and Domino 65called from a Domino form 139description 31Domino support 96enabling support 91installation 91

servlet.cnf 96, 136session class 34SetParameter method 116SetValue method 117SetValueAsFile method 122Show browser option 107signature, digital 4, 157simple activity 76Simple Mail Transfer Protocol

See SMTPSINIX

and DB2 11, 21, 45and DB2 CAE 45

SMP 21SMTP 4SNA 23, 46snapshot 25socket 66SOCKS 87SOCKS_NS environment variable 87SOCKS_SERVER environment variable 87SOCKS-enabled 87software developer’s kit

See SDKSolaris

and DB2 11, 21and DB2 CAE 23and DB2 Connect 23and Domino 1, 44and Lotus Notes client 2, 44

sound 3sourced UDF 16SPARC

and DB2 46and DB2 CAE 46and DB2 Connect 46and Domino 1, 44and Lotus Notes client 2, 44tool availability 73

SPX 46SQL

Access Group 37

accessing DB2 80and DB2LSX 63and JDBC 41BEGIN DECLARE SECTION 153CLOSE 131, 154COMMIT 13compound 39CONNECT TO 154CREATE FUNCTION 17CREATE PROCEDURE 129data access 80DECLARE C1 CURSOR 154definition 12DELETE 12, 62dynamic support of JDBC 41embedded 14, 40FETCH 154in an LS:DO process 60INSERT 12, 62JDBC statement 137OPEN 131, 154PREPARE 131ROLLBACK 13SELECT 12static 70supported by ODBC 39UPDATE 12, 62using JDBC 65

SQL Server 38SQL/DS 22SQL0805N 90SQLCA 40SQLDA 130sqleBeginCtx 153sqleEndCtx 154SQLTYPE 130SSL 157statement

On Event 119UseLSX 106, 115, 120, 126

static SQL 14, 70, 80store

See also NOSstored procedure

and @DbCommand 57calling application 129calling from LotusScript or Java agents 129DB2 feature 80description 41

227

developing 130executing in DECS 146ODBC and CLI support 39registering 185

stp4918 129structure

managed by relational DB2 11of data 53

structured data 3structured query language

See SQLsummarized business data 55sun.jdbc.odbc.JdbcOdbcDriver 131Sybase

and DECS 67and LC 64NotesPump link 8

symmetric multiprocessorSee SMP

synchronization 4, 25, 69SYSADM 86SYSCAT.PROCEDURES 185SYSCAT.PROCPARMS 185SYSCTRL 86system directory 86, 88system tables, DB2 11

Ttable

database 5in DB2 12qualifying 85space 12

TCP/IP 24, 46, 66, 85template

application 32document 6

textand LC 64computed 37data type 52in a document 3in a Notes form 6NotesPump link 8

thread 153time

agent trigger 4Domino and DB2 format 52

time stamp 151tool availability 73tracking, document 4Transact method 63, 125transaction 70transparency, ODBC driver 62trigger 4, 75triggering an agent 65two-phase commit 24, 39two-way replication 25type

data in a document 3user-defined

See UDT

UUDF 16, 39, 78UDT 16, 39, 63uncommitted change 13uniform resource locator

See URLunique ID security implementation 159unique identifier 5unit of work 13, 20, 54, 160Universal Database

See DB2 UDBupdate

and LS:DO 62immediate 61SQL statement 12, 62

Update method 128UpdateRow method 62, 63, 117URL 65, 85, 157use statement 106UseLSX statement 106, 115, 120, 126user

account synchronization 4and Windows NT security 157application support 53authentication 4, 155forced to authenticate 157identity, preference, and input 3remote 53

user IDand @DbFunctions 113mapping 158registered 88used to create the SAMPLE database 85


user-defined data typeSee UDT

user-defined functionSee UDF

Vvalidation 61, 70value 12variable global 107video 3view

in DB2 12in Lotus Notes 6security level 155

VINES 46VisualAge for Java 140VM and DB2 22, 46volatility of data 78volume of data 78VSE and DB2 22, 46

Wwarehouse 22, 25, 55Web server

and Domino 2and security 156displaying BLOB 124Domino task 90security 156

Web site 198Web user profile 55WebQueryOpen event 103, 107WebQuerySave event 104, 105Windows 3.1

and DB2 CAE 23, 45and DB2 Connect 23, 45and Lotus Notes client 2, 44

Windows 95and DB2 11, 45and DB2 CAE 23, 45and DB2 Connect 23, 45and Domino 1, 44and Lotus Notes client 2, 44tool availability 73

Windows API 35Windows NT

and DataJoiner 22and DB2 11, 21, 45

and DB2 CAE 23, 45and DB2 Connect 23, 45and Domino 1, 44and Lotus Notes client 2, 44and security 157tool availability 73user account synchronization with Domino 4

Word Pro 33workflow 4Workgroup Edition 24writeback 128

Xx.400 4X.PC 46X/Open 37

229


ITSO Redbook Evaluation

Lotus Solutions for the Enterprise, Volume 2 Using DB2 in a Domino Environment SG24-4918-00

Your feedback is very important to help us maintain the quality of ITSO redbooks. Please complete this questionnaire and return it using one of the following methods:

• Use the online evaluation form found at http://www.redbooks.ibm.com • Fax this form to: USA International Access Code + 1 914 432 8264 • Send your comments in an Internet note to [email protected]

Which of the following best describes you?_ Customer _ Business Partner _ Solution Developer _ IBM employee_ None of the above

Please rate your overall satisfaction with this book using the scale:(1 = very good, 2 = good, 3 = average, 4 = poor, 5 = very poor)

Overall Satisfaction __________

Please answer the following questions:

Was this redbook published in time for your needs? Yes___ No___

If no, please explain:

What other redbooks would you like to see published?

Comments/Suggestions: (THANK YOU FOR YOUR FEEDBACK!)

Pri

nted

in t

he U

.S.A

.S

G24

-491

8-00

Lotus Solutions for the Enterprise, Volume 2 Using DB2 in a Domino Environment SG24-4918-00

lotus solutions for the enterprise, volume 2 using db2 in a

Documents

notes employee form

activity accesses

db2 employee table

notes fieldsare

decs realtime activity

department form

department direct transfer

lotus notes form todb2