Enterprise Integration Using Domino

Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Connect collaborative computing applications to enterprise host systems Install, configure and use Lotus connector products in S/390 Sample code and scenarios provided Mike Ebbers Rudolf Fust John Mims Milan Otajovic Prabhakar Rao ibm.com/redbooks SG24-5682-00 International Technical Support Organization Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products May 2001 Take Note! Before using this information and the product it supports, be sure to read the general information in Appendix F, “Special notices” on page 255. First Edition (May 2001) This edition applies to Release 5.05 of Lotus DominoV5R5 for S/390, Program Number 5655-B86 for use with the IBM OS/390 Version 2 Release 8 Operating System and above. Comments may be addressed to: IBM Corporation, International Technical Support Organization Dept. HYJ Mail Station P099 2455 South Road Poughkeepsie, NY 12601-5400 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. © Copyright International Business Machines Corporation 2001. All rights reserved. Note 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. Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .ix The team that wrote this redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Comments welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Part 1. Introduction to the connector products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Chapter 1. Introduction to enterprise integration on 1.1 Application framework . . . . . . . . . . . . . . . . . . . . . . 1.2 Application integration on S/390 . . . . . . . . . . . . . . . 1.3 Ways of connecting Domino to S/390 applications . S/390 . ...... ...... ...... . . . . . . . . .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 .3 .5 .6 Chapter 2. Configuring Domino Enterprise Connection Services . 2.1 Installing DECS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.1.1 Entries in notes.ini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 Running DECS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3 The administration database . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3.1 The navigator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.3.2 The DECS administrator views . . . . . . . . . . . . . . . . . . . . . . . 2.4 Defining connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.4.1 Creating a connection document using the wizard . . . . . . . . 2.5 Defining activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.5.1 Creating activities with the wizard . . . . . . . . . . . . . . . . . . . . . 2.5.2 Logging of activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.5.3 Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.6 Full text indexing of enterprise data using DECS . . . . . . . . . . . . . . .9 . .9 . 10 . 12 . 13 . 14 . 16 . 17 . 17 . 21 . 21 . 26 . 26 . 26 Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) . . . . . . . . 29 3.1 Lotus Enterprise Integrator installation . . . . . . . . . . . . . . . . . . . . . . . . 29 3.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 3.1.2 Installation requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 3.1.3 Installing the LEI server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 3.2 Running LEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 3.2.1 Running server console commands . . . . . . . . . . . . . . . . . . . . . . 34 3.2.2 LEI administrator commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 3.3 Administering LEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 3.3.1 Using the LEI administrator database . . . . . . . . . . . . . . . . . . . . . 36 3.3.2 LEI server administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 3.4 LEI connection documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 3.4.1 Connectors and supported data sources. . . . . . . . . . . . . . . . . . . 44 3.4.2 MetaConnectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 3.5 LEI activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 © Copyright IBM Corp. 2001 iii 3.5.1 Admin-backup activity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.2 Admin-purge log activity . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.3 Archive activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.4 Command activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.5 Direct transfer activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.6 Polling activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.7 Realtime activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.8 Replication activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.9 Scripted activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.10 Constructing an activity . . . . . . . . . . . . . . . . . . . . . . . . . . 3.5.11 Running activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.6 LC LSX Extensions with LEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.7 Sample: Direct Transfer and Realtime access to relational data . 3.7.1 Construct a DB2 Connector . . . . . . . . . . . . . . . . . . . . . . . . 3.7.2 Construct a Notes connector . . . . . . . . . . . . . . . . . . . . . . . 3.7.3 Construct direct transfer activity . . . . . . . . . . . . . . . . . . . . . 3.7.4 Construct Realtime activity . . . . . . . . . . . . . . . . . . . . . . . . . 3.7.5 Final steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 4. Introduction to programmatic connectors . 4.1 LCLSX LotusScript Extension connectors. . . . . . . . . . 4.1.1 Terms and concepts . . . . . . . . . . . . . . . . . . . . . . 4.1.2 Classes and datatypes . . . . . . . . . . . . . . . . . . . . 4.1.3 Working with LCLSX. . . . . . . . . . . . . . . . . . . . . . 4.2 LS:DO ODBC connectors . . . . . . . . . . . . . . . . . . . . . . 4.2.1 Event handling . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3 MQLSX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.1 What is the MQSeries LotusScript Extension . . . 4.3.2 Class overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4.3.3 MQLSX installation on Domino for S/390 . . . . . . 4.3.4 Installing MQLSX code for a development client . 4.4 Lotus C/C++ API connectors . . . . . . . . . . . . . . . . . . . 4.4.1 Writing your own connector code . . . . . . . . . . . . 4.4.2 The Notes C/C++ API . . . . . . . . . . . . . . . . . . . . . 4.4.3 Notes application . . . . . . . . . . . . . . . . . . . . . . . . 4.4.4 C or C++ program. . . . . . . . . . . . . . . . . . . . . . . . 4.4.5 Production environment . . . . . . . . . . . . . . . . . . . 4.4.6 Test environment . . . . . . . . . . . . . . . . . . . . . . . . 4.4.7 Other applications accessing Notes . . . . . . . . . . 4.5 Integrating relational databases using @functions . . . 4.6 How to use @DB functions . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 . 48 . 48 . 48 . 49 . 49 . 50 . 51 . 53 . 53 . 61 . 62 . 63 . 63 . 64 . 64 . 65 . 66 . 67 . 67 . 67 . 69 . 71 . 71 . 72 . 72 . 74 . 74 . 77 . 82 . 82 . 83 . 84 . 84 . 85 . 86 . 86 . 87 . 89 . 90 iv Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Part 2. Working with DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Chapter 5. Setting up DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 5.1 Preparing the environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 5.2 Verifying ODBC function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Chapter 6. Connecting to DB2 with DECS . . . . . . . . . . . . . . . . . . 6.1 Preparing DB2 to connect with DECS. . . . . . . . . . . . . . . . . . . . . 6.1.1 Creating the view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.1.2 The Domino sample application to communicate with DB2 . 6.2 Integrating DB2 using DECS . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.1 Description of employee sync scenario . . . . . . . . . . . . . . . . 6.2.2 DECS setup using a table. . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.3 DECS setup using a view . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2.4 Results of scenario Employee Sync . . . . . . . . . . . . . . . . . . Chapter 7. Connecting to DB2 with LEI . . . . . . . . . 7.1 Command activity . . . . . . . . . . . . . . . . . . . . . . . . . 7.1.1 What this activity is used for . . . . . . . . . . . . . 7.1.2 Example scenario . . . . . . . . . . . . . . . . . . . . . 7.1.3 How we set up LEI for this scenario . . . . . . . 7.1.4 Parameter options set for this activity . . . . . . 7.2 Direct transfer activity. . . . . . . . . . . . . . . . . . . . . . 7.2.1 What this activity is used for . . . . . . . . . . . . . 7.2.2 Example scenario . . . . . . . . . . . . . . . . . . . . . 7.2.3 How we set up LEI for this scenario . . . . . . . 7.2.4 Parameter options selected for this activity . . 7.3 Archive activity . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.3.1 What this activity is used for . . . . . . . . . . . . . 7.3.2 Example scenario . . . . . . . . . . . . . . . . . . . . . 7.3.3 How we set up LEI for this activity . . . . . . . . 7.3.4 Parameter options selected for this activity. . 7.4 Replication activity . . . . . . . . . . . . . . . . . . . . . . . . 7.4.1 What this activity is used for . . . . . . . . . . . . . 7.4.2 Example scenario . . . . . . . . . . . . . . . . . . . . . 7.4.3 How we set up LEI for this activity . . . . . . . . 7.4.4 Parameter options selected for this activity. . 7.5 Polling activity . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.5.1 What this activity is used for . . . . . . . . . . . . . 7.5.2 Example scenario . . . . . . . . . . . . . . . . . . . . . 7.5.3 How we set up LEI for this scenario . . . . . . . 7.5.4 Parameter options selected for this activity. . 7.6 Realtime activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 . . 97 . . 97 . . 98 . . 99 . . 99 . 100 . 102 . 104 . . . . . 109 . . . . . 110 . . . . . 110 . . . . . 110 . . . . . 110 . . . . . 115 . . . . . 117 . . . . . 117 . . . . . 118 . . . . . 118 . . . . . 125 . . . . . 126 . . . . . 126 . . . . . 126 . . . . . 126 . . . . . 130 . . . . . 130 . . . . . 130 . . . . . 130 . . . . . 131 . . . . . 138 . . . . . 139 . . . . . 139 . . . . . 139 . . . . . 139 . . . . . 144 . . . . . 145 v Chapter 8. Accessing DB2 with programmatic connectors . . . . . 8.1 Running LotusScript agents on the Domino server . . . . . . . . . . . 8.1.1 Configuring Domino for multi-threading. . . . . . . . . . . . . . . . 8.1.2 Agent Manager debugging and logging information . . . . . . 8.1.3 LotusScript on the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2 Integrating DB2 using LCLSX programming . . . . . . . . . . . . . . . . 8.2.1 Business scenario: online employee retrieval . . . . . . . . . . . 8.2.2 Fetching data from DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2.3 Code enhancements in the sample employee application . . 8.2.4 Updating and inserting data in DB2 . . . . . . . . . . . . . . . . . . 8.2.5 Code enhancements in the sample application . . . . . . . . . . 8.2.6 Deleting rows in the DB2 table . . . . . . . . . . . . . . . . . . . . . . 8.2.7 Code enhancements in the sample application . . . . . . . . . . 8.2.8 Stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2.9 Performance enhancement using connection pooling . . . . . 8.3 Integrating DB2 using LS:DO programming . . . . . . . . . . . . . . . . 8.3.1 The online employee retrieval scenario using LS:DO . . . . . 8.3.2 Stepping through the agent LS:DO Fetch Emps code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 . 147 . 147 . 148 . 149 . 150 . 150 . 151 . 152 . 156 . 157 . 160 . 161 . 162 . 162 . 164 . 164 . 165 Part 3. Working with MQSeries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Chapter 9. Setting up MQSeries . . . . . 9.1 MQSeries for OS/390 setup . . . . . . . 9.1.1 Message queue manager . . . . . 9.1.2 Message queues . . . . . . . . . . . 9.1.3 MQSeries processes . . . . . . . . 9.1.4 MQSeries-CICS bridge . . . . . . . 9.1.5 Other MQSeries considerations . . . . . . . . . . . . . . .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 . . . . . . 169 . . . . . . 169 . . . . . . 170 . . . . . . 171 . . . . . . 171 . . . . . . 172 . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 . 173 . 175 . 176 . 176 . 183 . 183 . 183 . 184 . 184 . 184 . 185 . 185 Chapter 10. Connecting with MQSeries including CICS . 10.1 CICS connection scenario: order account management 10.2 Examining the code of our sample application . . . . . . . 10.2.1 The transactional CICS application . . . . . . . . . . . . 10.2.2 The Domino application using MQLSX . . . . . . . . . Chapter 11. Building an enterprise application 11.1 The three models of connector techniques . . 11.1.1 The DECS model . . . . . . . . . . . . . . . . . 11.1.2 The LEI model . . . . . . . . . . . . . . . . . . . 11.1.3 The programmatic connector model . . . 11.2 Solution architecture considerations . . . . . . . 11.2.1 Existing enterprise data . . . . . . . . . . . . 11.2.2 Size of master database . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. vi Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products 11.2.3 Updating or reading of enterprise data . . . . . . . . . . . . . . . . . 11.2.4 Redundant data or direct enterprise access . . . . . . . . . . . . . 11.3 Considerations when updating data . . . . . . . . . . . . . . . . . . . . . . . 11.3.1 Comparison of the two different data management concepts 11.3.2 Considerations when updating enterprise data . . . . . . . . . . . 11.3.3 Transactional considerations . . . . . . . . . . . . . . . . . . . . . . . . 11.4 Performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.4.1 Mapping complex relational models to Notes Databases . . . . 186 . 187 . 189 . 189 . 190 . 191 . 193 . 193 Appendix A. DECS activity options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 A.1 General options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 A.2 Create event options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 A.3 Open event options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 A.4 Update event options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 A.5 Delete event options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 Appendix B. LC LSX class properties and methods . . . . . . . . . . . . . . 209 B.1 LCSession. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 B.2 LCConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 B.3 LCFieldlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 B.4 LCField . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 B.5 LCStream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 11.5 LCNumeric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 11.6 LCCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 11.7 LCDatetime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Appendix C. Sample LotusScript agent code . . . . . . . . . . . . . . . . . . . . 221 C.1 LCLSX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 C.1.1 Code of Fetch Employee keyed agent . . . . . . . . . . . . . . . . . . . . . . 221 C.1.2 Code of Update/Insert Emp agent . . . . . . . . . . . . . . . . . . . . . . . . . 222 C.1.3 Code of the delete row agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 C.2 LS:DO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 C.2.1 The LS:DO Fetch Emps agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 C.3 MQLSX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 C.3.1 The WebMQPutOrder agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 C.3.2 The MQGetOrderStatus agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 Appendix D. Sample MQSeries-CICS source code . . . . . . . . . . . . . . . . 233 D.1 BMS map sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 D.2 C source code for CICS/MQSeries programs. . . . . . . . . . . . . . . . . . . . . 236 vii Appendix E. Workaround for manual field mapping in DECS . . . . . . . 253 Appendix F. Special notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Appendix G. Related publications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 G.1 IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 G.2 IBM Redbooks collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 G.3 Other resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 G.4 Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 IBM Redbooks fax order form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 IBM Redbooks review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 viii Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Preface The robustness and scalability of the S/390, teamed with the collaboration tools of Lotus Domino, makes a powerful combination. To increase the business power of a S/390 Domino environment, you can integrate the data and applications on your S/390 with the collaborative application environment of the Domino system. This IBM Redbook tells you how to connect collaborative computing applications to enterprise host systems. We give a detailed description of the Lotus connector products available on the S/390, including installation and configuration. We provide sample code that reads, updates, and deletes enterprise data from DB2. In addition we show how to interface to CICS using MQSeries on the host, without needing client code on each workstation. This redbook will help system architects, database administrators, and Notes developers to integrate S/390 data and applications with Domino applications in a S/390 environment. The book is divided into different sections. Part 1 introduces the connector products and gives detailed information about their installation and configuration. Part 2 covers DB2 connectors, and Part 3 covers MQSeries. In these parts, we describe how to set up the host system so Domino can connect to it, and we provide sample scenarios. 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 Poughkeepsie Center. Mike Ebbers is a senior IT specialist at the International Technical Support Organization, Poughkeepsie Center. He writes extensively and teaches IBM classes worldwide on all areas of Domino on S/390. Before joining the ITSO six years ago, Mike worked for 10 years in the field in IBM/US, and for 11 years as an instructor/developer. Rudolf Fust is an IT Specialist in IBM Global Services, Germany. He studied Computer Sciences at the University of Hamburg. He has over five years of experience in Domino Application Development and Administration. He is a certified Lotus Professional at the Principal level in Domino R4 and R5. He gained practical experience in several large Application Development projects © Copyright IBM Corp. 2001 ix at customer accounts. His areas of expertise include DB2, DECS, LEI, and Lotus connectors. John Mims is an IBM Senior I/T Specialist, currently living in Austin, Texas. He has been with IBM for 12 years, and in the Information Technology business since 1980. His areas of expertise include Application Development, Systems Programming, and Consulting on the IBM S/390, specializing in Domino for S/390 enterprise integration. He is one of the authors of an earlier IBM Redbook on integrating Domino for S/390 with enterprise data systems. Milan Otajovic is a Sales Specialist in IBM Slovakia. He has 12 years of experience in S/390, MVS and OS/390. He has worked at IBM for six years. His areas of expertise include MVS System Programming, DB2 Administration and Application Programming, CICS Applications Programming, and Lotus Domino. Prabhakar Rao is a Technical Manager in IBM Global Services, India. He has more than seven years of experience in Information Technology and presently works in IBMGAD with the S/390 Competency Center. He has been with IBM since 1997. He holds a Masters degree in Computer Engineering from Victoria Jubilee Technical Institute, University of Bombay. His areas of expertise include DB2, MVS, and RACF. He worked as a DB2 DBA, and taught DB2 for OS/390 Systems Administration and Database Administration courses to IBM business partners. Thanks to the following people for their invaluable contributions to this project: Rich Conway Robert Haimowitz International Technical Support Organization, Poughkeepsie Center Clark Goodrich IBM Poughkeepsie Sandy Kark IBM Poughkeepsie Ojan Majlessi Lotus Development Corporation, Westford Mary Peterson Lotus Development Corporation Product Manager, Cambridge Bill Ruby IBM Poughkeepsie x Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Chuck Smith Lotus Development Corporation, Austin Robert Sung Domino Development, Westford 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 “IBM Redbooks review” on page 279 to the fax number shown on the form. • Use the online evaluation form found at ibm.com/redbooks • Send your comments in an Internet note to redbook@us.ibm.com xi xii Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Part 1. Introduction to the connector products © Copyright IBM Corp. 2001 1 2 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Chapter 1. Introduction to enterprise integration on S/390 The System/390 platform is a de facto standard for enterprise computing. It is used in many major companies, across all industries and around the globe, running many mission-critical applications. These applications are written in different ways. Some have proprietary technology, developed in particular companies to meet their specific needs. Other use standard middleware, such as database subsystems, application servers, and security infrastructure, that has been available for many years from IBM and other software vendors. Today’s competitive global environment allows less time for development, and requires faster implementation and transformation of business processes. The System/390 has been established in large companies for a long time. Non-S/390 office application systems with collaboration features have been developed independently of the S/390 transactional legacy systems. This lack of integration adds time-consuming complexity to everyday business processes. Because of this, there is a demand for business application solutions which are simple, versatile, and easily implemented. Sometimes we try to use what we already have, by building new functionality around older systems. This can become very complex. 1.1 Application framework To keep things organized, IBM has provided building blocks consisting of application middleware. Figure 1 on page 4 shows an example of an application framework. Other systems can be placed into the framework, such as CICS Transaction Server and IMS. A typical user of S/390 systems runs many different subsystems and applications, such as ERP, data warehouse, or online ordering applications. S/390 offers the capability of running different workloads in a single system, or in a cluster of systems (known as a Parallel Sysplex). OS/390 has the capability to run both native MVS and native UNIX applications. This provides an easy way of integrating mission-critical legacy applications with applications originally developed for distributed environments. Domino running on OS/390 is a good example of this. Lotus Domino provides a true cross-platform application environment. It is © Copyright IBM Corp. 2001 3 accessible from native Notes clients and Web browsers through different networks, yet still maintains the same behavior for end users. IBM MQSeries Connect applications Speed application deployment and integration Manage and integrate business process flow across more than 35 application environments Lotus Domino Rapidly develop and deploy collaborative applications Advanced capabilities for managing work and information flow Integration with database, ERP and transaction systems IBM W ebSphere Speed transition from publishing to Web-based transactions For transaction intensive environments Support for distributed business components DB2 Universal Database Best performing database Handles multimedia as w ell as conventional data Optimized for Web applications Delivers enterprise class reliability and availability Figure 1. Application framework The creators of Lotus Notes initially introduced it as a decentralized midware platform to distribute data and application functions in heterogeneous environments. These were distributed PC LANs with midsize servers and low bandwidths. Later, as the Domino server was introduced into large companies with several thousand end users, the number of servers increased and administration became complex. The need for more powerful servers was clear. Domino has been available on the S/390 platform for the past four years. This provides the ability to support thousands of users from a single point of administration.The reliability and scalability of the S/390 in combination with the collaboration tools of Lotus Domino is an exciting dimension of workgroup computing. Many companies who run Domino on the S/390 begin with these features: • Mailing • Calendaring and scheduling • Discussion databases 4 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Then they develop or migrate Notes applications onto the S/390, such as: • Knowledge management • Web applications • Workflow applications The next level brings business power to a Domino environment by integrating the data and applications on the S/390 with the collaborative desktop user interface of the Domino System. 1.2 Application integration on S/390 A Domino server on OS/390 server can coexist with Domino servers on different platforms. It can play a key role in integration between traditional green screen 3270 applications and new Web-based asynchronous collaborative applications; see Figure 2. E n t e r p r is e S e rv e r In v e n to r y M anagem ent A c c o u n ts P a y a b le B illin g O rd e r P r o c e s s in g S u p p o rt C u s to m e r S e r v ic e M a r k e tin g S a le s W o rk g ro u p S e rv e r Figure 2. Integration of group and enterprise server data Besides Domino, other ways exist to make enterprise data accessible to end users. The IBM WebSphere Application Server is a good choice if your company requires only Web access. Net.Data provides simple HTTP access to data stored in DB2 database. However, if your environment consists of office systems, electronic mail, ERP applications, or online transactional applications, Domino may be the best integration platform. Domino offers you these features: • It runs on a variety of server platforms. • It is accessible by multiple clients, including native Notes and Web browsers. Chapter 1. Introduction to enterprise integration on S/390 5 • It provides access to various data sources. • It integrates with office applications such as Lotus SmartSuite and Microsoft Office. • It enables collaboration. • It provides knowledge management. • It can be used for e-mail. • It can be used for calendaring. • It can be used for scheduling. • It is easy to use and provides a consistent user interface. • It can use simple programming methods or advanced programming techniques. • It provides cross-platform portability of applications. • It has strong security. • It provides reliability. • It provides a single point of administration. • It has many resources available from Lotus, IBM, and other companies This redbook is intended to help system architects, database administrators, and Notes developers to integrate S/390 data and applications with Domino applications. We describe the Lotus connector products available on the S/390. We document the installation and configuration, and give guidance on when to use each tool. 1.3 Ways of connecting Domino to S/390 applications The tools we use to connect Domino server for S/390 to other applications are called connectors. They fall into two categories: programmatic (which require code) and non-programmatic. Non-programmatic connectors include Domino Enterprise Connection Services (DECS) and Lotus Enterprise Integrator (LEI). Programmatic connectors include LotusScript Extension for Lotus Connector (LCLSX), and MQSeries LotusScript Extensions (MQLSX). Figure 3 on page 7 shows the connector categories: 6 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products L o tu s D o m in o P r o g r a m m a tria m m a t i c A c c e s s P rog c L o tu s S c r ip t LC L SX JD B C LSX N o n - P r o g r a m m -aP ic g r a m m a t i c N o n t ro Jav a L C Java DECS DECS LEI L o t u s D o m in o C o n n e c t o r s E R P A p p ls SAP P e o p le S o ft J .D . E d w a rd s O r a c le s A p p s R e la tio n a l D B s DB2 O ra c le Sybase S Q L S e rv e r F la t D a ta D o m i n o O b je c t s F i le S y s t e m Te x t S y s te m T x S y s te m s M Q S e rie s C IC S IM S B E A Tu x e d o Figure 3. Domino enterprise connectors A native Notes client does not know anything about other data sources such as DB2. In order to talk to servers other than Domino, it needs a connector. This connector can be either on the client workstation or on the system where Domino server runs. For Web clients, the connector must be on the server. Figure 4 shows this architecture: Notes Connector Client network DB2 network Domino Connector Figure 4. Lotus connector models Chapter 1. Introduction to enterprise integration on S/390 7 This redbook covers the cases where each connector runs on the server system. We show how clients (Web-based and native Notes) can access Domino databases and their applications, and then integrate with existing business data and logic in back-end application systems on S/390. We create sample applications to show how things work, based on standard IBM-supplied samples for a particular subsystem. 8 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Chapter 2. Configuring Domino Enterprise Connection Services Domino Enterprise Connection Services (DECS) was added to Domino for S/390 in Release 5. Running as a Domino server task, it provides real-time access to external enterprise data. DECS administration is visually mapped (forms-based) for easy setup. Anyone familiar with Lotus NotesPump (now called Lotus Enterprise Integrator or LEI) will recognize this interface and easily adapt to its features. DECS captures Domino document events and performs the functions you set up within the DECS administration database. DECS provides a service similar to Lotus Enterprise Integrator’s real-time activity. It runs in much the same way, capturing Domino document events and performing the functions you set up within the DECS administration database. 2.1 Installing DECS While installing your Domino server, you must choose the Enterprise Domino server in order to install the files needed for DECS. During the configuration of the Domino server, in the Server Audience Screen, place a checkmark beside DECS, as shown in Figure 5 on page 10. Important We recommend that you use DECS for real-time functions, rather than LEI. In that situation, the realtime options should be removed from the LEI command file to avoid two Extension Managers being active at one time. Refer to Lotus Domino for S/390 Release 5: Installation, Customization and Administration for detailed information on installing and configuring Domino in a S/390 environment. © Copyright IBM Corp. 2001 9 Figure 5. Selecting DECS during configuration of the Domino server 2.1.1 Entries in notes.ini Two entries are automatically inserted into the notes.ini file, which is located in the /notesdata directory. The notes.ini file can be edited by using the OMVS ASCII Editor OEDITASCII which is (in our installation) located in the path: /usr/lpp/lotus/notes/5041/os390. A package called viascii can also be used in the shell to help with editing notes.ini and lei.ini. Note: A direct edit of the notes.ini file is risky, so make a backup copy first. 1. In the Servertasks entry, the DECS task is added like this: ServerTasks=Router,Replica,Update,Amgr,AdminP,CalConn,Sched,Event,Stats ,HTTP,DECS,maps 10 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products 2. The following line is also added, indicating that the decsext executable is loaded for the Domino extension manager. The extension manager handles the Domino events, some of which are used by the DECS executable. EXTMGR_ADDINS=decsext With these two entries, DECS is fully operational on the Domino for S/390 system. DECSEXT is the realtime portion of DECS. You must load DECSEXT at time of server startup, in order to have DECS load successfully. In addition, the following notes.ini entries can be added to help control DECS: 1. DECSTranslation All text data in a Domino database contains a reference to its character set. This is determined automatically by the connector when the data is fetched from a database. If the data is inserted into a database with a different character set, DECS automatically translates the text data just before storing it. This process maintains maximum performance by eliminating any unnecessary translation. Performance may be further enhanced through DECS three levels of translation support: no translation, LMBCS only, or full translation. The three available settings are: DECSTranslation=0 This setting will not translate data (except unicode). This setting can be used if all the connectors are compatible with the Lotus Multi-Byte Character Set (LMBCS), that is, ASCII characters. DECSTranslation=1 This setting is useful when all of the connectors being accessed use compatible, non-LMBCS, character sets. DECSTranslation=2 This setting is the default in Domino on S390. All data will be translated no matter what the character sets are. Important Do not use the DECSTranslation parameter if you are not sure which connectors you will be using. The default setting is the right choice. 2. DECSNativeText This entry allows your Domino server’s native character set to be overridden. The default setting, which is not required as an entry, is: DECSNativeText=Native Chapter 2. Configuring Domino Enterprise Connection Services 11 The “Character Sets” appendix specifies the character set as used within the Lotus connectors LotusScript extension (LSX). To apply these settings for DECS, remove the LCSTREAMFMT_ prefix. 3. DECSCenturyBoundary: This entry allows you to control how the year in a text string is converted to a Domino datetime field when the year contains only two digits. Values greater than or equal to the century boundary are considered to be in 1900s, while values less than that are in the 2000s. There are three ways to set this: DECSCenturyBoundary=0 This setting will always use “19” as the century number since all two-digit years are greater than zero. DECSCenturyBoundary=50 “50” is used as an example in this case. If the value is in the range of one to 100, the following rule applies: The century number is “19” if the two-digit year is greater than or equal to the century boundary; otherwise use “20” (for the year 2000). The default value for the century boundary is “50.” This entry is not required in the notes.ini file if the default value is desired. DECSCenturyBoundary=101 This value forces all dates with a century number of “20” (for the year 2000). 2.2 Running DECS Domino Enterprise Connection Services (DECS) begins running as you bring up the Domino task. The Domino console in Figure 6 on page 13 shows a list of tasks, including the status of the DECS server task, during startup. The DECS task is controlled by parameters in the notes.ini file. The ServerTasks line in the notes.ini file shows all of the tasks that Domino will run on a continuous basis. The DECS task is included on this line. If instead you wish to control the DECS task manually, remove the DECS entry from the ServerTasks line. Then when Domino is started, DECS will not start automatically. You must start DECS manually, until you change the notes.ini file to again include the DECS task. 12 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 6. Server Tasks View showing the DECS task To start the DECS task manually, type the following at your Domino console: LOAD DECS Domino will respond with a task response indicating that the task has started. The first time DECS is started, it will create the DECS Administration Database from the administration template that was included as part of the Domino installation process. To manually stop the DECS task, type the following at your Domino console: TELL DECS QUIT Domino will respond indicating that the task has shut down. Note: DECS can also be started from a program document in the Domino Directory. 2.3 The administration database Before you can use DECS in a Domino application, you need to set up DECS for that application. To do this: 1. Create a connection to the external data store, if it is not already defined. Chapter 2. Configuring Domino Enterprise Connection Services 13 2. Create an activity document that specifies: - Which documents in which database to monitor - Which events to monitor - Which fields are key fields externally and in Domino - How external fields or records map to fields in Domino 3. Initialize keys. You need to put documents in your Domino database with key values for all the records on the external system that you want to work with. In order to have DECS do something, a document event must be triggered. The DECS Administration application has an action called “Initialize Keys” that creates documents in the Domino database with data only in the key field. These documents are called “stub” documents. Note: If you encounter a DECS administrator error This operation is not permitted when executing restricted agents, then have the administrator sign the decsadm.nsf database. This should fix the problem. 4. Finally, start the activity to begin monitoring the documents in the Domino database. In 2.4, we explain how to set up connections and activities using a wizard interface to the DECS Administration database. Online help is available. Note: Data source connectivity testing is available for the DECS relational connectors. You can run the program LCTEST from a command line (OMVS or telnet) to confirm connectivity with your data source; see 3.4.1.1, “Testing connectors” on page 44. Supported data sources for real-time DECS connections on S/390 are: • DB2 • MQSeries (under development) 2.3.1 The navigator The DECS administration database navigator has an easy interface for creating your data source connections and activities. Figure 7 on page 15 shows the navigator along with sample activities. The following list will help you identify each region of the navigator: • Click Connections on the views box in the navigator to see a view of available connections. 14 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Note Currently, DB2 and File Connectors are the only supported connectors for DECS in the S/390 environment. The wizard may allow other documents to be created, but they will not work. Figure 7. The DECS connection to a DB2 database • Click Activities in the Views box to see a view of real-time activities. • Click Create Connections to create a new connection document for an external data source. This launches a wizard that prompts you through the process. The small blue 1 indicates that the wizard is active. You turn the wizard on or off through User Assistant, as explained below. • Click Create Activity to create a new real-time activity. When the wizard is active (indicated by the blue 2), you are prompted through the process of defining a real-time activity between your Domino application and your external data source. With the wizard area turned off, you are presented with a blank real-time activity document that you can edit directly. Chapter 2. Configuring Domino Enterprise Connection Services 15 • Click Start to begin monitoring the documents specified in your currently selected real-time activity. This has no effect if your current selection is already started. The Start button is disabled when in the connection view. • Click Log to see the status of the currently selected real-time activity. If the current selection is running, you will see the start time and other current status information. If the current selection is not running, you will see the results of the most recent run. The Log button is disabled when you are in the Connections view. • Click Stop to end your currently selected real-time activity. This has no effect if the current selection is not running. The Stop button is disabled when you are in the Connections view. • Click User Assistant to switch the User Assistant on or off. When turned on, this provides additional help and enables the DECS wizard. This is useful if you are a first-time user. The DECS wizard guides you through creating the real-time activity document and provides you with information to help in the creation and editing of the document. • Click Intro to view the DECS administrator database Using document. • Click Doc to display the DECS online user guide. • Click Exit to close your DECS administration database. 2.3.2 The DECS administrator views Now we discuss the database views that the administrator has available. 2.3.2.1 The connections view All connection documents can be seen on the Connections view. These documents are named by DECS using a combination of external data source type, database name and the table name. As shown in Figure 7 on page 15, you will also see any user name associated with accessing the external source. 2.3.2.2 The DECS activities view The DECS Activities view provides you with a graphical approach to activity management. The Activities view displays a list of Domino applications that have been enabled for real-time access (read, write, or both) to an external Lotus Connector system. There are several icons used in this view to show event triggering and activity status. Click Intro on the DECS navigator to get a complete description of the view graphics. 16 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products 2.3.2.3 DECS administrator menu commands Two commands are provided to help you manage your activities. They are shown in Table 1. Table 1. DECS Administrator commands Command Initialize Keys Description Use this command only to initialize a Domino database after a new activity is created. This command will populate your Domino database from the external data source. If you selected that some or all of your real-time fields be kept in the documents (selected from Options -> General -> Data Storage), then those settings will be obeyed during initialization. If you created any filter formulas, you will be prompted for a conditional formula for initialization. This command will restart your selected started activities. Reset Connection 2.4 Defining connections Domino Enterprise Connections Services (DECS) requires connection documents to enable integration with external data sources. These connections use the Lotus Connector architecture (a common set of connectors available to all Lotus integration products). These connection document settings provide the Domino server with valid login information to connect to external data sources. Within the DECS Administration database, you have the option to create connections using the DECS User Assistant. This assistant, called a wizard, can be turned on or off for this process. To use it, there must be a check mark (present by default) in the User Assistant box in the DECS navigator. 2.4.1 Creating a connection document using the wizard The following steps will guide you through the connection document creation process using the DECS wizard: 1. From your Notes R5 client, open your Domino server’s DECS Administration database. 2. With the User Assistant (wizard) turned on, click the Create Connection image shown in Figure 8 on page 18. Chapter 2. Configuring Domino Enterprise Connection Services 17 Figure 8. Create Connection image You will see the connection type selection dialog, shown in Figure 9. However, on System/390, the only supported DECS connections are DB2 and File System, at the time of writing. Figure 9. Choosing the subsystem 3. Select the connection to the external data source that you are using and click OK. In this example we connect to DB2. Note You must establish communication to your external data source prior to creating the connection document. You will be presented with the connection document form shown in Figure 10 on page 19. Fill in the first set of fields. For each field, you can click the caption (blue text) to get more information regarding the input required. The fields in the Connectivity section are: Database: The alias name of the S/390 DB2 subsystem.The value in this field is specified in DSNAOINI (the DB2 CLI initialization dataset). User Name: The user ID you are using to access the external database. Password: The User Name’s password. Click Key to the left if you wish to encrypt the password. You will need an encryption key to do this. 18 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 10. Example of a connection document for a DB2 database Data Journaling: Some database systems keep a journal (or log) of all changes. This is used for recovery reasons, mirroring of changes between systems, keeping remote systems informed about the current value of a data area, usage tracking (billing), and so on. Journaling is required if you run DECS under commitment control (the default setting for all DECS activities). If the DB2 table is not journaled, you must select Data Journaling Off, and you will only be able to read non-journaled data. If the table is journaled, the default access is read/write. If you leave this option on yet cannot write data, check to see if your external source is journaled. Selection Type: DECS can read data from external database tables or views. If your external data source is defined but not your Domino database, choose Table and develop your Domino database using an external table to Domino form mapping. The same mapping applies if your Domino database is defined but your external data source is not. Choose Chapter 2. Configuring Domino Enterprise Connection Services 19 View: If both the external data source and your Domino database are already defined and their mapping is not table-to-form. Note When using a selection type of View in an activity that updates or creates data, you must include all unique keys of the tables that the view includes in its creation SQL. 4. Click the Owner drop-down button in the Table Selection section of the connection document. You will be prompted to select the table or view owner for this connection; see Figure 11. Figure 11. The metadata by owner selection window The owner is used as a high-level prefix for the table or view names that DECS will be connecting to. Select the owner of the table you will be accessing and click OK, as shown in Figure 12 on page 21. The default owner is “anyone,” which leaves the field blank; the table you access will not be prefixed. This is used for accessing DB2 alias names or names that are unique to the DB2 subsystem. 5. Click the Name drop-down button. You will see a dialog box that displays all the tables or views the selected owner has access to, as shown in Figure 12 on page 21. 20 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 12. Select metadata by name Select the table or view you wish to access with this connection and click OK. The Name field will be filled in with your selection and the Columns field will contain all of the columns defined for that table or view. You can also click Override to type in the table or view name if it is not available in the selection, or if you prefer to bypass the DB2 processing that DECS is performing when displaying the list. 6. Input anything you want into the Comments field. 7. Click Save and Close to save the connection and return to the DECS Administration navigator. 2.5 Defining activities You have created a connection document. You also have a Domino database that will be used to retrieve data from your external data source. Now all you have to do is create the DECS real-time activity document. This section will discuss the two ways to create an activity document: • Using the User Assistant (wizard) • Without the User Assistant (no wizard) 2.5.1 Creating activities with the wizard Follow these steps to create a real-time activity using the DECS wizard: Chapter 2. Configuring Domino Enterprise Connection Services 21 1. From your Notes R5 client, open the DECS administration database on your Domino server. 2. With the User Assistant turned on, click the Create Activity icon. You will be presented with an information box introducing you to the DECS real-time activity wizard. Read the information if you are a first-time user and then click OK. If you require further help, click the ? button in the upper left corner. 3. After you click OK in the dialog box, DECS will connect to your Domino server. Using the Lotus Connector for Notes, DECS retrieves a list of databases currently installed on the Domino server, as shown in Figure 13. Figure 13. DECS database selection window From this list, select the Domino database you want DECS to connect to. The database S390EI/LEITest.nsf will be selected. Clicking the ? gives you further information about this section of the wizard and it also informs you where to modify any wizard settings if the computed settings are incorrect. Click OK when you have selected your database. 4. The wizard proceeds to query the Domino database you selected in the previous step. It will present you with a list of metadata to which you can map. At this level, the metadata that maps to the external data source table or view will be a Domino form, shown in Figure 14 on page 23. 22 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 14. DECS accessing Domino forms Select the form you wish DECS to map to for this activity. Clicking ? will provide further information on how you can modify settings made by the wizard. Click OK when you have selected your form. 5. At this point, the wizard has established the complete Domino connection. Now it will ask you to indicate which external data source connection you wish to use. See Figure 15 on page 24. Chapter 2. Configuring Domino Enterprise Connection Services 23 Figure 15. DECS choosing the connection to the enterprise system Select the external data source connection for this activity. For extra help, click the ? button. This explains this part of the wizard and tells you how you can modify any settings that it makes. If the connector you wish to use has not yet been created, click Cancel to leave this screen, then click New in the Lotus Connection section of the Activity form to create a new connection document. Click OK, after you select your external connection, to proceed to the next step. 6. The wizard proceeds to query both the Domino connection you supplied and the external data source connection to retrieve a list of fields from Domino and the list of columns from the external data source. The dialog box in Figure 16 on page 25 is presented. This dialog box shows the Domino fields on the left and the external data columns on the right. Clicking the ? button will provide you with help in performing the mapping. In general, you must select at least one key on either side, and you must map each Domino field that you select to a column in the external data source. The number of fields and columns mapped must be the same. 24 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 16. DECS mapping Notes form fields to DB2 columns This dialog box is extremely helpful, since it provides you with attribute information on the fields. To continue with the wizard, click OK. 7. You have various degrees of control with the event dialog box. Figure 17. DECS choosing the triggering document event Clicking ? explains that certain events require other events to occur. In particular, the Update event must contain an Open event such that the data to be updated can be retrieved. However, if you select to store keys and fields, the Open is not required for an Update event. Refer to Appendix A, “DECS activity options” on page 195 for further discussion of these topics. Chapter 2. Configuring Domino Enterprise Connection Services 25 Select the events you wish to capture and then click OK to continue with the wizard. 8. The next dialog box presented by the wizard requests the name of the activity. Enter a name that uniquely describes your activity document. Include items like the event types, the Domino database or form (or both), external connection type, and anything else that you feel will separate this activity from the rest. Click ? for further help when naming your activity. Click OK to continue. 9. The wizard presents a dialog box indicating that it has completed its process. The wizard reminds you that there are options that can be configured to uniquely control the activity. The default options are sufficient for the activity to run. Click OK to complete the wizard. 10.The wizard is now complete. You will be presented with the completed activity document. Click Save and Close in the top left corner to exit your activity document. Note A detailed table of DECS activity options can be found in Appendix A, “DECS activity options” on page 195. These include general options, create events, open events, update events, and delete events. 2.5.2 Logging of activities All DECS activities are logged in the Domino server log, or click the View server log. Check the Miscellaneous Events view to see these entries. You can also click View Log at the top right portion of your activity document, or you can click Log navigator in the Activities view. Both of these will retrieve log entries for your activity since it last started. 2.5.3 Scheduling For real-time activities, your scheduling options are fewer than in Lotus Enterprise Integrator (or NotesPump). Since real-time activities always run, they do not need a schedule. However, if your system comes down, during restart you will want your business-critical activities to start automatically. To do this, check the Enabled box in the Scheduling section under Auto Start. 2.6 Full text indexing of enterprise data using DECS Using DECS, you can set up a Domino full text index of the Notes database and all related rows of the table that is connected to the database. 26 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products The full text index is set up like a normal Domino full text index in the database properties window. The only difference is that the DECS activity running on the database must be active. As the index is being built, the content of the table is added. The database is now fully text-searchable from a Notes client or a Web browser. All the data of the connected table is available in the search. The search can be executed even when the connection is not activated. But the values cannot be seen in the document. So you need to have the connection active when using the full text search. For details on Domino full text searching, refer to the Domino Help function. Chapter 2. Configuring Domino Enterprise Connection Services 27 28 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) Lotus Enterprise Integrator (LEI) is a server-based utility application that allows you to transfer data between various sources. Using the LEI server, applications can read and write between supported data sources, and also access this data in real-time. 3.1 Lotus Enterprise Integrator installation In this section we introduce the LEI server, the LEI development client, and the databases that are installed with LEI. We also explain the different options for creating connections and activity documents. Figure 18 shows the LEI architecture. Note: ERP connections are under development on S/390. Figure 18. LEI overview © Copyright IBM Corp. 2001 29 3.1.1 Overview The LEI server runs as a multi-threaded, multi-processing task. It performs the work of transferring data between sources and destinations. It polls the LEI administrator database for instructions which are in the form of activity documents in order to determine what kind of data access or data transfer should be performed and when. 3.1.1.1 LEI development client The LEI development client is a version of the LEI administrator database and a local LEI server subset program that resides on your development workstation (usually an NT platform). The development client enables you to develop, run, and test LEI activities. It provides client product and connector DLLs enabling you to use LEI activity from action buttons for metadata selection and field mapping. It also lets you develop LotusScript agents using LEI classes from Domino Designer for Notes R4.6 or Domino Designer R5.0. 3.1.1.2 LEI databases There are four Domino databases that are created on your Domino server during LEI installation, if specified during setup. Only the log and administrator databases are required. A brief description of each follows. LEI administrator database The LEI administrator database is a Domino application that acts as the control station for all operations performed by an LEI server. It contains forms that define LEI server configuration parameters, connection specifications, and activity details. The administrator database is discussed in detail in 3.3.1, “Using the LEI administrator database” on page 36. LEI log database The LEI log database is a Domino application that logs all LEI server activity. This includes server start and stop times, activities executed, records transferred, as well as any errors specific to an activity. Two LEI activities, admin-backup and admin-purge, are provided for the maintenance of this database. Script vault The script vault is an optional database that can be used to store scripted agents; these can be executed using the scripted activity. It contains an action called Catalog All Agents, available at the View level, which inventories the agents and creates a tracking document for each. This document contains information about each agent, such as name and creator, and allows the user to add additional comments about the agent. Each time Catalog All Agents is pressed, the agent tracking document is updated if required, new agents 30 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products are cataloged, and tracking documents that no longer have associated agents are deleted. We suggest that this database be included in regular backup procedures. LEI documentation database The documentation database contains helpful information about construction of LEI connectors and activities as well as server administration. In addition, if DOC=YES during setup, these nsf databases are copied during install: leidoc, lccon, leiig, and lsxlc. Also, two sample databases (empsamp.nsf and packagetrack.nsf) are delivered with the product, but not placed in the notesdata directory. 3.1.2 Installation requirements This section presents the LEI installation requirements. 3.1.2.1 Server installation requirements LEI is installed on OS/390 as a separate product, whereas DECS is a part of Lotus Domino Server. Installation of LEI on S/390 platform requires the following products: • Domino Server Release 5 • An OS/390 version supported by Domino Server • An enterprise subsystem (at the time of writing, only DB2 is supported) 3.1.2.2 Client installation requirements • Notes client Release 4.5 or above • Although not strictly needed for installation on the host, you may want to install client connectivity software, for example, CAE for DB2 or DB2 Connect. These programs are necessary for getting to the subsystem metadata, if you are working with activities that access it. 3.1.3 Installing the LEI server Lotus Enterprise Integrator for S/390 comes as a UNIX tar file. Upload this file to your OS/390 HFS. The best place for it is in a temporary directory such as /tmp/leiinstall. Then update the environment variables: Notes_ISOLATION (not needed on S/390), Notes_ExecDirectory, LEI_DIR, PATH, and LIBPATH. Read the readme file to get the latest values and recommendations for these variables. We put our variables in our user ID .profile file, but this is not necessary. The following graphic shows our environment. Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 31 /u/ebbers1/.profile Columns 00001 00072 ===> Scroll ===> PAGE ***************************** Top of Data ****************************** export Notes_ISOLATION="TRUE" export Notes_ExecDirectory="/usr/lpp/lotus/notes/latest/os390" export LEI_DIR=/notesdata/leidir export PATH=$PATH:$LEI_DIR:$Notes_ExecDirectory:/notesdata export LIBPATH=$LIBPATH:$LEI_DIR:$Notes_ExecDirectory:/notesdata export STEPLIB=DB2V613G.SDSNEXIT:DSN610.SDSNEXIT:DSN610.SDSNLOAD export DSNAOINI=/etc/odbcini **************************** Bottom of Data **************************** When the environment variables have been set up, exit from the OMVS shell or quit the telnet session. In a new session, log on as a user. Your .profile must be set up correctly and you must have permission to write to the Notes data directory. We used user ebbers1, the owner of /notesdata and /usr/lpp/lotus directories. This user ID runs our Domino server. Issue the command export to display your actual environment setup. Make sure you have valid paths to the LEI target installation directory, and others. Your installation of LEI will fail if you do not set up your environment correctly. Always check the readme file that comes with your version of LEI. Untar the archive file containing LEI for OS/390 from the directory to which you uploaded it. In our case it was: cd /u/ebbers/lei tar -xvf LEI.tar In your installation directory, there will be a number of files. Those will be later distributed to proper directories by the install script. This is the reason that you must have paths and permissions set up correctly. Next, open an ASCII editor to create an LEI install command file. A sample install command file is shipped in the LEI tar file, named command.file. Tailor this file to suit your installation’s needs. We used the file shown in Figure 19 on page 33. 32 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products ===> Scroll ===> PAGE ***************************** Top of Data ****************************** INSTALLCLUSTER LEI=itsolei ADMINSERVER=wtsc52oe ADMINDATABASE=leiadm.nsf DIRECTORY=/notesdata/leidir VAULTDATABASE=leivlt.nsf REALTIME=YES SERVERTASK=YES **************************** Bottom of Data **************************** Figure 19. Sample command.file LEI on S/390 supports INSTALLCLUSTER and INSTALLSERVER installation methods. The LEI statement defines our name for LEI; we chose itsolei. ADMINSERVER refers to the Domino server from which this instance of LEI is administered. The DIRECTORY statement points to a target directory where LEI will be installed. Refer to LEI documentation for a detailed description of install script statements. The next task is to run the install script. You must run it from the directory into which the tar files were extracted. Have the Domino server up but DECS and LEI down. We used this command: setup @itsoinst where itsoinst is the actual name of our LEI install command file. The setup script will ask you two questions: • You are asked on which version of Domino you are installing LEI (our answer was R5) • You are asked to confirm the provided information Then the installation script will run, displaying progress indicators. After the LEI install script finishes, you are prompted to log on as the owner of a Notes executable directory. You can also issue an su to that ID. Run the command: leisetr5 This command will finish the installation of LEI on your OS/390 system. Exit from this Notes ID (or you will affect all processes related to it). Then stop your Domino server. After it is stopped, logon with a non-superuser ID, and enter the command: leiclean Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 33 Then start your Domino server again. 3.2 Running LEI If you have specified ServerTask=YES in your command file during setup, it will be included in the NOTES.INI file as: ServerTasks=...,LEI Therefore, it will start when the Domino server is started. You can type the show tasks command at the Domino Server console to see it running: sh ta The Domino server console will display messages from the LEI server. For example, when running an activity, you will receive messages at start, completion, and any errors. To administer the server, use the administrator database. This is detailed in 3.2.2, “LEI administrator commands” on page 35. 3.2.1 Running server console commands When running LEI as a standalone server, the following server console commands are available. (We show in parentheses a shortcut character that can be typed instead of the full command. If you type the full command, do not include the parentheses.) Note: LEI is not supported as a standalone server on S/390. However, the commands are valid. (H)elp (L)ist Provides command usage information and a brief explanation of the commands available from the server console. Displays a list of activities that are currently being executed, with a number associated with each activity. This number can be used with the Close and Kill commands to terminate a particular activity. (C)lose This is the preferred method to terminate the current activity using the number given by the List command. More than one activity can be terminated at a time, by listing the activity numbers separated by spaces. A request for orderly termination is sent to the activity process, which acts on it following the current database operation by immediately disconnecting from all databases and stopping the specific activities. When an activity is closed, LEI does not consider 34 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products it an error. On the other hand, the activity is not a completed activity, because dependent activities are not executed. (K)ill The Kill command will terminate one or more activities immediately. More than one activity can be killed at a time by listing the activity numbers separated by spaces. Regardless of the current activity state, it will immediately be terminated. The use of this command can leave the system in an unstable state; therefore, this command should be used only when absolutely necessary. (S)tatus Shows the status of the server, including startup information and basic configuration. Shut(D)own Shuts down the server when the last running activity is finished. This prevents the LEI server from starting any new activities and waits for all currently running activities to stop. After all the activities have been shut down, it stops the LEI server program. Note: This is the preferred method of stopping LEI. Sto(P) Stop the server immediately. This command prevents the LEI server from starting any new activities and sends a Close command to all the running activities. After a period of time (specified in the Server Configuration document’s activity Requested Shutdown Timeout field in the Administrator database), any activities which are still running are killed and the LEI server program stops. To use the commands, enter them in the Domino server console using the syntax: tell lei Note: You must enter tell lei p precisely. When it asks if you really want to shut down [n,y, or N], the response must be in the form of tell lei response or the response is not recognized. 3.2.2 LEI administrator commands To administer the LEI server when running as a Domino add-in task, you must use the following LEI commands from within the LEI Administrator: • Close Activity • Kill Activity • Shutdown Server • Stop Server Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 35 3.3 Administering LEI LEI is administered from documents in the Administration database. 3.3.1 Using the LEI administrator database The Administrator database contains the information about the connections and activities. Figure 20 shows the existing activities. The navigator, on the left, allows you to select different views. Figure 20. LEI Administrator showing some of the activities 3.3.1.1 LEI administrator documents There are three types of documents contained in the LEI Administrator database. Activity documents An activity document is the central element and contains instructions for the LEI server. Activity information in the administrator database tells an LEI server what to do, when to do it, and how. LEI can execute several kinds of activities to move and manage data. 36 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Configuration documents Two configuration documents containing LEI server settings are provided during the install process. A third configuration document is available for LEI development clients. These documents cannot be created manually; however, they can be edited to suit your preferences. The administrator configuration document contains the name and location of the log database, LEI help database, and scripted agent database, as specified during LEI install. The server configuration document contains defaults such as poll interval, maximum number of activities, maximum duration of activities, maximum consecutive failures, and activity shutdown request timeout. Configuration choices made during install, such as International Text Translation level, are also located within this document. The client configuration document contains information for any LEI development clients that have been installed referencing the administrator database on this Domino server. Connection documents A connection document holds information that defines a connection to the data servers and databases that LEI must access for transferring data. A single connection document can be shared by many activities.You must provide values for the options shown in Figure 21 on page 38. Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 37 Figure 21. Connection document options 3.3.1.2 LEI navigator The LEI navigator provides buttons for creating connections and activities and view selections for looking at different aspects of your LEI configuration. The menu bar provides access to the actions and views. Figure 22 on page 39 shows the LEI navigator. 38 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 22. LEI navigator Overview The Overview view lists all documents: activity, configuration, and connection documents, along with each document author’s name. Active The Active view displays currently running activities. Connections The Connections view displays, by type, all of the connection documents that have been created on the system. Activities The Activities view displays, by type, all of the activities that have been created on the system. Categories The Categories view displays all of your connectors and activities according to how they have been categorized. Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 39 Create connection The Create Connection selection allows you to create a new connection document. A dialog box appears after you select this option, allowing you to select the type of connection you want to create. The list shows all the connectors that currently are installed with LEI. Create activity The Create Activity selection allows you to create a new activity document. A dialog box appears after you select this option, allowing you to select the type of activity you want to create. See 3.5, “LEI activities” on page 47 for an explanation of the different activities. Start activity Click Start Activity to place the selected activity in the Run ASAP queue. When you select Run ASAP for an activity, it will run the next time the LEI server polls the LEI Administrator for activities to run. You must have selected the activity you want to run before selecting this option. Stop activity Click Stop Activity to stop a currently running activity. You must have selected the activity document before selecting this option. Log view The Log view lists all LEI logs, categorized by type (activity, operation, and server). Log documents are further categorized by server and start date. Help The Help view opens the online version of the LEI documentation. Intro The Intro button accesses an online description of the LEI navigator. 3.3.1.3 LEI administrator menu commands In addition to the standard Notes items found in the menus, the LEI Administrator menus provide specific items in the create menu for working with LEI. They are described in this section. 40 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Activity The Activity submenu provides a list of all LEI activities that can be created. Select the type of activity you want to create from this submenu. Connection The Connection submenu provides a list of all connections that can be created. Select the type of connection you want to create from this submenu. MetaConnection The MetaConnection submenu provides a list of all MetaConnections that can be created. Select the type of MetaConnection you want to create from this submenu. Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 41 3.3.1.4 Activity administration The activity administration submenu provides commands related to activities. A description of these commands follows. Clear browsing cache The Clear Browsing Cache command deletes the cache for the currently selected or open activity. Clear lock The Clear Lock agent clears an activity document’s Lock field and related fields so that the activity can be run again. Close activity This command closes a selected activity that is currently running. Close is the preferred method (over the Kill command) of prematurely terminating a currently running activity. Kill activity This command immediately terminates an activity process. The preferred method of stopping an activity is to use the Close command, which provides an opportunity for the activity to clean up its database connections and log the termination. Set designated server This agent is available from the Action List, and may be used to designate a particular LEI server to run a particular defined activity. The LEI Administrator normally assigns individual activities to be run on LEI servers according to available LEI server processing times.Set Designated Server, when used, overrides the default operations and assigns individual activities to be run on specific LEI servers. For selected activities, the agent synchronizes the 42 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products server ID field, based on the server name in the designated server field in the activity. 3.3.2 LEI server administration The Action/LEI Server Administration submenu provides commands related to the operation of the LEI server. A description of these commands follows. Shutdown server This command terminates the LEI server. This command is preferred over the Stop command for terminating the LEI server because it closes the server down in an orderly fashion. It prevents the LEI server from starting any new activities, waits for all currently running activities to shut down, then stops the LEI server program. However, for a rapid termination of the server, use the Stop command. Stop server This command quickly terminates the LEI server. It prevents the LEI server from starting any new activities and sends a Close command to all currently running activities. After a period of time (specified in the Server Configuration document’s activity Requested Shutdown Timeout field in the Administrator database), any activities which are still running are Killed (see the Kill command) and the LEI server program stops. For an orderly (and safer) shutdown of the server, use the Shutdown command. RunASAP RunASAP causes the currently selected activities to be executed by the LEI server the next time the server polls the LEI Administrator database. 3.4 LEI connection documents LEI requires connection documents to allow integration with external data sources. These connections use the Lotus Connector (LCLSX) architecture, a common set of connectors available to all Lotus integration products. Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 43 A connection document is a defined connection from the LEI server to a specific data source, such as a system database. The connection document provides specific access parameters, such as server names, user IDs, and passwords. Once a connector document to a database has been defined, LEI can access that database for executing activities such as data transfers. Connections are the building blocks for activities, which are discussed in a later section. You should construct at least two connections before starting an activity document. This is because when activities are created, connections must be chosen from the existing set of defined connections. After including the information from a defined connection in an activity, you can override individual values, if needed, for that specific activity. The information required in a connection document may be different for different database products. So the connection documents provide standard Connection Name fields as well as sections and fields specific to the database. Refer to the specific Connection chapters in the LEI online documentation about the type of connection you are creating. If you are using a connector you have purchased separately, refer to the documentation provided with that connector for information. 3.4.1 Connectors and supported data sources LEI 3.0 provides the following standard Lotus connectors for the associated data sources: • DB2 • File • Notes • Text Note: These are the only connectors supported by Lotus Enterprise Integrator for OS/390 at the time of writing. 3.4.1.1 Testing connectors Before creating your connections, you should test connectivity to data sources using command LCTEST. LCTEST is a testing program that uses the native database access method to test the connectivity. To use LCTEST, use the following procedure: 1. From an OS/390 telnet prompt or OMVS shell, type: lctest 2. After selecting the appropriate connector type and if connectivity test is successful, your screen will look similar to Figure 23 on page 45. 44 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 23. Result of LCTEST command 3. Later on, if you receive an error, run LCTEST to verify connectivity for the appropriate data source and connector. 4. If LCTEST runs successfully, return to the connector document and review it for proper user IDs, passwords, and typing errors. 3.4.1.2 Constructing connectors Before creating any connections, you should verify that LEI can communicate with your external database sources by running the data source-specific test, LCTEST, as described in 3.4.1.1. To create a new connection document, follow these steps: 1. Choose Create - Connection. A pulldown menu will appear. 2. Select the database type option from the Notes menu. The connection document will open in edit mode. 3. Enter the required information in the Connection Definition form. Each connector requires different information, depending on the source to which it will be connecting. Refer to the LEI online documentation for details. 4. Once created, these documents can be displayed through the Connection views in the LEI Administrator database. A connection can be used by one or more activities. Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 45 3.4.2 MetaConnectors A MetaConnector is an optional LEI connector. It provides pre-processing operations on connector data prior to transfer within a defined activity form. Once a MetaConnector is created, the MetaConnection document can be found in the views under Connections. 3.4.2.1 Types of metaconnectors There are four MetaConnectors supported by LEI 3.0. They are described in the following sections. Collapse/Expand MetaConnector The Collapse/Expand MetaConnector provides the ability to take multiple records from a data source table and collapse them to a single form field. It also performs the reverse operation, to expand the data into multiple records. Connection Broker MetaConnector The Connection Broker MetaConnector inputs data password information into a Domino application. It is then sent as parameters to the host source application to validate individual user logins to the external system, in order to write data. It can also be used to direct data to and from different connections, based on contact information that is supplied with each row of data. The additional connection properties are specified through extra fields in the field list supplied by the client. The MetaConnector properties allow the client to define the fieldnames that contain the various pieces of contact information. Metering MetaConnector Use the Metering MetaConnector to track data flowing to and from another Connection or MetaConnection. The Metering MetaConnector has no effect on any operations; it simply monitors the volume of data transferred. Results from the metering are logged to a file. The specific information logged is configurable through use of the Metering MetaConnection document. Order MetaConnector The Order MetaConnector is useful when ordering data sets from different server sources. For example, a DB2 table on an AS/400 system and a Domino database on a Domino server may use different order systems when ordering data. This can result in a data set comparison problem when using an LEI replication activity, which requires data sets to be ordered in parallel for data set comparisons. The Order MetaConnector may be applied in this situation to pre-process the data sets to be compared during the activity, ensuring the order pattern will be in parallel for accurate data set comparisons during the replication activity. 46 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products 3.4.2.2 Constructing MetaConnectors Since a MetaConnector will reference an existing connector, make sure you have defined the connector you will be working with before attempting to create a MetaConnector. 1. Choose Create - MetaConnection. A pulldown menu will appear. 2. Select the MetaConnection type from the menu. The MetaConnection document will open in edit mode. 3. Enter the required information in the MetaConnection form. Each MetaConnector requires different information, depending on the type of preprocessing it will be performing. Refer to the LEI online documentation for details. Once created, these documents can be displayed through the Connection views in the LEI Administrator database. 3.5 LEI activities Activity documents contain the information that instructs the LEI server to execute an event, such as a data transfer. Each activity type has a specific Domino form that can be used to create the activity. Each LEI activity is described briefly in this section. For more information, refer to the LEI online documentation. Figure 24 shows the functionality of an activity document. Figure 24. The functions of an activity document Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 47 3.5.1 Admin-backup activity The admin-backup activity creates a backup copy of your LEI Administrator database (LEIADM.NSF), and optionally the Script vault database (LEIVLT.NSF). Use the admin-backup activity when you want to create safe backup of the LEI administrator and associated documents. You should use the admin-backup activity at regular intervals to ensure that you always have backup copies of LEI activities, connections, and configurations that have been created. You can also use the admin-backup activity when your Administrator database becomes cluttered with too many documents. It cleans up the database while keeping backup copies of everything. 3.5.2 Admin-purge log activity Use the LEI admin-purge log activity to purge the LEI log database of documents older than a user-specified number of days. In order to save any logs, you must copy them to another Domino database before running the admin-purge log activity. 3.5.3 Archive activity An archive activity moves data from one database to another, deleting the original records from the source database as they are moved to the destination database. The source data and target location are indicated by metadata name (table, form, and so on). Selection of documents to archive can be done with either a condition or a relative timestamp. Some reasons to use the archive activity are: • To protect data on a regular basis • To archive infrequently accessed data • When migrating from one database to another • To create space on a full disk You can use the archive activity in combination with other LEI activities. For example, you can combine the archive activity with a polling activity. You can then poll your system databases to determine when data was last accessed, and archive it based on a specified date of its last access. 3.5.4 Command activity A command activity executes operating system, database, and SQL commands. 48 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products In order to execute an operating system command, select No Connector and enter the command just as you would at a command prompt. If you want to execute a database-specific or connection-specific command, you must select the appropriate connection document. You should use the command activity when you need to execute a specific command, either on a connected database or on the operating system on which the LEI server is running. For example, you can use the command activity to: • Execute an SQL statement on a supported connection • Execute an operating system command 3.5.5 Direct transfer activity A direct transfer moves data from one database to another. The data to be transferred is identified by a statement; for instance, an SQL query or a selection formula. There are three ways to have a direct transfer activity executed: • Immediate, by clicking RunASAP • Scheduled, using the activity scheduling options • By clicking Start activity in the Navigator You can combine a direct transfer activity with a polling activity to trigger a data transfer when a specified condition is met. 3.5.6 Polling activity Polling is a way of causing an activity (such as a direct transfer or replication) to execute when a condition is met. The polling document itself does not contain the instructions to execute. Instead, it triggers another activity or activities that are configured in separate documents. The polling activity does not re-establish a closed connection to a data source. If you are polling a connection, the connection must remain open as long as necessary relative to the polling interval. For example, if you have configured a database application to time out its connection after 10 minutes of inactivity, but your polling activity has a polling interval set to 15 minutes, the database connection may time out and close before the polling activity checks the connection. The polling activity would fail in this case. You should use the polling activity when you need to execute some action when another action or event occurs. As an example, say the Human Resources department uses a database for employee information. You need Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 49 to maintain this same information in a Domino database so the Engineering, Sales, and Marketing departments can access it. You could use a polling activity to check the database for new or changed records, and when the polling activity detects such an event, it would trigger a replication activity to copy the changed data to the Domino database. Figure 25 shows the details. Figure 25. Polling activity 3.5.7 Realtime activity A realtime activity provides synchronous access from a Domino application to an LEI supported external data source. Note: We recommend that you do not use LEI realtime access. Instead, DECS is the strategic solution for real-time access. The LEI realtime activity intercepts Domino database events and acts on them. When Domino users open, create, update, or delete Domino documents, these events are intercepted and acted upon, obtaining realtime access from the Domino document to enterprise sources supported by the LEI server. Once a system administrator has created the realtime activity, 50 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Domino users can open, create, update or delete enterprise data directly and transparently through their familiar Notes Clients or a Web browser. The Domino document events are intercepted and handled by the LEI server operating on the Domino server that is hosting the Domino application. 3.5.8 Replication activity LEI Replication synchronizes databases by updating one database from the data in another database, where one of the databases is master and the other non-master. In case of a conflict, the master database will win and overwrite the data in the non-master. This is different from Domino replication, where a replication conflict document is created if there is a conflict. Replication involves metadata from two connections (replication is done at the metadata level). There are two types of replication that are available within the replication activity form: • Primary key replication • Primary key/timestamp replication They are explained in 3.5.8.1 and 3.5.8.2. A condition can also be used in the replication activity document’s conditional clause field to further refine the result set to achieve an enhanced, selective replication. The replication activity is recommended for use when you want to: • Synchronize data in two databases • Merge data from one data source into another data source 3.5.8.1 Primary key replication Primary key replication replicates data based on a unique key common to both connections, which can consist of one or more fields in the metadata. The fields must exist in the source and target metadata. The function of the primary key is to determine whether a mismatch, or conflict of records, requires an update to a record, the insertion of a new record, or a record deletion. One of the databases identified in the activity document is the master database. It contains the data that wins any replication conflict. When replication takes place, records are updated according to the following rules: • Record is identical in both databases: the record is not updated. • Record does not match but the primary key is identical: the record in the master database updates the record in the nonmaster database. Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 51 • A primary key value exists in the master database but not in the nonmaster: the record from the master database is inserted in the nonmaster database. • A primary key value exists in the nonmaster database but not in the master: the record from the nonmaster database is deleted. Note that the option of mismatching keys does not exist. Such a case is treated as an insertion and a deletion. Because no information beyond the primary key is available, all mismatches are regarded as conflicts. In the case of conflicts, the master database overwrites the nonmaster database, and the master always prevails in a primary-key-only mismatch. 3.5.8.2 Primary key/timestamp replication If the metadata involved in the replication contains time stamp fields, and those fields are identified in the replication activity, LEI performs primary key/timestamp replication. First LEI creates two result sets (one for each database) that include only those records that have changed since the last replication based on the time stamp field. LEI then matches primary keys: • Both master and nonmaster records are found: the master record updates the nonmaster. • Only one record is found (either master or nonmaster): LEI attempts to locate the primary key in the other database. • If the primary key in the other database is found, the changed record updates the record that was not changed. • If the primary key in the other database is not found, a copy of the changed record is inserted into the other database. In primary key/timestamp replication, the nonmaster database can update the master database if a change has occurred only in the nonmaster database record. If a corresponding record is changed in both the master and nonmaster databases, a replication conflict will ensue. Because LEI looks only at changed records, deletions are not replicated. If a record is deleted from one database, the corresponding record in the other database remains unchanged. To handle issues like this, you sometimes have to schedule a primary key replication on a less frequent basis to complement the primary key/timestamp replication. Primary key/timestamp replication looks only at the records where the time stamp field value is later than the last time the activity was run. Primary key/timestamp replication remembers the latest time stamp on both servers, so the servers can have different time and date settings without any problem. 52 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Some database systems use different levels of precision for date and time fields. For example, one system may store date/time values to the nearest second, whereas another system may store date/time values to the nearest millisecond. To accurately carry out time stamp replication options between these systems, LEI may have to reduce the precision of the date and time fields when comparing values. 3.5.9 Scripted activity A scripted activity is one that executes LotusScript commands. LEI extends the set of Domino classes available to LotusScript. The Lotus Connector LSX (LCLSX), which comes with Notes/Domino 4.63 and later, is also included with LEI, as is an LEILSX. LEI extends these classes with additional methods to support the LEI Administrator and log databases. Using Lotus Connector LotusScript classes allows you to extend the functionality available from the other LEI Administrator activity operations (Direct Transfer, Polling, Replication, and so on). You can also construct customized routines in situations where you need more complete control over source and destination data transfers, or wish to instruct the LEI engine to perform data massaging or evaluation during transfer. 3.5.10 Constructing an activity To create an activity, follow these steps: 1. Open the LEI Administrator Database. 2. Select Create - activity from the Menu Bar. 3. Choose the activity you would like to construct. The selected activity document will be opened in edit mode. Each type of activity document is different. Refer to the LEI online documentation for specific required fields for the activity document you are constructing. 3.5.10.1 Using action buttons to construct activities Action buttons can be very helpful in the construction of an activity document. While in edit mode, an LEI activity document may include the following action buttons: • Author Privileges • Select Metadata • Map Fields Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 53 Note You may receive the following error when you click one of the browsing-related buttons (Select Metadata, Map Fields, or Map Timestamp): Error loading USE or USELSX module: *leilsx This may occur because you do not have the LEI server installed on the machine from which you are trying to run the browse, or because the LEI directory is not in your path. Author Privileges The Author Privileges action button, shown in Figure 26, allows you to change author privileges for the activity currently being edited. Figure 26. Author privileges action button To change Author Privileges for the activity, select the Author Privileges action button. The Author Privileges dialog box appears. Select the action you want from the options available; see Figure 27. Figure 27. Author privileges dialog box These actions include: • Add names to document editor list • Remove names from document editor list • View document editor list 54 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products 3.5.10.2 Select Metadata The Select Metadata action button, shown in Figure 28, lets you display available metadata objects from which you can pick the activity’s metadata when building direct transfer, polling, and replication activities. With direct transfer and polling activities, the select metadata action lets you select fields from the source metadata for simple command statement building. With replication activity, the select metadata Action lets you select key fields. If the activity has two connections, run the select metadata for each connector. Figure 28. Select metadata action button When you click the select metadata action button, the connection selection dialog box appears. You may see a metadata type option, depending on the activity type. Table 2 shows your choices for the different activity types: Table 2. Metadata activity types Activity Type Direct transfer Replication Polling Click Source or target, depending on which connection you want to browse Connection A or connection B No option. Polling uses a single connection For the direct transfer type, the metadata selection dialog box appears; see Figure 29 on page 56. Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 55 Figure 29. Metadata selection dialog box If you are working with the source, choose from the metadata selection only (the default), build SQL query, or browse fields. A description of each option follows. Figure 30. Metadata selection screen • Metadata Selection Only — Lets you choose only from a metadata list based on the Connection selected; refer to Figure 30. • Build SQL Query — Lets you create a SQL command statement by selecting fields. • Browse Fields — Will not build or replace any existing command statement. 56 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Note: The Build SQL Query and Browse Fields options are only available in Direct Transfer and Polling activities. Click OK. If you are working with the destination, the metadata is entered into the form and the action is completed. If you are working with the source, you will see the field list. The Field Selection dialog is displayed. The field selection options depend on the type of activity that you are building. • Direct Transfer and Polling: If you picked the build option, choose the fields or columns that you want to appear in the command statement. These will be the fields that LEI will select for transfer or evaluation when polling. Check Select All if you want to choose all fields in the metadata. LEI does not build a command line through select metadata for a Notes source. • DPROPR or replication: Choose the key fields. Click OK to complete the action. Save the activity. The selected metadata and fields are not automatically saved. You must save the document in order to save your metadata and field selections. Filter by Owner Name Option This option allows users to view only those tables owned by a certain owner. It only applies to those data sources that support the concept of owner names. This excludes Domino/Notes, text, and file system connectors. If this option is checked, the next dialog will contain a list of owners found based on the information provided by the connection selected. After an owner is chosen, that list of tables is displayed; see Figure 31. Figure 31. List of tables by owner Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 57 If a data source that does not support owner names is chosen, an informational message appears. Owner names are cached in the same manner as the lists of tables and fields. The same refresh button and last refresh datetime appear in the table and field dialogs. Additionally, the owner name filtering checkbox will reflect the correct setting as cached and used previously. For example, you previously chose to use owner name filtering on the source connection but not on the target connection. Therefore, as you move between the two connections in the dialog box, the setting will appear as on for source and off for target. This is true in all cases, except if owner name filtering was chosen for a connector that doesn’t support it. In that case, the setting is turned off for the user since it is invalid. If a connection previously had owner name filtering turned on, it may be turned off and the entire list of tables for that connection will be displayed. This means that a connection to the data source is made, new table data is gathered, and the cache is rewritten. Note that the menu item Actions > Purge Cache can be applied to destroy the current cache and start over. 3.5.10.3 Map Fields The Map Fields action button, as shown in Figure 32, brings up the screen shown in Figure 33 on page 59. This displays fields in the source and destination metadata. By selecting a list of fields from both metadata objects, you can build a field list that the activity can use to map fields in moving data from one database to the other. Map Fields is available for Direct Transfer, Polling, Replication, Archive, and Realtime activities. Figure 32. Map Fields action button 58 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 33. LEI field mapping To use the map fields action button, after specifying both activity connections, click Map Fields. If the form contains no metadata or command line, Map Fields steps you through the steps described in 3.5.10.2, “Select Metadata” on page 55. In the lists of fields in source and target (or Connection A and B) metadata, make a one-to-one selection of corresponding fields. In other words, the first field on the source selected list will map to the first field on the destination selected list, the second to the second, and so on. If you make an error, click the Clear button and start over, or remove the check from the unwanted item in the master list selection. To update the cache for the selected metadata, click the corresponding refresh button in the dialog box. This will cause LEI to read the data from the defined connection and update its cached information. When done mapping fields, click OK. If the option Map Fields as User Defines is not selected on the activity form, you will be asked if you want to select it. Save the activity document. The selected fields are not automatically saved. You must save the document in order to save your field mapping selections. Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 59 3.5.10.4 Create Agent (Script activity) The Create Agent action button, shown in Figure 34, appears in the LEI Administrator document when you select Create - Activity - Scripted from the menu bar. Figure 34. Create Agent action button Click Create Agent action. The screen in Figure 35 appears, prompting you to enter a server name for the location of the scripted activity. Figure 35. Entering a server name for scripted activity Enter a server name for the location of the scripted activity. To use the default server, click OK. After specifying the server or accepting the default server, Figure 36 appears, prompting you to specify the database containing the scripted activity. Figure 36. Database name prompt Specify the database containing the scripted activity and click OK. The LotusScript Agent Development document window appears, as shown in Figure 37 on page 61. Use this document to develop the scripted activity. 60 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 37. LEI LotusScript agent integration 3.5.11 Running activities There are two ways to run an activity: on a schedule, or on demand using an agent known as Run ASAP!. 3.5.11.1 Running an activity with Run ASAP! The Run ASAP! button, shown in Figure 38, is visible while in view mode in an activity document. If clicked, it causes the activity to be run the next time the LEI server polls the LEI Administrator database for pending activities. Figure 38. Run ASAP! button Click the Run ASAP! button when you want to run an activity as soon as possible. It can be used even if an activity is set up to be run on a schedule. Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 61 Alternately, the Run ASAP! agent can be invoked by selecting the activity document from the overview, activities, or categories views in the LEI Administrator database, and selecting Actions - RunASAP! from the menu bar. 3.5.11.2 Running an activity on a schedule Any activity can be set up to run on a schedule. There is a scheduling section in each activity document, shown in Figure 39. Figure 39. Scheduling section in an activity Basic scheduling options include: • • • • Schedule — Enable or disable schedule Run at Times — A given hour or range of hours at which to run this activity Repeat Interval — How often to repeat this schedule Days of Week — Days on which this schedule should run Advanced scheduling options include: • Start Date and Time — Activity will not be scheduled to run prior to this date and time • Stop Date and Time — Activity will not be scheduled to run after this date and time • Days of the Month — Numerically specify days of the month to run this schedule • Weeks of the Month — Numerically specify weeks of the month to run this schedule 3.6 LC LSX Extensions with LEI The following LC classes have expanded properties when LEI is installed: • LCConnection Class • LCFieldlist Class • LCSession Class 62 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products The LCSession class also provides additional methods to support activity level properties and logging. When an LEI scripted activity runs, the script can access the property fields of the activity form. When a scripted activity is used in conjunction with the LEI CGI program and an HTML form, the form’s field values appear in the session object as read-only properties. See 4.1, “LCLSX LotusScript Extension connectors” on page 67 for additional details about the LCSession Class methods. 3.7 Sample: Direct Transfer and Realtime access to relational data This section presents a scenario in which LEI is used to satisfy a business requirement. Chapter 7, “Connecting to DB2 with LEI” on page 109 describes the connection documents for the sample activities. Requirement: Provide real-time access to DB2 from a Web browser. Solution: LEI can be used to access data in real-time. The steps to complete this activity follow. (Note that DECS is the recommended way to implement real-time activities.) 3.7.1 Construct a DB2 Connector • From the LEI Administrator database, click Create Connection from the LEI Administrator navigator. A menu will appear. • Select DB2 to continue. A new DB2 connection document will be opened. • Choose a meaningful name for your connection. This is how you will refer to it when constructing activities. • Fill in the DB2 database name, user name, and password. These are the minimum requirements for a DB2 link. - There is a checkbox option for non-journaled data. Select this option to enable support for SQL queries against data in non-journaled tables. You can read more about data journaling in 2.4.1, “Creating a connection document using the wizard” on page 17. - Another optional section is Connection Options, which contains DB2-specific options for this connection. For more information on how to use these options, refer to the LEI Users Guide. Click the Save & Exit action button when you have completed the connection document. Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 63 Note: The password you enter in the connections is not encrypted by default. You can click the button next to Password NOT Encrypted on the connection document if you wish to specify an encryption key for the password. 3.7.2 Construct a Notes connector • In the LEI Administrator database, click Create Connection from the LEI Administrator navigator. A menu will appear. • Select Notes to continue. A new Notes connection document will be opened. • Choose a meaningful name for your connection. This is how you refer to it when constructing activities. • Type the name of the Notes server where the database you want to connect to is located, and the database name with the path to the Notes data directory. These are the minimum requirements for a Notes link. There is also an optional section of connection options for extending the capabilities of LEI to take advantage of specific Domino data structures and design elements. The options let you specify, for example, view-based selection criteria that manage the hierarchical structure of Notes. Connection options also permit you to define data translation and manipulation. For more information on how to use these options, refer to the LEI user’s guide. • Click Save & Exit when you have completed the connection document. • Test both connection documents. To avoid problems during the running of an activity, it is a good practice to test your connection documents before continuing. Use the LCTEST program that is included with LEI. It will be in the same subdirectory as the LEI executable. See 3.4.1.1, “Testing connectors” on page 44. 3.7.3 Construct direct transfer activity To complete a realtime activity, at least one key field must be resident in Domino. Therefore, you will need to create and run a direct transfer activity to transfer the content of key fields from DB2 to Domino. • From the LEI Administrator Navigator, click Create Activity. A menu will appear. • Select Direct Transfer. A new direct transfer document will be opened. Choose a name for your activity. 64 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products • Under the source section, click the pulldown box next to Connection Name. You will see a box containing all previously-defined connectors. Click the DB2 connector you constructed in 3.7.1 on page 63. • Under the Target Section, click the pull down box next to Connection Name and select the Notes connector you constructed in 3.7.2 on page 64. • If you are working at the server or at an LEI development client, you have access to the Select Metadata and Map Fields action buttons. Details on using these buttons are given in 3.5.10.1, “Using action buttons to construct activities” on page 53. Use the Metadata buttons to complete the Source and Target sections. If you do not have access to the action buttons, you will need to know beforehand the DB2 table name, target form name, and DB2 select statement for the field you will be transferring. • Next, complete the Field Mapping Section. This section gives you the option of selecting Automatic field mapping. Clicking this box will prompt you to choose between mapping by field name or field position. However, for our example we will be using the Map Fields Action button to fill out the Source and Target Field Lists. These fields should contain the names of the DB2 key field and the field where Notes will hold the key field once it is transferred. This completes the required information for the transfer of a key field from DB2 to Notes. There are other options that could be used in a direct transfer activity. For more information on these options, see the LEI user’s guide. 3.7.4 Construct Realtime activity Note: LEI has the same base code as DECS, and both can perform real-time activity. Here we describe how to do it using LEI. However, it is preferable to do real-time using DECS. • From the LEI Administrator Navigator, click Create Activity. A menu will appear. • Select Realtime Notes. You will now be in a new Realtime activity document. • Choose a name for your activity. • In the Notes section, use the Select Metadata buttons to fill in the name of the Notes database where users will be accessing the real-time data. It should be the same one that was specified in the Target section of the Direct Transfer activity document. Chapter 3. Introduction to Lotus Enterprise Integrator (LEI) 65 • The Metadata button will also prompt you to fill in the Notes Form Name and Notes Key List. This should be the field that was transferred in the Direct Transfer. In the External Data Source section, use the pull-down box to select the DB2 connection that you previously constructed. • You will then need to fill in a Table Name. You can use the Metadata button to select the table and keyfield to be used. • Continue with the Field Mapping section. The Key List fields have already been filled in with the Metadata button. The Notes Field List and External Data Field List should contain a list of corresponding fields between DB2 and Notes. List all the fields that will be viewed from Notes. Use the Map Fields Action button to complete these fields. If you do not have access to the action buttons for any of these fields, you can manually type in the appropriate information. • Clicking the pulldown box in the Events to Monitor section gives you four options. For our example, we assumed the data only has to be viewed with a Web browser. Therefore, we selected Document Open. More detail on these options can be found in the LEI user’s guide. This completes the required information for the Realtime activity document. 3.7.5 Final steps • Run the Direct Transfer activity by selecting it from the Activities view in the LEI Administrator Navigator and then clicking Action - RunASAP from the menu bar. If there are any errors, open the Direct Transfer activity and use the log link to view the error for that activity. Correct the error before continuing. • Run the Realtime activity by selecting it from the Activities view in the LEI Administrator Navigator and then clicking Action - RunASAP! from the menu bar. • Make sure your Domino HTTP task is running. You will now be able to view this DB2 data real-time using a Web browser. • It is always a good practice to test your connection documents before continuing. Use the program LCTEST that is included with LEI. It is in the same subdirectory where the LEI executable is located. 66 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Chapter 4. Introduction to programmatic connectors In this chapter we talk about connectors that require programming to make them operational. We cover Lotus Connectors LotusScript Extensions (LCLSX), LotusScript Data Objects (LS:DO), Message Queueing Series Extensions (MQLSX), Lotus C/C++ (C API) connectors, and @Functions. 4.1 LCLSX LotusScript Extension connectors You can program the Lotus connectors using a LotusScript Extension (LSX). There is a Lotus Connector API available from Lotus that permits development of additional Lotus Connectors for Domino. The LotusScript Extension for Lotus Connectors (LC LSX) extends use of the Lotus Connectors to LotusScript. The programming model is independent of individual connectors, eliminating the need to learn each system, but allowing experienced users to access specific connector features. Using this LSX, developers can access external data natively, using the same object model to make calls syntactically to a variety of enterprise systems. This reduces the learning curve for integrating Domino with enterprise data sources. Through the LC LSX, Notes and Web applications can retrieve and act upon data from agents, during document events, or by clicking a button. The LC LSX can be used alone or in conjunction with Lotus Enterprise Integrator (LEI). Together these technologies provide programmatic and declarative access to external data. Domino R5 on S/390 provides the following set of connectors at the time of writing. In addition, an MQSeries connector using LC LSX is under development. • DB2 • Notes 4.1.1 Terms and concepts The following terms have special meaning regarding connectors. 4.1.1.1 Metadata This is a generic term referring to a connector’s data definition. The data definition includes the names of data elements and their data types, and implies the order of the elements. For example, Domino uses forms to describe both the names of data fields and the data type of each field, while Sybase metadata describes a table. © Copyright IBM Corp. 2001 67 Metadata is information about the stored data. MetaConnectors define an action to execute against data being transferred, sometimes resulting in data transformation (as with the collapse/expand MetaConnector), and sometimes leaving the data unmodified (as with the billing MetaConnector). 4.1.1.2 Result set Information requested through a connection gives you a result set. Each connection can have a single active result set. You can have multiple simultaneous connections. The LCConnection methods (Execute, Select, Call, and Catalog) each produce a result set, replacing any existing result set. The result set describes the collection of data from the connection that matches the input criteria. Actual data is not returned until fetched. If specified, these methods build a field list representing the metadata, as part of generating the result set. When using connection methods that read or write the data of a result set, the default order of the metadata may be suspended by using the connection’s OrderByName property. Regardless of the order of the data within the metadata, OrderByName matches the names in the metadata to the names in the external system. 4.1.1.3 LC LSX Classes The LC LSX classes are an extension to the standard Notes classes. They have to be loaded using the Use statement in the options section of each code segment. The classes are by default installed on every Notes Client or Domino Server and ready to use. There are four LC LSX classes: • • • • LCSession LCConnection LCFieldlist LCField In addition to the four classes, there are four advanced data types: • • • • LCStream LCNumeric LCCurrency LCDatetime To make the LCLSX classes available, place the following statement in the Options event of your LotusScript program: Uselsx ” *LSXLC” 68 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 40 shows the relationship between the different LC LSX classes: LCSession LCStream LCDatetime LCNumeric LCConnection LCFieldList LCCurrency LCField Datatype Figure 40. Relationship between different LCLSX classes with datatypes 4.1.2 Classes and datatypes We now discuss briefly the classes and datatypes. For a detailed list of their properties and methods of use, see Appendix A, “DECS activity options” on page 195. 4.1.2.1 LCSession The LCSession class provides error information useful in error handling. It also provides for query and lookup of available connectors. You do not need the LCSession class in order to connect to a data source, but it is recommended because it gives good error feedback. 4.1.2.2 LCConnection The LCConnection class represents an instance of a Lotus connector. This class provides query and data access to the external system. Multiple instances of an LCConnection class can be allocated to a single connector. LCConnection properties depend on the specific connection. Typical properties include LCConnection.Database, LCConnection.UserID, and LCConnection.Password. 4.1.2.3 LCFieldlist The LCFieldlist class is the primary class for manipulating data through a connection. It binds a group of fields together with names and a default order. Chapter 4. Introduction to programmatic connectors 69 When you generate a result set and pass in an empty fieldlist, the connector automatically populates the fieldlist. For each data element of the result set, the fieldlist receives the element’s name and an LCField object of the corresponding data type. The result set can be controlled by manually building the fieldlist before generating the result set, or by using the FieldNames property of the connection. The Select and Call connection methods use an optional fieldlist of keys or parameters to restrict the result set. You construct this fieldlist manually and pass it to the Select method. You construct a key or parameter list by appending or inserting names and datatypes to the list. These methods create fields in the fieldlist and return the fields for further manipulation. The fields are then given values and, using field flags, can be given conditions such as greater-than and not-equal. 4.1.2.4 LCField LCField is a storage class that contains one or more data values. The data type of a field applies to all the values and can be one of the four advanced datatypes. 4.1.2.5 LCStream LCStream is a general purpose text and binary data type. A stream has a format that details the character set of the text and any special attributes of the binary data. Use it to store and manipulate text or binary data in the supported character sets. 4.1.2.6 LCNumeric The LCNumeric class is a container for high precision numbers. See the LC LSX documentation for syntax and details. 4.1.2.7 LCCurrency The LCCurrency class is a fixed point decimal data type with 4 decimal places and 19 digits of precision. This data type is mathematically equivalent to the LotusScript data type and is provided to support connections with a dedicated currency. 4.1.2.8 LCDatetime The LCDatetime class is a date and time data type. It is accurate to a hundredth of a second, and it specifies time zones and daylight saving time. 70 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products 4.1.3 Working with LCLSX The typical use of connectors is to gather, create, and modify data in the enterprise system. For example, a Domino application has a number of data fields on a form. Once user input is complete, a button activates a script to update corresponding information in an external data store. For this redbook, we concentrate on scripts running on a Domino for S/390 server. The script handles all the database activity on the Domino server, so all that you need is a thin client, without any database connectivity software. It is possible to execute the scripts locally on a Notes client, but in that case you need connectivity software, such as DB2 Connect, on each Notes client workstation accessing the enterprise system. 4.2 LS:DO ODBC connectors Since Lotus is putting development emphasis on the LCLSX connectors, we will not cover LS:DO very deeply. If you can choose a programmatic connector, we recommend the LCLSX connectors. One reason for this recommendation is because they are becoming widely used on different enterprise systems (although on S/390, only the DB2 connector is available at the time of writing). Another reason is because of the performance and function of LCLSX over LS:DO. However, since there may still be reasons to use LS:DO, we will go through it here in some detail. LotusScript:Data Object (LS:DO) provides full read and write access to external data sources using the complete control and flexibility of the LotusScript structured programming language. Unlike the other platforms, LS:DO on S/390 does not use ODBC. 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. In addition, LS:DO is easy to learn and use, because its design is consistent with LotusScript syntax and the LotusScript Notes classes. Note: Unlike the other platforms, S/390 does not provide ODBC support. However, DB2 for OS/390 ships an ODBC-compliant driver along with documentation. Chapter 4. Introduction to programmatic connectors 71 To make the LS:DO classes available, place the following statement in the Options event of your LotusScript program: Uselsx ” *LSXODBC” 4.2.1 Event handling If needed, you can create event-handling subroutines for some ODBC methods. These subroutines are called according to the behavior of an appropriate ODBC method, after the On Event statement is issued. In the following example, an event handler named presub1 is called before the ListDataSources method is called. 1. On Event statement Dim connection As New ODBCConnection On Event BeforeListDataSources From connection Call presub1 2. Event handler Sub presub1(Source As ODBCConnection) ‘** Write your event handling script here End Sub Your event handler must be in the scope where the event occurs. 4.3 MQLSX The MQSeries LotusScript Extension (MQLSX) can be used in any environment supporting LotusScript. It provides a set of classes incorporating the full power of the MQSeries Message Queueing Interface (MQI), giving your LotusScript applications the ability to interact with any MQSeries-enabled application in your enterprise, as illustrated in Figure 41. Of course the clients can be Notes-based as well as Web-based. In our environment, the MQLSX code will always run as an agent on the Domino for S/390 Server. Note: The MQLSX connector is being phased out in favor of the LCLSX MQ Connector. 72 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products MQLSX S/390 OS/390 Agent Uselsx "MQLSX" MQSession MQMessage ....... M Q L S X Remote MQS Systems MQSeries CICS Apps IMS Apps DB2 Apps Notes Notes Database Database Figure 41. Overview of the MQLSX MQSeries is IBM’s message queuing middleware product. It allows two or more applications on unlike systems to talk by sending messages. MQSeries uses a combination of programming (MQSeries API or MQI), queues (MQSeries Queue Manager or MQM), and channels (MQSeries Channel Architecture or MCA) to allow this exchange to occur. For further details on MQSeries, visit this IBM Web site: http://www.software.ibm.com/ts/mqseries The MQSeries LotusScript Extension allows you to integrate your Domino application with MQSeries, which must be installed on your Domino server. For developers, it must also be installed on the Notes client. In this redbook, we will focus on the server installation. The version and type of MQSeries you install is up to you and your system architecture. The type of MQSeries product depends on your infrastructure and integrity requirements. You can either install the MQSeries thin client or the full MQSeries server with Domino. There are advantages to either decision and each situation must be explored to weigh those advantages. Chapter 4. Introduction to programmatic connectors 73 These considerations are not discussed in this section, as the advantages and disadvantages depend on the systems you are using and on your network infrastructure (the topology, architecture, and protocol used). 4.3.1 What is the MQSeries LotusScript Extension The MQSeries LotusScript Extension (MQLSX) provides a tight link through MQSeries to transaction-based systems, allowing seamless integration of business processes across Domino and transaction systems. MQLSX enables you to make MQSeries calls directly from your LotusScript code. Figure 42 shows the architecture of the MQSeries LSX: Figure 42. MQLSX architecture placement With the MQSeries LSX, you can develop applications that integrate the Domino environment with transaction-based applications and legacy system data through MQSeries. This allows you to access enterprise application logic, not just the data, through a variety of platforms, since you have direct integration between Domino and MQSeries. 4.3.2 Class overview There are seven MQSeries LSX classes: • • • • • MQSession MQQueueManager MQQueue MQProcess MQMessage 74 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products • MQGetMessageOptions • MQPutMessageOptions In addition, the MQSeries LSX also provides predefined LotusScript constants, such as MQFMT_NONE, that are used by the classes. The constants are a subset of those defined in the MQSeries C header files, namely CMQC*.H, with some additional IBM MQSeries LSX reason codes. These classes can be categorized into three groups: • The first group contains the MQSession class. It provides a root object that contains the status of the last action performed on any of the MQSeries LSX objects. • The second group contains the MQQueueManager, MQQueue, and MQProcess classes. They provide access to the underlying IBM MQSeries objects. Methods or properties defined in these classes result in calls being made across the MQI. • The third group contains the MQMessage, MQPutMessageOptions, and MQGetMessageOptions classes. They encapsulate the MQMD, MQPMO, and MQGMO data structures respectively, and are used to put and retrieve messages to and from queues. The class relationship is presented in Figure 43 on page 76. Chapter 4. Introduction to programmatic connectors 75 MQSession AccessQueueManager References . Classes . Methods Connect Disconnect MQQueue Manager AccessProcess AccessQueue Open Put MQPutMessageOptions MQProcess MQQueue MQGetMessageOptions Get Close Write MQMessage Figure 43. MQLSX class model The following list identifies the components in Figure 43: • The MQSession class defines an instance of MQSeries access. This class manages all calls and error conditions. Its AccessQueueManager method is used to set the MQQueueManager class object. • The MQQueueManager class is used to access the MQSeries Queue Manager (MQM). This is performed by the Connect method for access and the Disconnect method to indicate completion. • The Disconnect method must be used in the newer version of the MQLSX for syncpoint control. Ensure that you code this statement. • The MQProcess class object is set by the AccessProcess method of the MQQueueManager class. The MQProcess class enables you to read the MQSeries process definitions. • The MQQueue class object is set by the AccessQueue method of the MQQueueManager class. The MQQueue class allows you to manipulate your queues. You must use the Open method to access your queue, and when you are done, use the Close method to commit your work. 76 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products • The MQPutMessageOptions class and the Put method of the MQQueue class define the complete put operation to the MQ Queue. • The MQGetMessageOptions class and the Get method of the MQQueue class define the complete get operation from the MQ Queue. • The MQMessage class contains the Write and Read methods that enable you to manipulate the message buffer. This buffer is used by the Put and Get operations as the storage area for your message content. 4.3.3 MQLSX installation on Domino for S/390 To perform this installation, you first download the code for MQLSX for Domino for S/390, since it is not a standard feature. The MQSeries Web site is located at: http://www.software.ibm.com/ts/mqseries/ MQLSX for Lotus Domino for S/390 is provided as a SupportPac. It is a tar file of 3.4 MB, and you can find a link to it at the following URL: http://www.software.ibm.com/ts/mqseries/txppacs/txpsumm.html It is recommended that a separate HFS be created for the /mqm directory, which will be defined later in the install process. Here is JCL to define the HFS dataset: //MQALLOC EXEC PGM=IEFBR14 //MQMHFS DD DSN=XXXXXX.MQM.HFS, // DISP=(NEW,CATLG,DELETE),UNIT=XXXX,VOL=SER=XXXXXX, // DCB=(DSORG=PO), // SPACE=(CYL,(20,5)), // STORCLAS=XXXXXX // DSNTYPE=HFS // Here is the mount statement to place in your BPXPRM member: MOUNT FILESYSTEM('XXXXXX.MQM.HFS') TYPE(HFS) MODE(RDWR) MOUNTPOINT('/mqm') Another method is to use ISH (interactive shell). We created an HFS with a high-level qualifier of MQM and a mount point of /mqm. We used ISH to create the HFS, rather than using JCL. Chapter 4. Introduction to programmatic connectors 77 Then we uploaded the tar file to the S/390 server using ftp and placed it in the root directory (/). The command sequence to do this is: ftp wtsc67oe cd / bin put <== <== <== <== wtsc67oe is the TCP/IP name of the omvs S/390 Server Valid OS/390 userid Password Set directory on S/390 as omvs root directory To unpack the tar file, we went into the OS/390 UNIX shell (using the TSO OMVS command) and issued these commands: cd / tar -xvof MA1H.tar This created a directory structure in the HFS file system. For convenience, we suggest that you enter the environment variable statements in the .profile file of the user ID that starts the Lotus Domino server. We made our changes in the .profile of ebbers1. This ID is authorized to start and stop our server. Any changes to the environment variables will not be activated until Domino is stopped and restarted. To enable the MQLSX to find the Code Page Conversion Tables, you must set the following UNIX System Services environment variable: export GMQ_XLAT_PATH=/mqm/mqlsx/conv For optional tracing, set the appropriate environment variables according to the information in Chapter 4 of the user’s guide for MQLSX; for example: export GMQ_TRACE=on export GMQ_TRACE_PATH=/mqm/mqlsx/trace export GMQ_TRACE_LEVEL=9 Add the following to the STEPLIB environment variable of your UNIX System Services Environment to pick up the batch adapter: export STEPLIB=SYS1.MQM.SCSQAUTH:$STEPLIB 4.3.3.1 Agent settings You need to edit the agents currently set to run on other platforms to tell them to run on your Lotus Domino server for OS/390. AMGR_DOCUPDATEAGENTMININTERVAL=1 AMGR_DOCUPDATEEVENTDELAY=1 LOG_AGENTMANAGER=1 78 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Setting these to 1 will cause the agent to run as soon as it can. However, you should set them according to the workload on your agent. See “About the NOTES.INI file” in the Notes Administration Guide for more information. 4.3.3.2 Setting the file ownership Use the mqlsxown script to change the ownership. It requires two parameters. mqlsxown $userid $group We used ebbers1 for $userid and sys1 for $group. The ebbers1 ID is authorized to start or stop our Domino server on OS/390, and sys1 is the group that is used by Domino. Change the directory to /mqm/mqlsx and type the command above. The first parameter is the user ID that is used to start the Domino server for OS/390, and the second parameter is the group name that the server uses. 4.3.3.3 Complete the installation Read and follow the instructions in the Installation Guide section of the mqlsxdoc.nsf database. This was included in the download. 4.3.3.4 Contents of the sample code After installing the SupportPac code, you will see that there is a subdirectory called /mqm created in the OMVS root directory. There are two Notes databases placed into the /notesdata subdirectory; they are MQLSXDOC.NSF and MQLSXVERIFY.NSF. As mentioned in the readme file, we ran the mqlsxown program with a suitable user ID and groupname (in our case, ebbers1 for $userid and sys1 for $group). The next step is to check the Installation Verification Program. You must have the MQSeries environment active on OS/390 before starting this IVP. Ask your MQSeries administrator or systems programmer for the name of your message queue manager subsystem. Make sure the MQM subsystem is running and its batch adapter is active. By default, the MQLSX IVP agent works with local queue SYSTEM.DEFAULT.LOCAL.QUEUE. After copying the MQLSXVerify.nsf database to the server, the agent’s view of the database has to be opened; you can do this using the Domino Designer. The database contains one agent called MQLSX OS/390 install verification. This agent is activated by clicking the checkmark in the empty box. The server hosting the database is entered in the server popup. The agent runs if documents are created or changed, and it takes the latest created document. Chapter 4. Introduction to programmatic connectors 79 Note Be sure that the user activating the agent has privileges to execute Lotus Script Agents on the server. If you encounter a message that you are not authorized to run this agent, you have to add the user to the groups authorized to execute limited LotusScript agents on the server. This is done in the server document under security. For further details, refer to the Domino Administration documentation. As shown in Figure 44, we created a “Verify” Document, using the Create/Verify Menu. Figure 44. MQ Installation verification We used MQLSX as the name of the queue manager and saved the document. We activated the agent and created the verify document. A few minutes later, the agent ran. The result of the agent activity appeared in the Notes log. If installed correctly, the agent produces the following results: 11/03/2000 11:22:56 AM AMgr: Start executing agent 'MQLSX OS/390 install verification' in 'mqlsxverify.nsf' by Executive '1' 11/03/2000 11:22:56 AM AMgr: 'CN=Milan Otajovic/O=Itso' is the agent signer of agent 'MQLSX OS/390 install verification' in 'mqlsxverify.nsf' 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 1.Verification program has started and we have sucessfully loaded the MQLSX DLL 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 2.Successful dim on the MQ objects 80 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 3.Successful New MQSession 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 4.Successful New MQQueueManager 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 5.Successful New MQPutMessageOptions 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 6.Successful New MQGetMessageOptions 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 7.Successful New MQMessage 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 8.Successful Connect MQSX 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 9.Successfully AccessQueue SYSTEM.DEFAULT.LOCAL.QUEUE 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 10.Successful WriteString Hello World 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 11.Successful setting MessageType to MQMT_DATAGRAM 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 12.Successful setting Format to MQMT_STRING 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 13.Queue depth before put: 0 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 14.Successful putting the message 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 15.After PUT and COMMIT queue depth is: 1 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 16.Successful setting MQGetMessageOptions 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 17.Queue depth before get: 1 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 18.Sucess getting the message 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 19.Successful ReadString 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 20.Message put matches message got 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 21.Message Put:..Hello World .. 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 22.Message Got:..Hello World .. Chapter 4. Introduction to programmatic connectors 81 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 23.Successful Committing the message 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 24.After Get and COMMIT queue depth is: 0 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 25.Successful DisConnecting 11/03/2000 11:22:57 AM AMgr: Agent ('MQLSX OS/390 install verification' in 'mqlsxverify.nsf') printing: 26.Verification Routine has completed. Your install is successful only if you have no error messages? 26 steps are successful. If there are errors, it is time to review the installation procedure. 4.3.3.5 Getting help SupportPac help can be obtained through your regular support channels for MQSeries. You can also participate in the MQForum under the Discussions link at Lotus Enterprise Integration Web site: http://www.lotus.com/enterpriseintegration Online documentation on MQSeries is available at the following address: http://www.software.ibm.com/ts/mqseries/library (case sensitive) 4.3.4 Installing MQLSX code for a development client The client MQLSX code is necessary on workstations where development is done. The local script syntax checker requires the MQLSX code to be installed locally. Notes clients or Web browsers executing the application don’t need the LSX code on the client, because in our examples the code is executed only on the Domino for S/390 server. The MQLSX code for various platforms can be located and downloaded using following URL: http://www.software.ibm.com/ts/mqseries/txppacs/txpsumm.html The SupportPac containing MQLSX code for Windows NT is MA7D. The zip file is ma7d.zip, 5.67 MB in size. We unzipped the file, which exploded to 15 files and 1 folder. We ran setup.exe to install the MQLSX client on NT. 4.4 Lotus C/C++ API connectors If you need a specific function that is not contained in a standard connector product, or if your application connection needs to be customized, you can 82 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products write your own connector code. Refer to Enterprise Integration with Domino for S/390, SG24-5150, for more details. 4.4.1 Writing your own connector code It is possible to write your own code to provide the connection between Domino and other applications on the same or a different S/390 server. This code would probably be written in C/C++, and would provide the glue between the two environments. This approach offers the following advantages and disadvantages. 4.4.1.1 Advantages Some of the advantages of writing your own code are: • Custom function: If none of the connector products have exactly the functions you need or are not available in your timeframe, you can write connector code, as shown in this redbook. • Performance: It is possible that you will get better performance from your own tailored code than from a standard product. This is because a standard product contains more code that you will probably need. However, we have not tested this possibility. 4.4.1.2 Disadvantages You also need to consider the disadvantages of writing your own code before selecting this option: • Maintenance: You need to maintain whatever code you write. Whenever you require changes to function, or you upgrade the Domino server, you must retest your code. • Skills: The connector code is written in C/C++. In some cases it also uses the Notes C/C++ API. Do you have those skills available? If not, are you willing to invest in them? • Availability: Errors in the connector code can result in a failure of the Domino server. Very careful testing is therefore required, and your code must handle all errors. • Master copy of data: When you design a Domino-to-database application, you must decide what data resides in both locations. Then you must decide which is the master copy, which fields can be updated from which side, and how to handle replication conflicts (especially if both sides can update). 4.4.1.3 Recommendations Considering all of these aspects, here are our recommendations. Chapter 4. Introduction to programmatic connectors 83 • Explore all of the options before deciding to invest in writing your own code, and choose the best solution for your requirements. • If the standard products achieve what you want, they are probably a better option. • Consider writing your own code in limited cases, such as when you need function or performance that is not available any other way. • Keep your connector code as simple as possible. Put the main function into LotusScript and the enterprise subsystem application, and put as little as possible in your connector code. This will minimize both your maintenance effort and problems in the code. 4.4.2 The Notes C/C++ API The Lotus Notes C/C++ API is a set of subroutines and data structures that allows you to write programs that access Notes databases. The API subroutines are written in C or C++, and you call them from C or C++ programs. With the Notes C/C++ API, you can write programs that perform a significant subset of the operations available through the Notes user interface, as well as some operations that are not available through the user interface. The API allows you to treat Notes databases at a high level by creating and deleting entire databases.You can create new documents, delete existing documents, and copy documents from one database to another. You can add fields to documents, delete fields from documents, copy fields between documents, read fields, and write into fields. The Notes C/C++ API lets you extend the Notes software with user-written add-ins. An add-in can be on the Notes workstation and present the user with tailored pulldown menu choices. Or it can be on the Lotus Domino server, running alongside the standard Lotus Domino server tasks. 4.4.2.1 Connector code The connector code can be a standard product, such as a LotusScript Extension (LSX; for example, LS:DO or MQLSX) or Lotus Enterprise Integrator (LEI), or it can be a C/C++ program that you write yourself. 4.4.3 Notes application A Notes application is written on S/390 in exactly the same way as on any other platform. Notes databases are encoded in Lotus Multi-Byte Character Set (LMBCS), which uses ASCII encoding. (S/390 is an EBCDIC platform, but 84 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products it can store ASCII files.) From any other platform, you can copy a database to the S/390 server using Notes replication. Or you can use utilities such as file transfer program (ftp) or Network File System (NFS) with the binary option. 4.4.4 C or C++ program The C or C++ program provides the connection between the Notes environment and the enterprise application. This can be used if the standard connector products do not meet your business needs. 4.4.4.1 Running a C program on OS/390 Lotus provides the ability for you to write C and C++ applications that interface to Notes databases. You can choose from two different interfaces: • The application can use the Notes application programming interface (API) toolkit, supplied by Lotus, to interface to the Domino server. This toolkit has been ported to S/390 and is available from the Web. Note that there are differences in the API between UNIX and Intel server platforms, and also some minor differences between specific platforms. If you are coding for the OS/390 for the first time, you need to allow for these differences. • The application can also interface directly to the server operating system, OS/390. OS/390 is branded XPG4 UNIX Profile (also known as UNIX 95) compliant. Code using these interfaces is portable to other platforms. One difference between S/390 and other servers is that, while most servers use ASCII data encoding, S/390 (and AS/400) uses EBCDIC data encoding. As noted, the Domino server works in ASCII. Therefore, the C code needs to do any necessary data conversions from ASCII to EBCDIC, and also from IEEE floating point format to S/390 floating point format. To make it easier to write ASCII applications on OS/390, IBM provides the libascii toolkit. This handles many of the ASCII-to-EBCDIC differences for you. 4.4.4.2 Design When designing a production application, you should carefully consider these points: • Robustness: Your code should handle all error conditions, including errors accessing the enterprise application and unexpected data (such as many rows returned from a relational database). • Testing: If the C code fails, it may bring down the complete Domino server. Therefore rigorous testing is necessary, including all possible errors. Chapter 4. Introduction to programmatic connectors 85 • Simplicity: We recommend that you keep the C/C++ program as simple as possible. Just write the function that you need to achieve communication between the two applications. Program logic should be contained in the Notes application and in the enterprise subsystem application. This will minimize the maintenance you need to do on the C code, and will minimize the chances of errors in the C code. If your C/C++ code will require much logic, you might consider using the standard connector products, which provide a great deal of function for you. • Performance: If your code is required to handle a high transaction rate, you may need to develop a sophisticated program. You can do that on OS/390 by making the program reentrant, loading it into the link pack area (LPA), and setting the sticky bit on in the HFS. This means that the program will be loaded only once and that it can be used by multiple users concurrently. The Domino server uses this technique to put some of its server code into LPA. For further information, see Lotus Domino for OS/390 Release 5: Installation, Customization and Administration, SG24-2083 and Lotus Domino for OS/390 Release 5: Performance Tuning and Capacity Planning, SG24-5149. 4.4.5 Production environment You may need the libascii, Notes C API toolkit, and Notes C++ API toolkit packages, which are available for download from the Web at: http://www.s390.ibm.com/products/domino The Domino server runs under a single RACF user ID on the OS/390 system. You need to make sure that this ID has access to all of the programs and files that are used for your code. 4.4.6 Test environment For testing, you need to set up a separate Domino server. We found that errors in our code often caused the Domino server to fail. Therefore we gave each person on the redbook team their own Domino server, using Domino partitioning support, so that they did not interfere with each other. 86 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Important Each server should be run from a separate RACF user ID that is not a superuser. Then, when the server fails, you can run killnotes to tidy it up before restarting it. If you use IDs with superuser authority, all Domino servers may be killed when you run nsd -kill. We also chose to run each test Domino server from its own (telnet or OMVS) session. While this is not ideal for production running, it provided an easy interface for the team, and kept each server's console messages separate. If you run the servers from the OS/390 operator console using DOMCON, all of the server messages go to the same log and it is more difficult to identify error messages for a particular server. Telnet is recommended over OMVS. If you run your server from OMVS, you need to specify a large region size for the TSO user ID that will start the server, otherwise you will get memory errors. We specified 100 MB to ensure we did not encounter these problems. Another reason to not use OMVS for a production environment is that the console screen will often go into input mode (at the bottom right corner of the screen) and the server will wait. You must press F10 (refresh) for the server console and the server to continue. 4.4.7 Other applications accessing Notes If you have Domino running on the same system as other applications, you may wish to write an application that initiates an action in Domino, such as: • Updating a Notes document • Sending a mail message You can do this by writing a C/C++ program that uses the Notes C API to access a Notes database. When designing your application, carefully consider the needs of the application in terms of efficiency and timeliness. The most efficient way to make numerous updates into Notes is to batch them up, such as by putting them in a file or adding them to an MQSeries queue. You can then make a number of updates with a single invocation of the C/C++ program. However, this introduces a delay in the updates. Chapter 4. Introduction to programmatic connectors 87 If you need immediate updating, you will need to do a direct call for each update. However, this incurs the overhead of initiating the C/C++ program and linking to the Domino server for each update. It may be possible to reduce that overhead by making the C/C++ program and the link to Domino persistent, but we did not explore this. This solution has a number of components, as described in the following sections. 4.4.7.1 The C program In this case, the program is initiated from the UNIX environment, and it controls all the functions that take place. Typical logic is: 1. Connect to the Domino server using the Notes C API. 2. Open a Notes database. 3. Open the sequential file and read from it. 4. Write data into documents in the Notes database. 5. Exit. The program runs as a main program, rather than as DLL. 4.4.7.2 Environment For this environment, you will need a Domino server running on S/390, and also the libascii and Notes C API Toolkit packages, which are available for download from the Web at: http://www.s390.ibm.com/products/domino 4.4.7.3 Security When the C program accesses the Domino server, it will start a Notes session using the Notes ID file that is listed in the KeyFilename=xxxxxxx.id parameter in the server notes.ini file. If this ID file has a password, you will have to enter the password. You can avoid having to enter a password by registering a new Notes user and not giving it a password. Then change the KeyFilename parameter in the notes.ini file to the name of the new ID file that requires no password. On OS/390, the notes.ini file will have the KeyFilename field set to the server ID file (server.id). In this case, add a new field name ServerKeyFilename to the server.id file (ServerKeyFilename=server.id), then change the KeyFilename to the new ID file. 88 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products All accesses from the batch program to the Notes databases depend on the database access control list (ACL) settings for the user ID, specified in the KeyFilename parameter. 4.4.7.4 Skills required You see from this overview that you will need a number of skills available to make the connection between Domino and other applications using Lotus Notes C/C++ API toolkits. The key skills that you need are: • Notes administration: To set up Notes databases, set server parameters to allow agents to run, and set up the HTTP server component. • Notes application development: To develop the Notes forms, views and LotusScript code to provide application function and to call the connector code. • C/C++ programming: To code and test the C program that provides the connection in most of our samples. • Subsystem administration: To set up the subsystem to accept the connection from the C program. • Subsystem application programming: To develop the enterprise subsystem application (if not already available) or provide information on the interfaces to an existing application. • OS/390 system administration: To provide a Domino server test environment and appropriate security authorization. For more information about Lotus Notes C and C++ API Toolkits, installing sample code and other details, refer to Enterprise Integration with Domino for S/390, SG24-5150. 4.5 Integrating relational databases using @functions The Domino @functions are normally used on the client, which is not the focus of this redbook. Although @functions are not normally used in server-based agents, we provide some information for completeness. The Domino functions @DBCommand, @DBLookup and @DBColumn enable you to access RDBMSs. The @DB formulas are read-only, but provide an easy-to-use access to databases. The basic purpose of these functions is to create value lists for keyword fields. @DBLookup and @DBColumn can be used to query a relational database; @DBCommand is used only for executing stored procedures. Chapter 4. Introduction to programmatic connectors 89 @DBCommand does not return result sets. If you need a more customized and more complex query, LCLSX or LS:DO is a better option. Some of these functions inherently involve a delay before they complete. To set user expectations, it is sometimes a good idea to code the functions behind a button so that the user expects some delay before the function is completed. 4.6 How to use @DB functions The @DB functions are summarized in Table 3. Table 3. @DB functions Function @DBColumn Description Generates a keyword list. Returns a specified column for all rows in the specified table. Performs a lookup. Returns a specified column value in the row that matches the specified condition. Triggers stored procedures in the external database. Equivalent SQL SELECT DISTINCT column_name FROM table_name SELECT column FROM table WHERE condition (Any SQL statement) @DBLookup @DBCommand 90 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Part 2. Working with DB2 © Copyright IBM Corp. 2001 91 92 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Chapter 5. Setting up DB2 This chapter describes the steps to establish connectivity between Lotus Domino and IBM Database 2 (DB2) on OS/390. We used this environment to test DECS, LEI, LS:DO, and LCLSX solutions. If you already have an environment for accessing DB2 for OS/390 using a DB2 ODBC driver, you could skip this chapter. However, it also introduces our testing environment, which is needed to understand our samples and scenarios. 5.1 Preparing the environment Let us assume you already have DB2 installed on your OS/390 system, and that this includes the ODBC driver. This driver has been shipped with DB2 since Version 5. In our case, we used DB2 Universal Database for OS/390 Version 6. 1. First, check with your DB2 system administrators and OS/390 systems programmers for the name of DB2 subsystem. If there is only one DB2 subsystem in the OS/390 system image where your Domino is running, just remember its name. However, it is very likely that you will have more than one DB2 subsystem, or that you will need to access remote DB2 subsystems. In these cases, collect information about the DB2 subsystem names and which subsystem is the default for your OS/390 system. Note In order to access any instance of DB2 for OS/390, one instance of DB2 must run in the same system as your Domino server. If you need to access remote instances of DB2, you must enter appropriate information into DB2 communication tables. 2. Next, create a file into which the initialization information for the ODBC driver will be stored. We created this file in the /etc directory of our system. Note: Read carefully DB2 for OS/390 ODBC Guide and Reference for your DB2 version. It contains information about setting up an ODBC initialization file and explains its parameters. Our ODBC initialization file is shown in Figure 45 on page 94. © Copyright IBM Corp. 2001 93 /etc/odbcini Columns 00001 00072 ===> Scroll ===> CSR ***************************** Top of Data ****************************** ÝCOMMON¨ MVSDEFAULTSSID=DB2G DIAGTRACE=1 DIAGTRACE_NO_WRAP=1 ÝDB2V¨ MVSATTACHTYPE=CAF ÝSAMPDB¨ DBNAME=DSN8D61A **************************** Bottom of Data *************************** Figure 45. ODBCINI file sample Our DB2 subsystem is named DB2G in our sample. You should replace it with a subsystem name from your installation. We also limited our access to just the DSN8D61A database. You can leave this section out of the ODBC initialization file, or you can customize it according to your installation’s requirements. 3. Next, set up the environment where the ODBC initialization file will be exported as a environment variable. The ODBC driver for DB2 on OS/390 looks for the DSNAOINI variable. This has to point to the directory and file name of your actual ODBC initialization file. We used the .profile file of user EBBERS1 1 to export DSNAOINI: export DSNAOINI=/etc/odbcini 4. Finally, change the environment variable STEPLIB so that it contains names of DB2 for OS/390 load libraries. You can place the following statement in the .profile file of your Domino for OS/390 server user: export STEPLIB=DB2V610G.SDSNEXIT:DSN610.SDSNEXIT:DSN610.SDSNLOAD:$STEPLIB This statement points to DB2 load libraries containing ODBC DLLs and executable files, and to the main DB2 configuration module, DSNZPARM. 5.2 Verifying ODBC function Now you are ready to test whether your DB2 ODBC driver for OS/390 works correctly. Stop the Domino server and log off all connections using your Domino server user ID. This will enable all environment changes to be active. If you log on with the user ID assigned to the Domino server, you can see your environment by entering the export command. 1 User EBBERS1 is the user ID which runs our Domino/390 server. 94 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Verify that changes you’ve made are valid. Then restart the Domino server. Now you can start working with DB2 from the Domino server using any of the provided connectors. To verify ODBC functionality, you can use various methods. One way to do this is to run the sample ODBC verification program shipped with DB2 for OS/390, dsn8oivp. Another way is to use a utility shipped with Domino for S/390, such as LCTEST; see 3.4.1.1, “Testing connectors” on page 44. Note If you intend to use remote DB2 instances from Domino for OS/390, your local DB2 serves as a DRDA Application Requestor. You must update the appropriate communication tables to point to other DB2 instances, either on the same S/390 server or other servers. See DB2 for OS/390 Administration Guide for help. Chapter 5. Setting up DB2 95 96 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Chapter 6. Connecting to DB2 with DECS Now that we have set up our DB2 environment and our Domino server, we can use DECS as a connector between them. 6.1 Preparing DB2 to connect with DECS The name of the DB2 subsystem we used in building our activities is DB2G. The name of the database we used is DSN8D61P, and the name of the tablespace is DSN8S61A. We created RACF user IDs that are granted the necessary privileges to use these DB2 objects. We created a table named dsn8610.employee, into which we receive Notes data from DECS activities. These are the DDL statements we executed with SPUFI to create the sample table. CREATE TABLE DSN8610.EMPLOYEE( EMPNO CHAR(6) NOT NULL, FIRSTNME CHAR(15) , LASTNAME CHAR(15), DEPTNAME CHAR(30), EXPERTISE CHAR20), MAIL_ADDRESS CHAR(30), PHONE CHAR(30), SALARY DECIMAL(8,2)) IN DSN8D61A.DSN8S61P; 6.1.1 Creating the view A view is simply a virtual table. The data inserted in a view will actually be stored in an underlying table. In order to use the VIEW option in DECS, we created a view using the employee table definition. In our DECS scenario, our data source is a view rather than a table or a stored procedure. So our Notes database is connected to the view. The data can be viewed using a DB2 select. Our sample view is called DSN8610.EMPVIEW. The following DDL was used to create the view: CREATE VIEW DSN8610.EMPVIEW AS SELECT EMPNO,FIRSTNME,LASTNAME, DEPTNAME,EXPERTISE,MAIL_ADDRESS,PHONE FROM DSN8610.EMPLOYEE; We created the view without the salary column. © Copyright IBM Corp. 2001 97 6.1.2 The Domino sample application to communicate with DB2 We created a simple Notes database to show the different ways to integrate a Domino application with DB2 databases. It is an organization database that holds employee data such as names, photos, address information, expertise, and salary information. The application is kept simple to let us concentrate on the integration features. The database can be operated from a Notes client or a Web browser. Figure 46 shows the form that stores the employee data: Figure 46. Sample form Person All of the fields are text, except the income field (numeric) and the field picture (Domino rich text). Expertise is a multivalue field. We created a view in which the employee documents are categorized by department. See Figure 47 on page 99: 98 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 47. The employee view categorized by department 6.2 Integrating DB2 using DECS Since our application couldn’t include all the options and functions in DECS, we chose a subset and set up the following scenario. 6.2.1 Description of employee sync scenario In our sample scenario, we have a filled DB2 table containing existing employee information. The following steps tell how we can set it up. 1. We fill the DB2 table using a Domino Notes client as a front end. This could be also done by a Web browser. 2. We keep a subset of data in the Domino database, so we can show it in a Notes view. 3. When we open a Notes document, we fetch the rest of the dataset from the DB2 table, using DECS to display the information in a Web browser or a Notes client. 4. We then update the information and write it back to the DB2 database, keeping the fields used by the view in the Notes database. 5. If desired, we can delete rows in the DB2 table by deleting the corresponding document in the Notes database. 6. We set up this scenario using a DB2 table and view. Chapter 6. Connecting to DB2 with DECS 99 6.2.2 DECS setup using a table We created a DB2 connection document to our DB2G subsystem. We turned off data journaling and chose the EMPLOYEE_NO_BLOB Table created with Owner DSN8610. Figure 48 shows the connection document we created. Figure 48. DECS connection document After creating the connection document, we created the activity document. We selected the organization database, choosing the Person form. Then we selected the connection to the EMPLOYEE_NO_BLOB table. We defined the employee number as a key in both databases. We selected the field mappings, as illustrated in Figure 49 on page 101. 100 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 49. Activity settings For events to monitor, we chose all available. This allows us to create or insert data into the DB2 table, open or fetch data from the table, update data in the table, or delete data from the table. We left all the settings at the defaults, except the general setting of data storage. As illustrated in Figure 50, we wanted three fields to be visible in the Notes view in order to built a usable view. We chose the Notes fields firstname, lastname, and hierarchy of the department. This gave us a view of the employee names categorized by their departments. Chapter 6. Connecting to DB2 with DECS 101 Figure 50. General option settings (fields kept in Notes) 6.2.2.1 Problems we experienced At first, we experienced problems when we tried to map fields in the DECS activity document. As we pressed the Map Fields button, we had an overflow error message, as shown in Figure 51. The error resulted from the field level help we created in our Notes Application. DECS field mapping runs into an error if the Notes Application uses Field Level help where the characters exceed a certain amount. When we stayed below 60 characters, it worked fine. Figure 51. Error message when mapping with long field level help Two workarounds are available to solve this problem. 1. Reduce the field level help to less than 60 characters per entry. Execute the field mapping in DECS. After this you can reinsert the field level help. 2. Override the automatic field mapping in DECS by opening a few hidden fields in the Notes realtime form in the DECS administrator. Insert the field and column names manually. This method is described in Appendix E, “Workaround for manual field mapping in DECS” on page 253. 6.2.3 DECS setup using a view When the view was created, it looked empty, since there were no qualifying rows in the view. Then we created a connection document just as we did in 6.2.2; see Figure 52 on page 103. 102 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 52. Connection document to the DB2 EMPView We also created an activity called person_empview, shown in Figure 53. Figure 53. Activity using the DB2 EMPVIEW Chapter 6. Connecting to DB2 with DECS 103 6.2.4 Results of scenario Employee Sync Here we include some screenshots of our employee sync scenario. From the Notes database point of view, the results are the same, whether you connect to a view or a table. If we have a filled DB2 employee table, then we can activate the Initialize keys action, as shown in Figure 54. Figure 54. Activating the key initialization on the Notes database This will create a Notes document with the key field and the realtime fields to be kept in the Notes document, according to the previously-defined activity document, for each row of the DB2 table. As shown in Figure 55, the action causes a messagebox to display. Figure 55. Information message before initializing the keys in the Notes database The action completes with a message box informing us of how many Notes documents were created; see Figure 56 on page 105. 104 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 56. Success message after initializing the Notes documents with key fields If the initial DB2 employee table is empty, we populate it by inserting data. We use the Notes client or the Web browser, in combination with the DECS create event as activated in the activity document. Filling the DB2 table using the employee form in the Notes client occurs as shown in Figure 57. We have kept some information in the Domino database to show a subset of information in a view. Figure 57. Creation of data using a Notes client In this case we selected two expertises, Domino and DB2. We defined this field as a multivalue field in the employee form. Until now, we have not dealt with any multivalue settings in the activity document. So, as you can see in Figure 58 on page 106, we wrote these values into the DB2 table as one string with a comma as a separator. If you handle multivalue fields in this manner, you must dimension your corresponding DB2 column to be as long as all possible values put together. Chapter 6. Connecting to DB2 with DECS 105 Figure 58. Result in our DB2 table When you look at Figure 59, representing the Notes view of the created employee, you notice that only the fields we have defined in the activity document’s general settings (firstname, lastname and the department hierarchy) will stay in the Notes database and appear in the view. The other fields are deleted in the Notes database after being transferred to the DB2 table. Figure 59. View containing only a subset of data When you open a document (see Figure 60 on page 107), for example with a Web browser, all the fields of the corresponding EMPLOYEE_NO_BLOB DB2 table are loaded in real time into the Notes document. The expertises are again available as multivalue fields in Notes. Even though you can see the field contents of the Notes document using document properties, the content of all realtime fields will still be fetched from the DB2 table. 106 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 60. Fetch from Web using DECS After creating the row in the DB2 table, we could open the corresponding Notes document in the Notes client, update the fetched data and write the updates back into the DB2 table by closing the Notes document, which triggers the DECS update event. Once we create the DB2 rows, we can remove the rows by deleting the corresponding document in the Notes database. 6.2.4.1 Problems and error messages we experienced We experienced some errors working with the realtime fetch using the Web browser, regarding our ability to open documents. With the Notes client, we did not experience any problems. In our testing, perhaps due to time constraints, we were not able to get DECS to handle multivalue fields or BLOBs. Chapter 6. Connecting to DB2 with DECS 107 108 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Chapter 7. Connecting to DB2 with LEI In this chapter we describe how to work with LEI. We document all the connections we created and the activities that make use of them. However, we did not try all the parameter options, but instead just tried those that are generally used to construct activities. Every activity needs a connection document in order to connect to the enterprise data source. We describe how to create the connection and activity documents in Chapter 3, “Introduction to Lotus Enterprise Integrator (LEI)” on page 29. We suggest that you review it before you build, since we have not repeated the documentation to create connections and activity documents in this chapter. We chose Notes and DB2 as data systems. We used them as source, target, master, or non_master, based on the type of activity we built and the example scenario. When creating DB2 tables, we used the qualifier DSN8610. The fully qualified name of the table is DSN8610.tablename. We also created a synonym using just the table name. So, the table name alone can be used instead of a fully qualified name, or both can be used interchangeably. In the documentation, we used the fully qualified name in most places, but sometimes we used an unqualified table name. They both refer the same table. The following are the activities we tested • Command Activity • Direct Transfer Activity • Archive Activity • Replication Activity • Polling Activity Note: We did not emphasize the realtime activity of LEI, since Lotus recommends using DECS for this. © Copyright IBM Corp. 2001 109 7.1 Command activity The command activity connects to the host data system. To execute a connection-specific command, select the desired document that connects you to the enterprise data source. 7.1.1 What this activity is used for Command activity executes operating system, database and SQL commands. 7.1.2 Example scenario In our example scenario, a specific department such as Human Resources updates the enterprise database whenever an employee resigns. We assume that an application program updates the employee number to xxxx, as this program has only the privilege of updating the column in the database. The HR department schedules this activity (for example, weekly) to delete the employee records for all employee numbers that equal xxxx. We have created a second activity also, to insert the details of an employee into the enterprise database. This is to try another SQL command. In general, this activity can be used to execute any valid SQL command. 7.1.3 How we set up LEI for this scenario We created a DB2 table to test this activity. The name of our DB2 subsystem is DB3G, the database name is DSN8D61A, and the tablespace name is DSN8S61D. The following is the SQL we used to create the table SN8610.LEITAB. We used this table in more than one activity. CREATE TABLE DSN8610.LEITAB( EMPNO CHAR(6), FIRSTNME CHAR(15), MIDINIT CHAR(1), LASTNAME CHAR(15), DEPTNAME CHAR(5), SALARY DECIMAL(8,2), PHONE CHAR(15), MAILADDRESS CHAR(15)) IN DSN8D61A.DSN8S61D; To create a connection, here are the steps: • Choose Create Connection from the navigator. • Select the database type option from the menu. • Enter the required information in the Connection Definition form. 110 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products 7.1.3.1 Using LCTEST In case there are connectivity problems, use LCTEST to verify connectivity. It comes with Domino. Ours is located in the following directory: /usr/lpp/lotus/notes/latest/os390 At the shell prompt, enter: lctest Select option DB2 (option 6) to verify the connection. Supply the DB2 subsystem ID, MVS user ID, and password. If the test ends with an error message, then there is something wrong with DB2 connectivity. The same test can also be used to test Notes connectivity. For more details about lctest, refer to 3.4.1.1, “Testing connectors” on page 44. 7.1.3.2 Creating the connection document Click Create Connection (Figure 61) in the LEI navigator to create the new connection document. Figure 61. Connection icon in the LEI navigator The types of connectors available with LEI are displayed by selecting Create Connection. We selected a DB2 connection from the listbox in Figure 62 on page 112. Note: In this redbook, we connected to DB2 and Notes. These are the only available LEI connectors at the time of writing. Chapter 7. Connecting to DB2 with LEI 111 Figure 62. Listbox to select the connection to the enterprise data system We called our connection document “Command Activity Connection.” We entered our RACF user ID and password in the corresponding fields in the document and supplied the name of the database where the enterprise data object is created. In our case, it is the name of the DB2 subsystem, DB3G. We didn’t check the option for journaling data. Neither did we use a column called Category. If you want to categorize the connections you create, you can supply a comment for the connection document in the Comments column. For more information on these options, refer to the LEI online documentation. Select save & exit at the top left corner of the connection document, to save the document and exit to the LEI administrator. Figure 63 on page 113 shows our connection document. 112 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 63. Connection document for the command activity Click Connection options to view more options. We chose the commit at disconnect option. There are other options, such as table creation (you supply the DB2 database name where the connection creates the target metadata), performance, and logging. 7.1.3.3 Creating an activity document These steps outline the general procedure for creating an activity. 1. Open the LEI Administrator database, LEIADM.NSF. 2. Choose Create > Activity > Command Activity from the menu bar, or click Create Activity on the navigator pane. 3. Fill in the required fields and select the desired options for the activity in the Command Activity document, including its connections and scheduling options. Note that any connections you want to use in the activity must already exist and should have been tested with LCTEST. 4. Save the activity document. You can select the Run ASAP option to have the activity executed by the LEI server as soon as possible after saving the activity. The create activity icon in the LEI navigator looks like Figure 64 on page 114. Chapter 7. Connecting to DB2 with LEI 113 Figure 64. Create Activity Icon LEI prompts for the type of activity to be created. We selected a command activity. Figure 65 depicts the activity list box displayed by LEI. Figure 65. Activity listbox LEI displays the activity document with empty fields. We named our activity command activity. We selected RunASAP option from the actions list. In your applications, you may schedule the activities for a specific time, using the scheduling parameters in the activity document. Since this activity will delete the details of employees whose numbers equal xxxx, we entered an SQL statement to achieve this: DELETE FROM DSN8610.LEITAB WHERE EMPNO=’xxxx’; Figure 66 on page 115 shows our activity document. 114 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 66. An activity document to delete an employee There is a Log Link button on the activity document. You can select this to view the LEI log. 7.1.4 Parameter options set for this activity The general options in the activity document are meant for the designated LEI server and the operating system priority. We did not choose the designated server, as we have only one LEI server installed. The name of our LEI server is ITSOLEI. The OS priority is always set to medium. We did not address the dependent activities option. The maximum duration of the activity can be set to a preset time interval. We let this activity Run ASAP with all the time it needs to complete. However, you might want to set a time period beyond which you do not want this activity to continue. The scheduling options are self-explanatory. We did not schedule it to any particular time. We ran this activity using the Run ASAP option in the Actions menu. Figure 67 on page 116 shows the options we selected in our activity. Chapter 7. Connecting to DB2 with LEI 115 Figure 67. Command activity with general and scheduling options We selected the Save&exit button in the top left corner of the document. Make sure that you cannot run the activity unless you save it. Next, click Actions in the dropdown menu and select Run ASAP in order to run the activity. By clicking Log link, you can view the LEI Server log to check the status of the activity. If you open the activity after a run, the log shows the time it ran along with the result; that is, whether the activity ran successfully or ended with an error. You can also check the result of the activity by viewing the DB2 table, using SPUFI or a DB2 client, to see whether it deleted the specified rows. In our case, we ran an SQL statement in SPUFI and found that the activity deleted the row with empno=’xxxx’. We also created this activity with another SQL statement to insert a new row into the table. We created the DB2 table to accept rows with duplicate values. So, every time we ran this activity, one row was added to the table with the column values supplied in the SQL. Figure 68 on page 117 shows the activity document with the SQL insert statement. 116 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 68. Activity document with insert SQL statement After successful execution of the activity, we queried DB2 and displayed the row inserted by the activity. Figure 69 is from our DB2 table, showing this row. Figure 69. Row inserted into DB2 table using the command activity 7.2 Direct transfer activity Direct transfer reads data in the source and copies it to the destination. The source data is unchanged. If the overwrite option is selected, the target data is deleted and the source data is transferred. The target is then a copy of the source. 7.2.1 What this activity is used for This activity copies data from one database to another. The default behavior is to append data. The activity needs to identify the source and destination databases. The candidate data can be selected using a Notes selection formula or an SQL statement. The overwrite option is also available, which deletes all the existing data in the target database and adds data that meets the selection criteria. Chapter 7. Connecting to DB2 with LEI 117 7.2.2 Example scenario We used a travelling salesperson scenario. On the host is a DB2 database with data about different companies. Using an LEI activity run, the salesperson gets a subset of the data about one customer. For example, he would like to look through the service history of the customer before calling about a new deal. The salesperson can take the data with him in an offline Notes database. We created a fictitious company and named it EXON. We built an activity with the following predicate, to transfer only the data about EXON to the target: company_name=’EXON’ A successful run of this activity copies all the data for that company to the Notes database. The salesperson can view just the data he is interested in. 7.2.3 How we set up LEI for this scenario We selected our source database as DB2 and our target as Notes. We used a simple SQL to select the data that we transferred to DB2. This activity required two connection documents, a source and a target database connection. Since our source is DB2, we created a new connection to DB2. We named it “Direct Transfer.” We could have used an existing connection to DB2 as well. We used the same DB2 table (LEITAB) that we used for the command activity. We created a Notes database that matched the field types of the source. For more details about this database, refer to 6.1.2, “The Domino sample application to communicate with DB2” on page 98. This is used for all our activities that involve a Notes database. The SQL we supplied in the activity document filters the data. If we wanted to reverse the direction of data transfer, then we could choose DB2 as the target and Notes as the source. In that case, the Notes selection formula would control the data that is being sent to the target. We created a new Notes connection for building this activity by selecting Notes from the connections display list. Figure 70 on page 119 shows the scenario. 118 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 70. Connector list 7.2.3.1 Creating a connection document The next step is to create the connection document. We selected our Notes database from the list in the LEI connection document. We named our Notes connection document “Notes direct transfer”. Figure 71 shows the details. Figure 71. Creating a Notes connection document Chapter 7. Connecting to DB2 with LEI 119 Note The Notes database must have been created before you select it in the connection document. 7.2.3.2 Creating a transfer activity The next step is to create the activity that performs this transfer. Click Create activity in the LEI navigator to open the new activity document, then fill in the required fields in the document. We named our activity “Direct transfer from DB2 to Notes.” Click Select metadata to fix the source and target databases. Next, click the dropdown button at the connection name that displays the list of connections. Select the connection names created for this activity; for example, the DB2 connection name and the new Notes connection name. Once this selection was done, we selected the name of the actual table from the list of tables displayed by LEI. We also selected the Notes form from the list in the Notes database display. Click metadata again to display the forms available under this Notes database. We chose the person form that was created for this example. We chose target in the metadata fields display. This display will show you only source and target at first. Once you make this selection, then LEI displays either Notes forms or DB2 tables, depending on where the cursor was placed at the time of your selection. Figure 72 shows how to select the DB2 table. 120 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 72. Direct transfer activity document showing the DB2 table selection We selected the table created for this example: dsn8610.leitab. The next step is to select the Notes database that receives the data from DB2 table. We selected the person database, as shown in Figure 73 on page 122. Chapter 7. Connecting to DB2 with LEI 121 Figure 73. Direct transfer activity showing the Notes database selection Once the source and target selection is completed, then the respective data objects names can be seen in the document. 7.2.3.3 Mapping the fields Now, it is time for field mapping. This can be done in more than one way. Either we select automatic field mapping, based on field names or position, or we can manually map the fields. We selected the manual mapping. In order to manually select the fields, use one of these two methods: • LEI displays the list of available of source and target fields. Select a source field by clicking on the field name. Follow this with a corresponding field from the target. or • Click the names of the chosen fields in the source list, then in the target list, in the proper mapping order. The first source field you choose maps to the first target field, the second to the second, and so on. If you mark Automatic, data is mapped from each source column to the destination by column sequence: first column to first, second to second, third to third, and so on. 122 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products We selected six fields for this activity. Table 4 shows the fields we selected for mapping: Table 4. Manually mapping LEI fields Source FIRSTNME LASTNAME DEPTNAME MAILADDRESS PHONE Target FirstName LastName Hierarchy MailAddress OfficePhoneNumber Figure 74 shows you the details: Figure 74. Direct transfer activity showing the field mappings We inserted rows in DB2 with the deptname as EXON. We expect the activity to transfer all those rows to Notes database. However, we have not selected all the available fields in the mapping. Hence, only the corresponding values get transferred to Notes, leaving all other fields empty. Figure 75 on page 124 shows our DB2 source with the rows that match the condition deptname=’EXON’. Chapter 7. Connecting to DB2 with LEI 123 Figure 75. DB2 table showing the EXON rows Notice that we did not map all the available fields. After choosing the scheduling options, we saved the activity document. To execute the activity, we selected the Run ASAP option from the actions menu. The activity completed successfully by sending the rows that match the predicate in the SQL statement to Notes database. This is our SQL statement for the direct transfer activity. SELECT * FORM DSN8610.LEITAB WHERE DEPTNAME=’EXON’ You can view the LEI log by double-clicking Log on the activity document or selecting log from the LEI navigator. Figure 76 on page 125 is the log after a successful execution of the activity. 124 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 76. LEI log for the direct transfer activity We created a Notes application with views to check the data. Figure 77 shows the Notes documents transferred from DB2. Figure 77. Notes documents from DB2 using direct transfer There are more parameter options, such as performance, general, and scheduling. For details on these, refer to the LEI online documentation. 7.2.4 Parameter options selected for this activity We did not schedule the activities for any particular time. We selected the same options as in the command activity. Although we used the Run ASAP option to start the activity, we could have chosen some of the scheduling options in the activity document. Chapter 7. Connecting to DB2 with LEI 125 7.3 Archive activity The archive activity is useful as a one-way move, where you want to store data at the target and free disk space at the source. It deletes original records from the source. 7.3.1 What this activity is used for The archive activity moves data from one database to another. The records can be selected by a conditional statement or relative timestamp. Archive deletes the source records. It can be used when migrating from one database to another or when offloading outdated data to storage which is infrequently accessed. This activity can be used in combination with other LEI activities, such as polling, to trigger an archive upon the occurrence of an event or condition. 7.3.2 Example scenario We decided to move seldom-used data from Domino to DB2. We selected the Notes database called “person” as our source and DB2 as our target. We moved the six documents that had been previously transferred from DB2 to Notes during the direct transfer. The archive activity deleted all the documents from the Notes database after successful execution of the activity and archived them in the DB2 table DSN8610.leitab. We recommend using DB2 as the target because it can handle higher volumes of data than Notes. 7.3.3 How we set up LEI for this activity We selected Create Activity in the LEI navigator. For an archive activity, we need to have two connections, one for source and the other for the target. We used the existing connections and did not create new connection documents. We used the Notes connection named “person” as our source and the connection named “direct transfer” as our target. Figure 78 on page 127 shows the connection document for the Notes connection. It uses the Notes database called “person.” 126 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 78. Connection document “person” Click Create activity from the LEI navigator. From the list of types of activities, select Archive. We named our activity as Archive from Notes to DB2. We mapped the corresponding fields from the source and target databases. We did not select all the fields, but selected only the following from source to map to the target. Table 5. Mapped fields for archive activity Source Hierarchy EmpNo Expertise FirstName LastName MailAddress Target DEPTNAME EMPNO EXPERTISE FIRSTNME LASTNAME MAILADDRESS In the archive options, we did not select the Metadata creation option to create target metadata, because we chose to use a table that was already created by us in DB2. However, we tried this later while testing the activity with DB2 as source and Notes as target. LEI created a Notes database with the name supplied by us against the form name in the activity document. In a Notes view, we found that LEI archived data in the newly created database. For field names, LEI uses the ones you supply in the mapping. Chapter 7. Connecting to DB2 with LEI 127 We used a condition clause empno <>”” to refine the data. The activity document was saved and we used Run ASAP to run the activity. As a result of the successful execution of the activity, the Notes database became empty (it had only the six documents copied by direct transfer) and the data was moved to the DB2 table. Our DB2 table already had six rows, so as a result the number of rows is doubled to 12; six duplicate rows are appended by the archive activity. Figure 79 shows our activity document. Figure 79. Activity document showing the archive activity After successful execution of the activity, we used a simple select SQL query in DB2 to view the archived data. Figure 80 on page 129 shows our DB2 table. Notice the data from Notes archived to DB2. 128 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 80. DB2 table with appended rows from the archive activity In Figure 80, the six rows at bottom of the table came from Notes. Notice that all six rows have NULL values in the phone column. This is because when we mapped the fields in the activity document, we did not map the phone column from source to target. So DB2 assumed NULL values, displayed as a dash (-). We also mapped the expertise column from source to target. But we did not include it in the SQL select, because we could not fit the results on the page of this book. However, the values of the expertise column are also NULL. This is because, in our direct transfer activity, we had not chosen the expertise field, so Notes did not receive any values for that column and hence returned no values to DB2. Note We created the table dsn8610.leitab to assume NULL values for any values which are not supplied. We selected the expertise column to check the values in a separate SQL query and found that there are NULL values for the archived rows. Chapter 7. Connecting to DB2 with LEI 129 7.3.4 Parameter options selected for this activity We did not select timestamp archiving, so all the documents transferred to DB2 got deleted from Notes. However, LEI displays a message box to alert you when the activity is not timestamp archiving; see Figure 81. Figure 81. LEI alert on not selecting timestamp archiving We selected Yes to move the Notes documents to DB2. However, we used a conditional clause to refine the data selected for archiving. If there are any documents in Notes with employee number as blank, those documents are not archived. 7.4 Replication activity Replication synchronizes databases by updating data from one into the other. Note: Replication by DECS is not synonymous with Notes replication. Whereas Notes replication updates both databases equally, DECS replication updates are controlled by master-nonmaster parameters. 7.4.1 What this activity is used for Replication is used to synchronize data in two databases. It merges data from one data source into another data source. A condition can be placed in the replication activity document to refine the result set. The two types of replications are: • Primary key replication • Primary key/timestamp replication 7.4.2 Example scenario We chose a DB2 database as the master. We assumed that the Human Resources department updates the database whenever a new employee joins the company. We selected a Notes database as non_master. It is used by other departments, such as sales and marketing. These departments want the 130 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products information about new employees joining the company. The activity replicates the DB2 database with Notes, providing the departments with details of the new employees. The frequency of the replication is once per day and the activity keeps both DB2 and Notes databases in sync. However, the changes made to the non_master will not replicate to the master. In our example scenario, we chose DB2 as master and Notes database as non_master. 7.4.3 How we set up LEI for this activity We used two databases to build this activity. The Notes database “person” is the same one used for the previous activities. We created a new DB2 table, lei_master. It is different from leitab, because it has a primary key, a unique index on the primary key, and an extra column called ‘joining_date’ of type date. We used this new table to explain the polling activity, so we need this additional column. Here is the SQL we used to create the table: CREATE TABLE DSN8610.LEI_MASTER( EMPNO CHAR(6) NOT NULL PRIMARY KEY, FIRSTNME CHAR(15), MIDINIT CHAR(1), LASTNAME CHAR(15), DEPTNAME CHAR(5), SALARY DECIMAL(8,2), PHONE CHAR(15), MAILADDRESS CHAR(15), EXPERTISE CHAR(15) JOINING_DATE DATE) IN DSN8D61A.DSN8S61D; CREATE UNIQUE INDEX ILEI_MASTER ON DSN8610.LEI_MASTER(EMPNO); Table lei_master accepts no duplicate values in the empno column. We inserted some rows in the lei_master using a DB2 client. We also created a synonym for this table. We can use the table name rather than the fully qualified name. The following SQL creates a synonym CREATE SYNONYM LEI_MASTER FOR DSN8610.LEI_MASTER In order to build and test the activity, we need to insert few sample rows into the table. Chapter 7. Connecting to DB2 with LEI 131 We can execute SQL using SPUFI or the Command Center in the DB2 Connect client. As an alternative, we can use the command activity (see 7.1 on page 110). After entering the SQL shown in the screen shots on the previous page, we would click Run ASAP to create a new DB2 table and a synonym. Figure 82 shows our data in lei_master. We used the DB2 Connect Command Center to insert rows into the table. Figure 82. Data in table lei_master You can build the replication activity with either primary key or primary key/timestamp replication. We tried the former with the following scenarios: • Notes as master and DB2 as non_master • DB2 as master and Notes as non_master • No master In the first two scenarios, the master always wins the conflicts. But in the third scenario, it does not update either connection on replication conflicts. In the first scenario, if we add new documents to the Notes database, they are replicated into the DB2 table during a successful run of the activity. If we delete one or more Notes documents or update the existing documents, the non_master replicates all of them during successful execution. The activity works in the same way when we reverse the connections and choose DB2 as master and Notes as non_master. 132 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products When we choose the no master option and update both the databases before running the activity, we find that none of the updates are replicated, even though the activity completes successfully. 7.4.3.1 Creating the Notes connection Compared with the creation of earlier connections, the only additional option we chose when building this connection is the name of a Notes view. It was already created for viewing the Notes documents. We specified it because the replication activity creates the required view by default if a Notes view name is not supplied. We found a warning about this in the LEI log. In the connection options of the connection document, there are suboptions such as general options, document selection, field selection, data transformation, and data creation. To select the view, we select the document selection options, then click View to use for selection for a list of Notes views. Figure 83 shows our Notes connection document. Figure 83. Connection document for the replication activity 7.4.3.2 Creating the activity Click Create activity. Fill in the options displayed. We named our activity “Replication Activity(DB2-Notes).” Chapter 7. Connecting to DB2 with LEI 133 We supplied two connection names, to connect to Notes as well as to DB2. We selected already-existing connections from the connection display box. We chose “Notes direct transfer” to connect to Notes and “Direct transfer” to connect to DB2. We selected “person” as the Notes database and “lei_master” as the DB2 table. In the activity document, there are radio buttons to specify which one is master. We can select either Connection A or Connection B, and the other connection becomes the non_master. However, if we choose the third option, Skip Conflicts, then we enter the “no master” scenario. We can select different options once the activity is executed successfully with one set of options. We selected Connection B as master. So DB2 is our master database and Notes is non_master. We did not chose automatic field mapping. We selectively mapped the fields by supplying the key field names. We used empno as our key field in both master and non_master databases. In actual field mapping, you can select the fields of interest by clicking the corresponding fields. We did not select the timestamp replication for this activity, and for the remaining options we selected only the default values. We could have tried more options with our activity building. We selected Save&exit before we selected Run ASAP. Figure 84 shows our activity document. Figure 84. Activity document for the replication activity 134 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 85 shows the mappings of the fields selected for replication. Figure 85. Replication activity document showing the field mappings Make sure that you map the key fields when prompted, and then map the other fields. Also, note that the key field is also mapped in the source field list. Initially the Notes database is empty, because we deleted all the documents in order to try this activity. Our DB2 database is shown in Figure 82 on page 132. We chose Run ASAP from the Actions menu to run the activity once and stop. Figure 86 shows the LEI log for the activity. Figure 86. Activity log showing six rows replicated into the Notes database Chapter 7. Connecting to DB2 with LEI 135 Notice the SQL SELECT statement in the LEI log. In order to include it in the log, you need to select output SQL statements to log in the logging options while creating the connection document for replication activity. Figure 87 shows the view from our Notes database after successful execution of the activity. Figure 87. Notes database “person” after replication We can delete or update the Notes documents, then run the replica activity. We find each time that the Notes database is a replica of the DB2 database (master updates non_master). But once you delete some rows in the master, then it gets updated in the Notes database to keep both master and non_master in sync. We inserted a new row in DB2 to test the replication activity. The following is the SQL used to insert the new row. INSERT INTO LEI_MASTER VALUES('E0_NEW','Howard','S', 'Stone', 'IIS',2678.00,' 3-1456','Howard@IBMUS','Domino','2000-11-11'); After successful insertion, we can look at the rows in the table to make sure that the new row was added. Figure 88 on page 137 shows the DB2 rows after inserting a new row. 136 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 88. DB2 table after inserting a new row Now the master database is different from the non_master, because it has a new row in it. We again used RunASAP to execute this activity. After successful execution of the activity, we found that the new row is replicated in Notes. Notice the LEI log for this activity. It fetched seven rows from DB2 (the six original rows plus one new row) and six documents from Notes (the original six rows from the first replication) making a total of 13. The activity replicated seven (6 original rows +1 new row) records to Notes. Figure 89 on page 138 shows the details of replication in the LEI log. Chapter 7. Connecting to DB2 with LEI 137 Figure 89. LEI replication activity log after inserting new row in DB2 table After successful execution of the activity, you can find the new document in Notes. Figure 90 shows our Notes database after replication. Notice the new row added to the non_master. Figure 90. Notes database “person” after replication 7.4.4 Parameter options selected for this activity We selected Log key values on error option from Logging. Make sure that Enable Logging and Buffer Logging are selected for the activity. These two options are selected by default. You need to select the remaining options to suit your requirements. 138 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products 7.5 Polling activity Polling activity triggers another activity. It can trigger more than one activity configured in separate activity documents. 7.5.1 What this activity is used for This activity runs on a scheduled basis. It triggers other activities based on the occurrence of a condition. The polling activity must remain open as long as necessary. The triggering activity depends on the occurrence of some action or event, not on the frequency of the polling activity. The polling document does not contain the instructions to execute. Instead, it triggers one or more activities listed in the polling activity document. Upon the occurrence of the event, the listed activities in the polling document get executed. Unlike other activities, which continue to run past any defined stop time until they complete, a polling activity runs until stop time then ceases. The start and stop times of the polling activity are set in the scheduling options in the document. 7.5.2 Example scenario We assumed an example scenario where a DB2 table keeps track of the employee data. Whenever a new employee joins the organization, the Human Resources department updates the DB2 database with the details of the new employee. Other departments, such as Sales and Marketing, also need this information to be replicated in their notes database.The joining date of the employee is the date they joined the company. We chose the comparison of the date and the joining date of the employee as the condition for running the polling activity. This triggers a subordinate activity that updates the Notes database. Whenever the date equals the joining date of the employee, the subordinate activity is polled. The polling activity is scheduled to run between 9:00AM and 6:00PM. If an entry is made into the HR database with the joining date as today’s date, then this triggers an activity that automatically replicates DB2 databases with Notes databases that are shared by other departments. 7.5.3 How we set up LEI for this scenario We identified a subordinate activity that is triggered by the polling activity. We named our polling activity as “polling activity.” We identified the subordinate activity as the replication activity. We used SQL as the trigger statement with the following condition: joining_date = current date Chapter 7. Connecting to DB2 with LEI 139 If this condition is true, then the polling activity automatically triggers the replication activity to synchronize both master and non_master databases. Note The subordinate activities must have been defined and tested before they can be used in the polling activity document. 7.5.3.1 Creating the activity document You can use any of the existing connections. We chose to use “DB2 connection” to connect to DB2, as the trigger statement triggers the subordinate activity based on the data updates in the DB2 table. We named our activity as “Polling Activity.” Click the dropdown box against connection in the activity document to select the connection from the connection list box. Move the cursor to the trigger statement and enter your own trigger. In the trigger statement, we used the following SQL statement: Select * from dsn8610.lei_master where joining_date = CURRENT DATE In order to supply the table name, click metadata, and select OK when connection to poll is displayed. The next screen shows the list of tables we can use with the connection name we chose. We selected the table name dsn8610.lei_master. The condition is satisfied only when the statement produces a result set containing at least one row. This is considered to be a successful poll. Note CURRENT DATE is a DB2 register. It always has the current date stored in the register. In the Polling Frequency option, we choose a 60-second period. Hence, the activity polls every 60 seconds between the scheduled time period set in the scheduling options. In the Activities to Execute option, we selected the name of the activity, “replication activity,” to be executed upon meeting the specified condition. 140 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products The next option in the activity document is Execute Synchronously. Selecting this option suspends polling until the triggered activity is completed. We did not select it. Hence, the polling and subordinate activities cannot execute simultaneously. This is because if the subordinate activity fails, the polling activity can not resume. We did not supply any post statement for the Reset Trigger option. In the Event Handling option, we asked DECS to generate any polling errors. In the Basic Scheduling options, since the polling frequency is already selected, we did not need to select any interval. However, in the Advanced Scheduling options, we selected the option Start Date and Time as 9:00AM and End Date and Time as 6:00PM. So the activity starts polling between these times every 60 seconds. Figure 91 shows our activity document. Figure 91. Polling activity document We saved this document and selected Run ASAP to start the document. The activity starts polling every minute. We updated the DB2 table lei_master with the following SQL statement: INSERT INTO dsn8610.LEI_MASTER VALUES('NewEmp','Anil','S', 'Kumar', 'ACAS',2678.00,' 3625','Anil@IBMIN','CICS','2000-11-16');. Chapter 7. Connecting to DB2 with LEI 141 Figure 92 shows the DB2 table after inserting the new employee with joining date as current date. Notice the new employee with empno NewEmp; it is the last row in the table. Figure 92. DB2 table after inserting the new employee As the current date (we ran this activity on 16 Nov. 2000) matches the joining date of the new employee, the polling activity triggered the replication activity. You can also use the DB2 CURRENT DATE register to insert, instead of the date supplied in the form of a character in the following SQL. So today’s date gets substituted for the joining date field. The following screen shows you the SQL. INSERT INTO DSN8610.LEI_MASTER VALUES('NewEmp','Anil','S', 'Kumar', 'ACAS',2678.00,' 3625','Anil@IBMIN','CICS',CURRENT DATE); Figure 93 on page 143 shows the Notes database with the new employee. Notice empno NewEmp, the first document at the top of the database. 142 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 93. Notes database showing the replication activity As the polling activity triggers the replication activity, LEI writes log entries for the replication activity. Notice the log for the polling activity in Figure 94. Figure 94. LEI log for the polling activity Chapter 7. Connecting to DB2 with LEI 143 Notice the SQL statement in the LEI log. This statement must return at least one row to trigger the subordinate activity. We inserted one row in DB2 table that satisfies the condition. As a result, the replication activity was triggered. Figure 95 shows the LEI log for the replication activity. Figure 95. Replication activity log triggered by polling activity) Notice that the totals in Figure 95 are different from the replication activity log shown in Figure 89 on page 138. This is from the new row that triggered the replication activity, bringing the total number of records in Notes to eight. 7.5.4 Parameter options selected for this activity Notice the Advanced Scheduling options in Figure 96 on page 145. We scheduled the activity to start at 4:00 PM and stop at 6:30 PM. That is the time we tested this activity. Also, notice the option Polling Frequency in Figure 91 on page 141. The activity polls during the scheduled time period at a frequency of 60 seconds. That means it polls once each minute. 144 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 96. Polling activity parameter options 7.6 Realtime activity We did not write a scenario involving realtime activity. Lotus recommends using DECS for the realtime activity. Support for LEI realtime could be removed in the future. Chapter 7. Connecting to DB2 with LEI 145 146 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Chapter 8. Accessing DB2 with programmatic connectors This chapter deals with connectors that provide programmatic access from Domino to DB2 databases. In this redbook, we show how to use S/390 server-based connector code, including LCLSX and LS:DO, to access enterprise systems. This eliminates the need for each client to have connector code and client software for each server application. Of course, the code can be run with minimal changes on a client, for example, on an enterprise client such as DB2 connect. In the programmatic category, Lotus focuses its development efforts on the LCLSX connectors, so we will focus on them also. 8.1 Running LotusScript agents on the Domino server In this chapter, we discuss script code executing on the Domino server rather than the client workstation. However, the scripts are started synchronously using a Notes client or Web browser. This means the user will not notice that the script runs on the server. This technique has the advantage of not needing any enterprise client software on the user’s workstation beyond the standard Notes client or Web browser. However, this technique may not be suitable for some applications (for example, if many clients access the server simultaneously, because of performance limitations when accessing large amounts of data in parallel mode) but has the advantage of allowing thinner clients, which are easier to maintain. When running a LotusScript agent on a server using the “run on server” method, invocation is done from the Notes RPC instead of the agent manager. 8.1.1 Configuring Domino for multi-threading By default, Domino runs only one copy of a script at a time, queuing additional requests. If you want to enable multiple users to run your script at the time (called multi-threading), you must use the notes.ini statements described below. Be aware of agent runtime synchronization issues with sequential agents. 8.1.1.1 DominoAsynchronizeAgents statement Add this line to notes.ini on the Domino server to enable multi-threading: DominoAsynchronizeAgents=1 © Copyright IBM Corp. 2001 147 If you omit this statement, the value defaults to 0 and multi-threading is disabled. 8.1.1.2 ODBCThreadSafeDrivers statement Your ODBC driver manager and drivers must be thread-safe to run in a multi-threaded application. Consult with your ODBC supplier to verify that the driver is thread-safe, particularly if the ODBC package is not at the 3.0 standard. If all the ODBC drivers you are using are thread-safe, add this statement to notes.ini on the Domino server: ODBCThreadSafeDrivers=ALL If none of the ODBC drivers you are using are thread-safe, add this statement to notes.ini on the Domino server: ODBCThreadSafeDrivers=NONE If you have a combination of thread-safe and non-thread-safe drivers, you can still set up a multi-threaded environment by identifying which drivers are thread-safe and which are not, using the following two statements: ODBCThreadSafeDrivers = driver-name [, driver-name] ODBCNonThreadSafeDrivers = driver-name [, driver-name] LS:DO uses the appropriate type of threading for each driver, based on these statements. If you do not specify whether a driver is thread-safe or not, LS:DO assumes that is not thread-safe. 8.1.2 Agent Manager debugging and logging information Developing an agent on a server makes it hard to debug, especially since the debugger runs only on the client workstation. To collect information about what is happening during runtime, you can configure the agent manager to provide different levels of detail logging of the agent activity. You can specify that the Agent Manager record debugging information in these ways: 1. Specify Debug_AMgr=* in notes.ini, where the option * lists the information for all options Use this statement to provide debugging information about agent loading, scheduling, and performance. When you specify Debug_AMgr, you can later change the settings by using the tell amgr_debug command at the Notes console. 148 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Note If you specify that the Agent Manager should display all debugging information, performance can be significantly affected. After you specify Debug_AMgr in notes.ini and you run an agent on a server, check the Notes console and Notes Log for the debugging information. Optionally, you can redirect the information to be recorded in a separate file on the server; however, this can affect performance. To redirect information, edit notes.ini and add the following statement: DEBUG_OUTFILE= If you run an agent against a database stored on your local workstation, you must redirect the output because the Notes console is only on the server. To specify that the Agent Manager should record less debugging information than with Debug_AMgr, edit notes.ini and add the following statement: 2. Specify Log_AgentManager=1 in notes.ini Use this statement to provide a subset of the debugging information recorded with Debug_AMgr. Log_AgentManager does not affect agent performance as much as Debug_AMgr could. If you specify both statements, the Debug_AMgr settings take precedence. For detailed debugging, you can execute the code on the client and turn the debugger on. Or you can use the notes.log on the server, along with the print statement. You can also use the agent log class. See the Domino Designer Help for details. 8.1.3 LotusScript on the Web A Web agent can be written in LotusScript. This is the only context in which a Web application can use LotusScript. Anything that runs in the browser, such as an action, hotspot, or event, cannot contain LotusScript. We access DB2 in the form of reading, updating, inserting, and deleting datarows from tables. LotusScript agents activated from the Web cannot use any of the classes: NotesTimer, NotesUIDatabase, NotesUIDocument, NotesUIView, or NotesUIWorkspace. Chapter 8. Accessing DB2 with programmatic connectors 149 8.2 Integrating DB2 using LCLSX programming In this section we describe how we used plain LCLSX programming without running a declarative tool (such as DECS or LEI). The examples need code written in LotusScript. 8.2.1 Business scenario: online employee retrieval We wrote a scenario to illustrate fetching data from DB2 using keyed retrieval. It uses the same employee database as described in Chapter 6, “Connecting to DB2 with DECS” on page 97. It also uses the same table, called EMPLOYEE_NO_BLOB. In this example, we retrieve employees by their last names. We don’t need to keep any information or key values in the Notes database, as we did with DECS. The database is completely empty and we don’t have any indexes in the background, unlike our DECS example. This means there are no limits on the size of the DB2 table. In this scenario, the DB2 table is completely separate from the Notes database. We issue the search by pressing a button in the navigator pane using the Notes client. A window pops up asking for the employee’s last name to retrieve, as illustrated in Figure 97. Figure 97. Executing a retrieval by Employee’s Lastname After issuing the lastname, the database is searched for all entries having this last name. One document is created for each row. The results can be viewed after refreshing the screen, and are shown in Figure 98 on page 151. 150 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 98. Result of retrieval by lastname “Gart” 8.2.2 Fetching data from DB2 There are four methods of querying across a connection, as described previously: Catalog, Execute, Select, and Call. The catalog operation is used to return intermediate information within the external system; for example, the tables of a DB2 database or the columns of a specific database table. For a complete list of Catalog options, see the Catalog method in the LCLSX for Lotus Connectors manual. The remaining methods (Execute, Select, and Call) create result sets of data from the connection. The methods differ significantly in their interface: • The execute statement uses a connector-specific command statement to determine the contents of the result set. This interface is helpful when the external system command structure is familiar and when cross-connector portability is not an issue. • The select method uses a combination of key names, values, and condition flags to indicate the desired contents of the result set. This interface works across connectors and does not require knowledge of the connector's command language. • The call method is similar to select, but is used for calling host procedures or functions. Instead of keys, parameters are provided. The keyed retrieval uses a key fieldlist, which determines the row of the table which is the key and the value of the key. The key can either match exactly or be greater or less than a specific value. We experienced code page conversion errors while trying to fetch data using a Connection.Execute statement, which sends an SQL statement to the DB2 Chapter 8. Accessing DB2 with programmatic connectors 151 database. For this reason, we chose the keyed retrieval method to fetch data from the DB2 table. 8.2.3 Code enhancements in the sample employee application For this example, we took the sample application created for DECS in Chapter 6, “Connecting to DB2 with DECS” on page 97. We added a button hotspot and an agent which is executed on the S/390 Domino server. We used the RunOnServer method, passing parameters in an agent parameter document. To illustrate how to code a keyed retrieval on a DB2 table, we show the code of our example application block by block. The code can also be viewed as a unit in Appendix C, “Sample LotusScript agent code” on page 221. 8.2.3.1 The search employee button For the click event of the button, the following code was created: Sub Click(Source As Button) Dim session As New NotesSession Dim db As NotesDatabase Dim Agent As NotesAgent Dim ParmDoc As Notesdocument Set db = session.CurrentDatabase key$ = Inputbox$("Enter the Employees Lastname")<-Prompting for Lastname In the following block, the parameter document is created, the lastname is written in the LCkey field, and the document is saved to the current database residing on the server. The agent must run on the same server. The agent reads the LCkey field after the document is saved, to get the key for its retrieval. ' Create Parameter Document for Agent Set ParmDoc=DB.Createdocument ParmDoc.Subject = "Agentparameterdoc" ParmDoc.LCkey = key$ Call ParmDoc.Save(True, False) In the following lines, we call the Agent that executes the fetch. We include the ID of the parameter document containing the lastname as a parameter in the call. ' Get Agent and Run it on the Server 152 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Set Agent = db.GetAgent( "Get Emps keyed") Print " . . . DB2 Fetch Agent running " status = Agent.RunOnServer(ParmDoc.NoteID) If status = 0 Then Print " DB2 Data Fetch Agent executed successfully" End Sub 8.2.3.2 The search agent An agent called Get Emps keyed containing the following code is created in the employee database residing on the S/390 Domino server. The first step in writing the script is to load the LotusScript Extensions for Lotus Connectors. The UseLSX statement accomplishes this step. Additional options may be used to check variables, simplify string comparison, and so forth. Uselsx "*lsxlc" The remainder of the script is located in the Initialize event of the agent. Errors are logged by issuing a print to the notes.log. The error handler is initialized and the following Notes objects, including the agent parameter document, are declared: On Error Goto Handler ' Declare Notes Objects Dim NSession As New NotesSession Dim DB As NotesDatabase Dim Agent As NotesAgent Dim count As Long Dim SQLString As String Dim hr_id As String Dim EmpDoc As NotesDocument'Fetched Row from DB2 Table Dim ParmDoc As NotesDocument 'Parameter Doc from Agent created by Search Employee Button The following LC Objects are declared for containing the key information and the result set information. The FLD... fields refer to the DB2 columns. 'Declare LC Objects Dim Session As New LCSession Dim src As LCConnection Dim FieldOut As New LCFieldList ' Fieldlist populated after Select Dim KeyList As New LCFieldList ' key Fieldlist Dim FLDLastname As LCField Dim FLDFirstname As LCField Dim FLDEmpno As LCField Dim FLDDeptname As LCField Dim kfld As LCField ' Field used for the key Fieldlist Chapter 8. Accessing DB2 with programmatic connectors 153 The following lines initialize the parameter document from the agent and read the key parameter for the select. 'Get Notes Docs Set DB = NSession.currentdatabase Set Agent = NSession.currentagent 'Read key Parameter from Agent Parameter Document Set ParmDoc = db.GetDocumentbyID(agent.ParameterDocID) Print "Parm Document opened, NoteID = "+ ParmDoc.NoteID tkey = Parmdoc.GetItemValue("LCKEY" ) Note The LSX Session class has a status property that can be used to determine if the error handler was triggered by an LSX error or a LotusScript error. In all cases where the LSX reports an error, the LotusScript 'Error$' will contain error information. However, when first creating LSX objects, the LSX has additional error information not available through the LotusScript error statements. Creating and initializing the session status provides this additional information for the error handler. The creation of the session object is not necessary for normal error handling. The connection to the DB2 table is established in the following lines. After the connection is created, all of its properties are accessible to customize the connection to the target system. Common properties include database and server, user ID, and password. Properties are not case sensitive. ‘Establishing the Connection Session.ClearStatus Set src = New LCConnection ("db2") '‘Create Connection object src.Database = "DB2G" src.Metadata = "DSN8610.EMPLOYEE_NO_BLOB" src.UserID ="FUST" src.Password = "lnotes" Print "Establishing Connection" src.Connect '‘Connect to db2 data source ‘EILLAB’ Print "Connection established" This selection is accomplished by creating a key list. The default key flag, LCFIELDF_KEY, indicates an exact match. If an inequality, such as 'greater-than' or 'like' is needed, then the field's flags property would be ORed 154 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products with the corresponding constant. (In all cases, key fields must have the LCFIELDF_KEY constant in addition to any optional conditional flag constants.) The key fieldlist which defines the column and the value used to retrieve the rows is created in the following lines. The value was read before from the agent parameter document. 'Create key fieldlist Set kfld = keylist.append("LASTNAME", LCTYPE_TEXT) kfld.Flags = LCFIELDF_KEY kfld.value = tkey(0) The Select connection method creates a result set of all records from the external system which match the keylist. If the LotusScript keyword Nothing is substituted for the keylist, then all records of the specified metadata would be selected. In this case, all records from the DB2 table are selected. Here we use our previously created key fieldlist. We match the LC Fields to the columns of the result set we will receive. 'Do a keyed Select on the table count = src.Select(keylist,1,fieldout) 'Set LC Fields Set FLDlastname = Fieldout.Lookup ("LASTNAME") Set FLDFirstname = Fieldout.Lookup ("FIRSTNME") Set FLDEmpno = Fieldout.Lookup ("EMPNO") Set FLDHierarchy = Fieldout.Lookup ("DEPTNAME") The Fetch connection method reads the data from the external system into the result fieldlist (result set). The individual data values may be accessed from a fieldlist using the expanded class properties. For each field in a fieldlist, there is a property with the corresponding name. This property is an array of values using the closest available LotusScript datatype to match the LSX LC datatypes. The following loop goes over the result set and issues a fetch as long as any data is left. For each successful fetch, a document is created in our sample application. 'Loop over Resultset While (src.Fetch (Fieldout) > 0) 'Create Document for each Row Set empdoc = db.createdocument empdoc.form= "Person" empdoc.Firstname = FldFirstname.text(0) empdoc.Lastname = Fldlastname.text(0) Chapter 8. Accessing DB2 with programmatic connectors 155 empdoc.Hierarchy = FLDHierarchy.text(0) empdoc.Empno = FLDEmpNo.text(0) Call empdoc.Save (True, False) Wend Note When writing scripts that act on more than one record, it is more efficient to locate the field from within the fieldlist, outside the loop, and then use the field for data access. Using the expanded class properties locates the field each time it is used and allocates an array of values, not just a single value. Finally we delete the agent parameter document and disconnect from the DB2. ret = ParmDoc.Remove(True) 'remove Agent Parameter Document src.Disconnect '‘Disconnect from db2 data source ‘DB2G’ Exit Sub Note In LotusScript, if no explicit “delete” occurs on an object, it is automatically deleted when it falls out of the scope of the function, subroutine, or script. So the LCConnection.disconnect is not a must. We also have error handling, by printing errors to notes.log on the Domino server. Handler: '‘Error Handler If ( session.status <> LCSUCCESS) Then Print session.GetstatusText, 0, _ + "The following Lotus Connector error has occurred." Else Print Error$, 0, _ + "The following LotusScript error has occurred." End If End Sub 8.2.4 Updating and inserting data in DB2 To show how it is possible to update or insert data from Notes documents into a DB2 table, we enhance our online employee retrieval scenario. We supply an agent which allows us to write data back to the DB2 table. The first step in the scenario allows us to search for employees by issuing the lastname. We retrieve all employees with this lastname, collecting a subset of the whole 156 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products DB2 employee table. The DB2 data can now be viewed and edited in Notes documents, using a Notes client or a Web browser. The next step is to bring the changes done in the Notes documents back into the corresponding DB2 table row. We implemented a simple solution in our Notes department database that can be activated in a open document by pressing an action button after editing the document, as shown in Figure 99. Figure 99. The update/insert button in the sample application The agent is activated on each document, using the Notes client. The agent can also be activated by a Web browser using the method explained in the MQLSX scenario; see 10.2.2, “The Domino application using MQLSX” on page 176. The agent code would differ only in the way the document is handed to the agent. Another way to use this agent, with simple modifications, would be with a view. In this way, several of the fetched documents could be modified. When all modifications were done, the agent would select all modified documents in the view and write the changes of each into the DB2 table. For code simplicity, we show the agent code only applied to the currently open document. 8.2.5 Code enhancements in the sample application As a basis for starting, we take the organization.nsf code developed for the online employee retrieval scenario. We add an action button to the “Person” Chapter 8. Accessing DB2 with programmatic connectors 157 form, and we add another agent for updating or inserting the data. In the following section, we step through the important sections of code. The complete agent code is available in Appendix C, “Sample LotusScript agent code” on page 221. 8.2.5.1 The update DB2 action button in the Person form The code behind the button is similar to the button used in the online employee retrieval scenario. The difference is that the document itself is used as a parameter document for the agent; no temporary document is created. The creation of a temporary document has some performance advantages when the originating Notes document is large. In this case, the current document is not large, so the fields are read out directly. The code below gets the current document, reads the NoteID, and hands the document over to the agent. Then the agent is triggered by the Notes client and runs again on the Domino server. 'get the current document Set db = session.CurrentDatabase Set uidoc = ws.currentdocument Set doc = uidoc.document Call uidoc.save 'save document to deliver new parameters to the agent ' Get Agent and Run it on the Server Set Agent = db.GetAgent("Update/InsertEmp") Print " . . . DB2 Fetch Agent running " status = Agent.RunOnServer(Doc.NoteID) If status = 0 Then Print " DB2 Data Update/Insert Agent executed successfully" End Sub 8.2.5.2 The update/insert emp agent In the first lines, the declaration of the necessary LCObjects is executed. 'Declare LC Objects Dim Session As New LCSession Dim src As LCConnection Dim FieldLst As New LCFieldList Dim kfld As LCField Dim fld As LCField The employee document is opened using its NoteID, which is provided by the agent calling parameter and retrieved using the ParameterDocID property. In this case, we take the employee number as the key. It is retrieved from the employee document. Set DB = NSession.currentdatabase Set Agent = NSession.currentagent 'Read key Parameter from Employee Document Set ParmDoc = db.GetDocumentbyID(agent.ParameterDocID) Print "Parm Document opened, NoteID = "+ ParmDoc.NoteID tkey = Parmdoc.GetItemValue("EMPNO" ) Print "key " + tkey(0) + "fetched" 158 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products The connection to the DB2 table EMPLOYEE_NO_BLOB is established. The LCConnection.MapByName property determines that the mapping between the fieldlist and the DB2 table is done by name and not by order. If we did not use this property, firstname and lastname would be switched in the DB2 table. 'Establish DB2 Connection Session.ClearStatus Set src = New LCConnection ("db2") '‘Create Connection object src.Database = "DB2G" src.Metadata = "DSN8610.EMPLOYEE_NO_BLOB" src.UserID ="FUST" src.Password = "lnotes" src.MapByName = True Print "Establishing Connection" src.Connect '‘Connect to db2 data source ‘EILLAB’ Print "Connection established" The fieldlist, which represents the row to be updated or inserted, is created. LCField fld is used to create the fieldlist. The corresponding names of the aim columns of the DB2 table are appended to the fieldlist. The EMPNO column is the key column by which the corresponding DB2 table row will be searched. The column values to be updated or inserted in the table are set in the fieldlist. The value of the key, EMPNO, is retrieved from the employee document and assigned. 'Create key fieldlist to be updated or inserted Set kfld = FieldLst.append("EMPNO", LCTYPE_TEXT) kfld.Flags = LCFIELDF_KEY kfld.value = tkey(0) Set fld = FieldLst.append("LASTNAME", LCTYPE_TEXT) fld.Text = Parmdoc.Lastname(0) Set fld = FieldLst.append("FIRSTNME", LCTYPE_TEXT) fld.Text = Parmdoc.Firstname(0) Set fld = FieldLst.append("DEPTNAME", LCTYPE_TEXT) fld.Text = Parmdoc.Hierarchy(0) Note If you use the LCConnection.MapByName property, the result set fields will be mapped by name to the DB2 table columns. Otherwise they will be mapped by position. An update of an existing row is tried. The column EMPNO of the DB2 table is searched for the value which is previously defined. If this value exists in the table, the values defined in the result set are updated in the row of the table. Chapter 8. Accessing DB2 with programmatic connectors 159 In this case, count equals the number of rows updated. If the row cannot be found, nothing is updated in the DB2 table and count is set to 0. 'Do a Update on the table if the row exists (key = EMPNO) count = src.Update(FieldLst,1,1) Print Cstr(count) + " rows updated" If an update is unsuccessful (count = 0), the fieldlist is inserted in the table. ' Do a Insert if row doesn't exist (key = EMPNO) If count = 0 Then count = src.Insert(FieldLst,1,1) Print Cstr(count) + " rows inserted" End If Note If you issue consecutive inserts into the same target, you should use the same fieldlist to achieve optimum performance. If a row is successfully updated or inserted, the employee document is deleted from the Notes database. The connection is disconnected. If count > 0 Then ret = ParmDoc.Remove(True) 'remove Document only if Table has been updated/inserted End If src.Disconnect '‘Disconnect from db2 data source ‘DB2G’ Exit Sub In this case the error handling is skipped, since it is the same as in the previous scenario. 8.2.6 Deleting rows in the DB2 table To illustrate how you can delete rows in a DB2 table, we again enhanced the employee retrieval scenario, activating the Delete row button as shown in Figure 100 on page 161. The Notes document itself will be also deleted. 160 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Figure 100. The delete row button in the sample application Once again, this scenario could also be performed using a Web browser, with little change in the agent activation technique. It is also possible to run this agent, slightly modified, in a view and delete the subset of table rows corresponding to the documents in the view. 8.2.7 Code enhancements in the sample application The action button used for this function is just like the one used in the update/insert example. The only difference is the name of the agent called. We again use EMPNO as key to find the row to be deleted. 8.2.7.1 The delete row agent code The first part of the agent is identical to the update/insert agent. This includes the declaration, fetching the employee document and key, and establishing the connection. We begin stepping through the code after the connection has been established. src.Connect '‘Connect to db2 data source ‘EILLAB’ Print "Connection established" The key fieldlist is created containing only the key field and its value, so that the corresponding row can be found in the DB2 table. The key is again the employee number (EMPNO), which is provided by the agent parameter document. Chapter 8. Accessing DB2 with programmatic connectors 161 'Create key fieldlist with key of the row to be removed Set kfld = FieldLst.append("EMPNO", LCTYPE_TEXT) kfld.Flags = LCFIELDF_KEY kfld.value = tkey(0) Now the fieldlist is used for the LCConnection. Here is a method to remove the first row with the provided EMPNO. 'Do a Delete on the table if the row exists (key = EMPNO) count = src.Remove(FieldLst,1,1) Print Cstr(count) + " rows deleted" If the row is found and deleted, the employee document is deleted in the Notes database and the connection is disconnected. If count > 0 Then ret = ParmDoc.Remove(True) 'remove Document only if row has been deleted Print "deleted" End If src.Disconnect 'Disconnect from db2 data source ‘DB2G’ Exit Sub 8.2.8 Stored procedures We built a stored procedure in the MVS DB2 subsystem. We could not successfully call it using the LCConnection.Procedure Property with the name of the stored procedure and calling it with the LCConnection.Call method. We always got DB2 error messages. However, we think it would work. 8.2.9 Performance enhancement using connection pooling A typical operation on an enterprise database system consists of three parts: 1. Connection 2. Operations with the data 3. Disconnection In many enterprise integration applications, only a small number of operations are executed on the relational data application. A much greater percentage of total time is associated with connecting to and disconnecting from the external data source. The LSX for Lotus connectors provides a connection pooling property that makes it possible to retain discarded connections for later use. The pooling functionality is controlled by the LCSession property, ConnectionPooling, which is a Boolean with a default value of FALSE. When this property is set to TRUE, subsequent requests for new connections are processed through the connection pool. 162 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products 8.2.9.1 How connection pooling works and is used With connection pooling, creating a new connection is accomplished by first checking the pool for an existing compatible connection; if one is not available, then a new connection is created. A compatible connection is determined by the external system and by the required connectivity properties. This prevents a connection that was originally established for one user from later being used by another. As an example, a connection to DB2 which was originally created using Mike's username and password, and then released to the connection pool, would not be reused if a connection was requested using Rich's username and password. A connection is removed from the pool when the Connect method occurs. A connection is returned to the pool when the Disconnect method occurs. If no explicit disconnect occurs, an automatic disconnect is performed when the object is deleted. A connection that is returned to the pool does not perform a disconnect from the external system. Code that takes advantage of connection pooling must anticipate this behavior, and compensate for what normally would happen automatically during a disconnect. For example, disconnecting from an RDBMS may trigger a commit of records inserted, updated, or deleted since the connection was established. Likewise, rollbacks or other database operations can take place automatically as a result of disconnecting. When connection pooling is enabled, these events do not take place because the connection is not actually dropped. Therefore, if you want these types of operations, the processing portion of the script must explicitly perform them. The life span of a pooled connection is dependent on the LSX. Within Notes and Domino, an LSX is loaded when the execution of UseLSX occurs in a script. The LSX is not unloaded until the Notes or Domino process terminates. Once a connection is pooled, it remains available until the associated process terminates. The connection pool defaults to a maximum of 20 pooled connections for a given external system. When the maximum number of connections has been created and is in use, any requests for an additional connection will be granted but the connections will not be pooled. The default may be overridden using INI settings. For details, refer to the Domino LCLSX documentation. In our sample agent code, you could activate connection pooling by issuing the following line after initializing the LCSession. .ConnectionPooling = true Chapter 8. Accessing DB2 with programmatic connectors 163 Once you add this line and connect to a DB2 table, you will notice the performance improvement when connecting for the second time. The first connection gets set up for the specific user, and the second time this connection can be reused. 8.3 Integrating DB2 using LS:DO programming In addition to the LCLSX family, Lotus offers the LotusScript Data Object (LS:DO) connector. This popular product will eventually be replaced by the LCLSX connector for DB2. To illustrate how LS:DO works, we have coded the same online employee retrieval scenario we used with LCLSX; see 8.2.1 on page 150. This way the two technologies can be compared. 8.3.1 The o nline employee retrieval scenario using LS:DO We coded the same online employee retrieval that we used with LCLSX. The agent is activated, as in the LCLSX example, by using a button on a navigator page, as shown in Figure 101. Figure 101. The LS:DO search button in the sample application 164 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products We use the Notes client to initiate the execution of the agent. The button calls the LS:DO Fetch Emps agent using the “Run on Server” method. The key parameter is passed to the agent using the parameter agent document. For detailed information, refer to 8.2.1, “Business scenario: online employee retrieval” on page 150. We step through the important pieces of code in the following section. The complete code can be viewed in Appendix C, “Sample LotusScript agent code” on page 221. 8.3.2 Stepping through the agent LS:DO Fetch Emps code In the options section of the agent, the line Uselsx "*LSXODBC" must be added. The following lines show the declaration of the three LS:DO classes. Dim con As New ODBCConnection Dim qry As New ODBCQuery Dim result As New ODBCResultSet The parameter document created by the button is fetched using the Note ID of the document fetched by the agent.parameterDocID property of the agent. The key to be used in the SQL statement is retrieved from the parameter document field LCKEY. 'Get Notes Docs Set DB = NSession.currentdatabase Set Agent = NSession.currentagent Print "LS:DO Agent" 'Read key Parameter from Agent Parameter Document Set ParmDoc = db.GetDocumentbyID(agent.ParameterDocID) Print "Parm Document opened, NoteID = "+ ParmDoc.NoteID tkey = Parmdoc.GetItemValue("LCKEY" ) Print "key " + tkey(0) + "fetched" The connection is built to the DB2 database. 'connect to DB2G using "fust" ID and "lnotes" password If Not con.ConnectTo("db2g", "fust", "lnotes") Then Print "Could not connect to DB2G" Exit Sub End If The query and result set objects are initiated and the SQL is executed on the result set. 'execute the SQL against the Employee_no_blob table Set qry.Connection = con Set result.Query = qry SQLStr$ = "SELECT * FROM DSN8610.EMPLOYEE_NO_BLOB WHERE LASTNAME = '" _ & tkey(0) & "'" Chapter 8. Accessing DB2 with programmatic connectors 165 qry.SQL = SQLStr$ result.Execute In the next lines, the agent creates and saves an employee document for each table row where lastname equals the key in the SQL statement. If the loop reaches the end of the result set, it is closed with the DB_CLOSE option, which causes the entire result set to be purged. 'iterate through the resultset If result.IsResultSetAvailable Then Do result.NextRow 'Create Document for each Row / Resultset entry Set empdoc = db.createdocument empdoc.form= "Person" empdoc.Firstname = result.GetValue("FIRSTNME") empdoc.Lastname = result.GetValue("LASTNAME") empdoc.Hierarchy = result.GetValue("DEPTNAME") empdoc.Empno = result.GetValue("EMPNO") Call empdoc.Save (True, False) Loop Until result.IsEndOfData result.Close(DB_CLOSE) Else Print "No data retrieved " Exit Sub End If The connection is disconnected and the parameter document is deleted. 'disconnect con.Disconnect ret = ParmDoc.Remove(True) End Sub 'remove Agent Parameter Document 166 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Part 3. Working with MQSeries © Copyright IBM Corp. 2001 167 168 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Chapter 9. Setting up MQSeries This chapter describes how to set up your environment so that the Domino for S/390 server can communicate with MQSeries applications. 9.1 MQSeries for OS/390 setup Setting up an environment for MQSeries for OS/390 is described in MQSeries for OS/390: System Management Guide. Carefully follow the instructions given. Adapters are part of MQSeries. You will need to set up an MQSeries batch/TSO adapter with your message queue manager in order to enable Domino for S/390 to work with queues and messages. If you want to access other application environments, such as CICS and IMS, you have to set up their adapters as well. In our environment, we have MQSeries for OS/390 Version 2 Release 1 installed. Our message queue manager is named MQSX, which we use in our code samples. Domino for S/390 uses MQSeries LotusScript Extensions (MQLSX) to access MQSeries message queueing services. The installation of MQLSX is described in 4.3.3, “MQLSX installation on Domino for S/390” on page 77. MQLSX uses the batch/TSO adapter of MQSeries. 9.1.1 Message queue manager To begin, collect the information about your message queue manager (MQM) from OS/390 parmlib member IEFSSNxx or from your system administrator. Ensure that the MQM is started. Also, if you work with other application subsystems, make sure the appropriate adapters are installed in those systems. In our case, we installed the MQSeries-CICS adapter and MQSeries-CICS bridge. In CICS, you have to define resources used by these bridges. Resource definitions for programs, transactions, and CICS temporary storage queues are shipped with MQSeries for OS/390. Use these prepared jobs to update the CSD data set of your CICS subsystems. Install related resource groups so CICS programs and transactions will be accessible from 3270 terminals or from other programs. You can use CICS transaction CKQC to check and monitor the MQSeries-CICS adapter. You can use an IBM-supplied transaction (CKBR) or © Copyright IBM Corp. 2001 169 a user-written transaction to start CICS programs from the MQSeries-CICS Bridge. We did not work with IMS or other application subsystems in our testing, but we believe that the principles we used for MQSeries and CICS are valid for other configurations as well. Always refer to the publications for MQSeries and application subsystems for guidance in setting up MQSeries adapters and bridges. 9.1.2 Message queues The default installation of MQSeries for OS/390 creates many resources in the MQM. You will need to set up different queues for your applications, probably with different attributes. For initial testing using our samples, you need to create the following queues: • • • • SG245682.NOTES.IN.QUEUE SG245682.NOTES.OUT.QUEUE CICS01.INITQ SYSTEM.DEFAULT.LOCAL.QUEUE Message queue SYSTEM.DEFAULT.LOCAL.QUEUE is used by the MQLSX IVP agent. You can define it using these MQSeries commands: DEFINE QUEUE(SYSTEM.DEFAULT.LOCAL.QUEUE) TYPE(QLOCAL) PUT(ENABLED) DEFPSIST(NO) MAXDEPTH( 999999999) NOTRIGGER MAXMSGL(4194304) NOSHARE DEFSOPT(EXCL) MSGDLVSQ(PRIORITY) RETINTVL(999999999) TRIGTYPE(FIRST) TRIGDPTH(1) TRIGMPRI(0) DEFTYPE(PREDEFINED) NOHARDENBO GET(ENABLED) INDXTYPE(NONE) DEFBIND(OPEN) Message queue CICS01.INITQ is used by the MQSeries-CICS Bridge. You can define it with these commands: DEFINE QUEUE(CICS01.INITQ) TYPE(QLOCAL) STGCLASS(SYSTEM ) DESCR(CKTI initiation queue) PUT(ENABLED) DEFPRTY(5) DEFPSIST(YES) NOTRIGGER MAXMSGL(1000) USAGE(NORMAL) SHARE DEFSOPT(EXCL) MSGDLVSQ(FIFO) RETINTVL(999999999) TRIGTYPE(NONE) NOHARDENBO GET(ENABLED) QDPMAXEV(ENABLED) QDPHIEV(DISABLED) QDPLOEV(DISABLED) QSVCINT(999999999) QSVCIEV(NONE) INDXTYPE(NONE) DEFBIND(OPEN) Message queues SG245682.NOTES.IN.QUEUE and SG245682.NOTES.OUT.QUEUE are used by our samples in this redbook. Here are the MQSeries commands you can use to create these objects: 170 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products DEFINE QUEUE(SG245682.NOTES.IN.QUEUE) TYPE(QLOCAL) STGCLASS(DEFAULT) DESCR(Sample queue for incoming msgs to MQLSX) PUT(ENABLED) DEFPSIST(NO) MAXDEPTH( 999999999) NOTRIGGER USAGE(NORMAL) NOSHARE DEFSOPT(EXCL) MSGDLVSQ(PRIORITY) RETINTVL(999999999) TRIGTYPE(FIRST) TRIGDPTH(1) TRIGMPRI(0) DEFTYPE(PREDEFINED) NOHARDENBO GET(ENABLED) INDXTYPE(NONE) DEFBIND(OPEN) DEFINE QUEUE(SG245682.NOTES.OUT.QUEUE) TYPE(QLOCAL) STGCLASS(DEFAULT) DESCR(Sample queue for outgoing msgs from MQLSX) PUT(ENABLED) DEFPSIST(NO) MAXDEPTH(999999999) PROCESS(ITSOSAMP) TRIGGER MAXMSGL(4194304) USAGE(NORMAL) NOSHARE DEFSOPT(EXCL) MSGDLVSQ(PRIORITY) RETINTVL(999999999) TRIGTYPE(EVERY) TRIGDPTH(1) TRIGMPRI(0) NOHARDENBO GET(ENABLED) INDXTYPE(NONE) DEFBIND(OPEN) Note that for queue SG245682.NOTES.OUT.QUEUE, we defined a process called ITSOSAMP. This process is triggered every time a message arrives to this queue. Process ITSOSAMP is defined in 9.1.3. 9.1.3 MQSeries processes Processes are defined in MQSeries to handle events. They are triggered when a message arrives in a specified queue. In the queue definition (as in our example in 9.1.2), you can specify when MQSeries triggers a process. In our case, it was after any message arrives in the queue. Our process, defined in the queue, is named ITSOSAMP and is defined as follows: DEFINE PROCESS(ITSOSAMP) DESCR(Sample process for Domino and MQLSX) APPLTYPE(CICS) APPLICID(IMQG) USERDATA() ENVRDATA( ) This definition, combined with other information provided when queue was created, means that after any message arrives, the process IMQG (a CICS transaction) is started. IMQG reads a message from queue and writes that data to a VSAM dataset. 9.1.4 MQSeries-CICS bridge If you want to access 3270-based CICS applications from Lotus Domino for S/390, the only way to achieve this today is to use the MQSeries-CICS bridge. This bridge is an interface between 3270-based transactions and an MQSeries-aware application, including MQLSX. You need to understand CICS external interfaces in order to write applications using MQLSX and Domino. The MQSeries-CICS bridge is not a VTAM device emulator, it is a real bridge. It communicates with CICS transactions using vectors, which represent data Chapter 9. Setting up MQSeries 171 otherwise provided by EXEC CICS requests. You need to understand these data structures for your MQLSX programs. Using this method, you can directly access existing 3270 applications, giving your Notes users access to back-end business applications and data sources supported by CICS. 9.1.5 Other MQSeries considerations Using the MQSeries family of products offers you an opportunity to gain access to diverse applications and data sources in your company. In Chapter 10, “Connecting with MQSeries including CICS” on page 173, we show how to access VSAM datasets (read and write) from Domino for S/390 applications using MQLSX and MQSeries. This technology gives you access to all the environments supported by MQSeries, including non-S/390 platforms, flat files, and non-relational databases. 172 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Chapter 10. Connecting with MQSeries including CICS In this chapter we demonstrate how to connect a Domino application on a S/390 server to an enterprise application. We use MQSeries as the connection middleware. With MQSeries, it is possible to connect to all sorts of applications, if they support an MQSeries interface. In this case we chose a CICS application as our enterprise system. We connect to MQSeries using the MQLSX LotusScript Extensions. 10.1 CICS connection scenario: order account management We have chosen a scenario which is part of many procurement solutions. A supplier offers items on the Internet. Customers can order these items using a standard Web browser. In our scenario, each customer has an account where orders are managed. This is done by a transaction-based CICS application derived from the standard sample application FILEA. The application is illustrated in Figure 102 and described in detail in the following sections. remote S390 Domino AccountMan Application MQLSX HTTP CICS Transactional Application MQSeries Notes Internet Figure 102. MQLSX order account management scenario © Copyright IBM Corp. 2001 173 We developed a Domino application that can be accessed from the Web or from a Notes client. When an item is ordered, the order will be saved in the Domino server database using the Web browser; see Figure 103. Figure 103. Putting an order into MQSeries By clicking Shop IBM, a server-based agent is activated. It puts this order, in a defined format, into a MQ queue called SG245682.OUT.QUEUE. This is illustrated in Figure 102 on page 173 by the two upper symbols in the MQSeries box, and is accomplished using the MQLSX classes. This message format contains the ID of the document representing the order, so the connection to the originating Notes document can always be obtained. If the action is successful, this message is received by the browser: Your Order is shipped. You will receive the confirmation soon. MQSeries itself can be distributed in various ways. The MQ Manager handles the queue entry; if necessary, it distributes it using MQ transfer queues to a distributed server. A CICS application reads the queue and gets the MQ message issued by the Domino server. Once the message is retrieved, the CICS transaction logic saves the account order information to a VSAM file. When it is saved, a confirmation is put into the SG245682.NOTES.IN.QUEUE, which again is managed and possibly transferred to another location by the queue manager. 174 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products A scheduled Domino agent runs every five minutes to poll the SG245682.NOTES.IN.QUEUE queue. This is illustrated by the lower symbols in the MQSeries box in Figure 102 on page 173. Of course, this parameter is changeable. When the message arrives in the queue being polled, it is read by the agent. The ID of the corresponding Notes document is retrieved from the string and the document is modified with the information issued by the CICS application. For example, some confirmation information is shown in Figure 104. Figure 104. Viewing status change in the view after MQ get The confirmation information is now visible in the document and the view. At this point, some automation (such as mail notifiers) could be added with little effort. Of course our application is very simple, since we concentrated on the queue interface management. 10.2 Examining the code of our sample application In this section, we look at the sample application code that we wrote for the MQSeries-CICS scenario. Chapter 10. Connecting with MQSeries including CICS 175 10.2.1 The transactional CICS application Our CICS application is based on IBM-supplied samples shipped with CICS. We used the C version, although other languages may be used as well. Our CICS application is unaware of Domino, so the only interface is through MQSeries queues. Our application reads data from one queue and writes answers back to the other queue. We exchanged the structure of the data among our developers for CICS and LotusScript. We used standard structure, which is used by every FILEA sample in CICS. Our CICS application consists of two main transactions. The first one, IMQG, reads SG245682.NOTES.OUT.QUEUE and writes messages to the file FILEA. It also writes messages to the CICS log, where you can immediately check which message was processed and written to the VSAM file. IMQG invokes program ITSOGALL. This program is very simple, with limited function. However, it does what we need: it reads one message at a time from the queue and writes it into a VSAM file. Note: It is possible to run this CICS transaction when any message arrives in the queue. This is defined in MQSeries. First, you define how the queue used for Domino-CICS communication triggers it: after the first message; or after some number of messages; or after each message processed. Second, you define this process to MQSeries and refer to a matching CICS transaction. We did not use this function in our samples. The second transaction is QMNU, which calls program ITSODMNU. It is a simple menu transaction where you can browse, add, query, and update records in VSAM file. We modified the CICS-supplied samples so that every update or add action writes the same data written to the VSAM file to the message queue SG245682.NOTES.IN.QUEUE, too. This is done by program ITSODALL. We also changed the status flag field of the record from 0 to 1, aliased in Notes by open and confirm. This is interpreted by a Domino agent and indicates to the user that the order has been accepted into the system. For a complete source code listing of our CICS application, see Appendix C, “Sample LotusScript agent code” on page 221. All changes to the original IBM-supplied samples are highlighted in boldface. 10.2.2 The Domino application using MQLSX The Domino application consists of a two-frame frameset, a form, a page with an embedded outline as navigator, a view, and three agents. For the MQ functionality, we only discuss the code related to it. This time we chose a Web browser for our client. A slightly different agent can also be called using the “RunonServer” method from a Notes client. 176 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Once you open the database from the Web, the first step of filling out the document and putting the order into a queue is activating by clicking Shop IBM in the form. The following @Command code is executed: @Command([ToolsRunMacro];"WebMQPutOrder"); @Command([FileSave]); @Command([FileCloseWindow]) The code calls the WebMQPutorder agent, which is activated through HTTP on the Domino server. The second important script agent is the polling agent. It is scheduled to run every 5 or 10 minutes. It polls the queue for arriving messages with confirmation information, and writes the information in the corresponding document. 10.2.2.1 The message putting agent: WebMQPutOrder In this section the important parts of the agent are described. To see the complete code of the agent, refer to Appendix C, “Sample LotusScript agent code” on page 221. The following lines are to declare the necessary QM objects. 'Declare MQObjects Dim mqs As MQSession Dim mqqm As MQQueueManager Dim mqq As MQQueue Dim mqm As MQMessage Dim mqpmo As MQPutMessageOptions Dim mqgmo As MQGetMessageOptions Dim mqp As MQProcess The Notes session and the database in which the agent runs are set. Set session = New NotesSession Set db = session.CurrentDatabase The Order document which was filled using the Web browser is retrieved using the Document Context property of the session. The document context is always the Notes document from which an agent is called using the browser. Once the document is retrieved, the field values of the document are read into string variables. In the phone$ string variable, we put the NoteID of the document. (We could have renamed the variable.) This ID of the document is transferred back and forth to the CICS application so the Notes document can be retrieved for writing the confirmation information into it. 'Read MQ string values from DocumentContext (Document where agent is activated) Set ParmDoc = session.DocumentContext Stat$= ParmDoc.Status(0) CustNumber$ = ParmDoc.CustomerNumber(0) CustName$ = ParmDoc.CustomerName(0) Item$ = ParmDoc.Item(0) Chapter 10. Connecting with MQSeries including CICS 177 Phone$ = Cstr(ParmDoc.NoteID) <--------OrderDate$ = Cstr(ParmDoc.Date(0)) Amount$ = Cstr(ParmDoc.Amount(0)) Comment$ = ParmDoc.Comment(0) In the following lines, the queue name is defined. The name can be viewed by issuing a DISPLAY QLOCAL (*) command in the MQSeries control panel on the S390. We created the queues for our example application. 'Specify name of the Queue to put the message in QueueName$ = "SG245682.NOTES.OUT.QUEUE" The MQSession is created here, In case of an error, the error message will be displayed in the browser. ' Creating New MQSession Set mqs = New MQSession If mqs.CompletionCode <> MQCC_OK Then Print "Error: MQSession cc: " & mqs.CompletionCode Print "Error: MQSession rc: " & mqs.ReasonCode End If We initiate the following MQ Objects and connect to the MQSX queue manager. To get the name of the MQ Queue manager, ask the MQ Administrator. ' Initiate MQQueueManager, MQPutMessageOptions, Message Set mqqm = New MQQueueManager Set mqpmo = New MQPutMessageOptions Set mqm = New MQMessage ' mqqm.Connect QmgrNames$ = "MQSX" mqqm.name = QmgrNames$ Call mqqm.Connect We access the queue MQSX with queue default values. For detailed information about MQSeries, refer to MQSeries Application Programming Reference. The URL to get this documentation is found at the end of the MQLSX introduction chapter. ' Access the queue QOpenOptions& = 0 Set mqq = mqqm.AccessQueue(QueueName$, QOpenOptions&, "","","") Now the message is concatenated with the field values of the order form. The variable Phone contains the NoteID of the Order document itself. We don’t do any string length evaluation or conversion. In a production application, string length adaptions should be programmed, because the strings written to the 178 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products queue must be the exact byte length of the datagram of the queue. Otherwise they will be chopped. On success, a message will be written to the Web browser by issuing a print statement. ' PUT Msg '--------------' Set msg options for write mqm.WriteString(Stat$ & CustNumber$ & CustName$ & Item$ & Phone$ & OrderDate$ & Amount$ & Comment$) If mqm.CompletionCode <> MQCC_OK Then Print "Error: MQSession cc: " & mqs.CompletionCode Print "Error: MQSession rc: " & mqs.ReasonCode Else Print "Your Order is shipped. You will receive the confirmation shortly." End If The messagetype of the MQ message is set to datagram and the format is set to string. The message is put into the queue with default options and a commit is issued. Now the message is handed over to the MQSeries queue manager. The disconnect statement ends the code here, setting MessageType to MQMT_DATAGRAM mqm.Messagetype = MQMT_DATAGRAM mqm.Format = MQFMT_STRING ' Put the msg Call mqq.put(mqm,mqpmo) ' Commit the message Call mqqm.Commit ' Disconnect Call mqqm.Disconnect To the original code we added some lines of cleanup and error message handling. This can be seen in Appendix C, “Sample LotusScript agent code” on page 221. 10.2.2.2 The message polling agent In this section the important parts of the agent are described. To see the complete code of the agent, refer to Appendix C, “Sample LotusScript agent code” on page 221. The queue for incoming messages is defined. 'Specify Name of Queue to poll QueueName$ = "SG245682.NOTES.IN.QUEUE" A new MQ session is opened. An error message is issued if a session cannot be opened. The necessary queue objects are initialized. Chapter 10. Connecting with MQSeries including CICS 179 ' Creating New MQSession Set mqs = New MQSession If mqs.CompletionCode <> MQCC_OK Then Print "Error: MQSession cc: " & mqs.CompletionCode Print "Error: MQSession rc: " & mqs.ReasonCode End If ' Initiate MQQueueManager, MQPutMessageOptions, Message Set mqqm = New MQQueueManager Set mqgmo = New MQGetMessageOptions Set mqm = New MQMessage Again we connect to the MQ queue manager MQSX , and the incoming queue is accessed with queue default options. ' mqqm.Connect to Queue Manager MQSX QmgrNames$ = "MQSX" mqqm.name = QmgrNames$ Call mqqm.Connect ' Access the queue QOpenOptions& = 0 Set mqq = mqqm.AccessQueue(QueueName$, QOpenOptions&, "","","") The options for the get operation on the Queue, which will read the data from the queue, are set. MQGMO_FAIL_IF_QUIESCING causes a failure if the queue manager is quiescing. This option in turn forces the MQGET call to fail. On OS/390, this option also forces the MQGET call to fail if the connection (for a CICS or IMS application) is in the quiescing state. If MQGMO_FAIL_IF_QUIESCING is not specified and the queue manager or connection enters the quiescing state, the wait or signal is not canceled. The MQGMO_SYNCPOINT option sets a synchronization point, which defines a unit of work. This should be set in the first MQGet of a unit of work. In this case, one MQGet represents a unit of work. This synchronization point is used when issuing a commit or fallback. For detailed information about MQSeries, refer to MQSeries Application Programming Reference at URL: http://www.software.ibm.com/ts/mqseries/library 180 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products The depth of the queue is also logged. In production, the depth of the queue should be greater than 0 in order to proceed: ' GET MSG '--------------'Setting Message Options mqgmo.options = MQGMO_FAIL_IF_QUIESCING + _ MQGMO_SYNCPOINT T$ = "17.Queue depth before get: " & mqq.CurrentDepth Print T$ 'Check # Queue entries The following section of code gets the message out of the queue using the above options. The datagram of the queue is read into a string declared as msgin$. This string contains all the data we need. The commit for this unit of work is issued. The queue now contains one entry less than above. The queue manager is disconnected. ' Get the message Call mqq.Get(mqm,mqgmo) If mqs.CompletionCode <> MQCC_OK Then Print "Error: " & T$ & " cc: " & mqs.CompletionCode Print "Error: " & T$ & " rc: " & mqs.ReasonCode End If Print "Got the Message" ' Read the message msgin$ = mqm.ReadString(mqm.MessageLength) Print "Read the Message" ' Commit the get Call mqqm.Commit T$ = "24.After Get and COMMIT queue depth is: " & mqq.CurrentDepth Print T$ 'Check # Queue entries ' Disconnect Call mqqm.Disconnect The note ID of the target Notes document is retrieved. It is in position 48 in the msgin$ string and it is defined to be 8 characters long. We use the GetDocumentbyID property to get the document which contains the corresponding order, using the NoteID we just fetched. All the data from the queue datagram is read into the fields of the Notes document. In our example, we altered only the Status and Comment fields. The document is saved and the results can be seen in a view or document. In production, you should not use hardcoded position digits. Chapter 10. Connecting with MQSeries including CICS 181 'Read Data into form of Document searched with NoteID DocID$ = Trim$(Mid$(msgin$,48,8)) 'Get NoteID of corresponding Doc from Queue string Set ParmDoc = db.GetDocumentbyID(DocID$) Print "Document opened" ParmDoc.Status = Left$(msgin$,1) ParmDoc.CustomreNumber = Mid$(msgin$,2,6) ParmDoc.CustomerName = Mid$(msgin$,8,20) ParmDoc.Item = Mid$(msgin$,28,20) ParmDoc.Date = Mid$(msgin$,56,8) ParmDoc.Amount = Mid$(msgin$,64,8) ParmDoc.Comment = Mid$(msgin$,72,9) Call ParmDoc.Save(True, False) After this we added some queue cleaning code and some error message handling. The complete code of this agent can be seen in Appendix C, “Sample LotusScript agent code” on page 221. 182 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Chapter 11. Building an enterprise application An enterprise application is a solution that is spread across more than one subsystem. In our redbook, an enterprise application consists of two parts: first, a Notes or Web part, consisting of a user interface, some business logic, and some data stored in Notes databases; second, an enterprise subsystem that hosts the main data storage, such as a DB2 database or VSAM files. It may also contain the main business logic of the solution, such as a CICS application. The design of such an integrated solution is more complex than using a single application environment. But its business benefits outweigh the complexity. The design of an enterprise application and the decision of which tool to use in your solution are essential to the successful implementation of the application. If concept errors or wrong assumptions are made during the design, the effect will not be visible until the application is completed and tested. Lots of time and effort will have been spent, yet major changes will be necessary. The choice of the tools for the application is based on early concepts. So be very careful about planning the application. It pays to research carefully and document an application design concept early. 11.1 The three models of connector techniques The connector tools in this book can be divided into three different models, according to the way they connect to the enterprise data: DECS, LEI, and programmatic. It is essential to fully understand the way these tools work to integrate them in an enterprise application. If one of the declarative (non-programmatic) tools fits the solution, much time can be saved. All models provide read and write access to the enterprise subsystem. For detailed information about the tools, refer to Part 1 of this redbook. 11.1.1 The DECS model The DECS model provides declarative real-time access to enterprise data using a fixed interface. DECS connects to enterprise databases such as DB2. For each row in the database, at least one key field must coexist in the connected Notes database; this redundant data is necessary. The rest of the fields of a document are synchronously retrieved from or updated to the enterprise © Copyright IBM Corp. 2001 183 subsystem. DECS stores an internal table that defines the relationship between each row in the enterprise database table and each document in the Notes database. The event-driven activation of the connection to the enterprise data for reading, writing, or deletion is done by the Domino extension manager using events monitoring. The open, update, create, and delete events on Notes documents are available. The relation has to be initialized for each document, or once for all documents, in order to work. The connected enterprise subsystem tables are statically defined for each connection. DECS connects to one table per connection. 11.1.2 The LEI model The LEI model provides a declarative batch job data transfer or synchronization tool. LEI is an asynchronous data transfer tool. It can transfer large volumes of data in either direction between any two data sources, such as between Domino databases and DB2 tables. The transfer can be used for redundant data storage in two data sources. It can also be used for moving data from one data source to another. The data transfer generally happens asynchronously in the background in a scheduled or manually activated execution. The connected enterprise subsystem tables are statically defined for each connection, usually with one table per connection. 11.1.3 The programmatic connector model The programmatic connector model provides flexible real-time access or a transfer tool for low volumes of data. Connectors include LCLSX, LS:DO and MQLSX. This model provides data access to server databases such as DB2, as well as through MQSeries middleware to transactional enterprise applications. The access modes are flexible. Synchronous real-time access as well as asynchronous scheduled access is available using all types of Notes events and activation functions. The connectors can also be used from a client, which requires having client code from the enterprise subsystem. The programmable connections code can be embedded in LotusScript code. Different enterprise subsystem tables can be flexibly handled. 11.2 Solution architecture considerations The most important decision is which of the three connection models will be used in the enterprise application. The easiest way to connect to host 184 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products systems is by using declarative connectors. So in most cases you will use this method. The decision should be based on examining the solution design. Since we cannot cover all possible enterprise application scenarios, the following sections discuss points to consider and supply sample statements for each point. These checkpoints can be used as a template for evolving the technique to interface Domino with the enterprise data. Certain situations are highlighted by using a table if they seem critical. You can tell how suitable a connector model is for the scenario by the number of minuses or pluses shown in the table. 11.2.1 Existing enterprise data If you have enterprise data to connect to, you should consider the following points before designing the solution: • Study the structure of the enterprise data or application before designing application. What is fixed and what can be changed? • For transactional applications, study application logic. Embed application logic in the solution. Define the interface fields using MQLSX as the Domino and the enterprise subsystem MQ interface. • For databases, study the database definition and the tables that you need to connect to. Understand the model of the database. 11.2.2 Size of master database Consider the number of rows in the database. The bigger the database, the more probable that you will use programmatic connectors; see Table 6. Table 6. Size of master database Condition Very large enterprise databases above Domino limits DECS - LEI - Prog + If no enterprise data exists, see if the amount of data can be handled by a Notes database without an enterprise subsystem. Or, is redundant data (copies of same data in both systems) possible (DECS or LEI)? Is the number of rows greater than the number of documents being handled by a Domino database with sufficient performance (less than ten up to hundreds of thousands of documents)? Will the large views involve many calculations? If the total number of documents is too large for a Notes database or view to handle with good performance (see Performance Considerations for Domino Chapter 11. Building an enterprise application 185 Applications), DECS is not the right choice for your system. Can you have partly redundant data using LEI selection formulas that transfer only a subset of the records? Think about how to build the logical data connection. Which rows will be a Notes document? Which rows can be multivalue fields or lists in a Notes document? 11.2.3 Updating or reading of enterprise data Table 7. Updating or reading enterprise data Condition Updating in geographically distributed applications DECS + LEI - Prig + When reading the data, choosing the connector model depends on: • How often the data is changed • How up-to-date the data has to be • The distribution of the data When updating enterprise data, here are some things to consider: • If the Domino database that accesses the enterprise system is distributed over more than one server or workstation, redundant data might cause conflicts when the same document is modified by more than one person on different replicas. Synchronous access to the data using DECS or a programmatic connector is preferable. For example, you could have a distributed Notes database with access to a central enterprise database system through the Domino server. • Be aware of transactions in enterprise systems using the programmatic connectors. • LEI is normally asynchronous. So updates in the enterprise system won’t be executed immediately. LEI has a replication mechanism. For details, refer to Chapter 3, “Introduction to Lotus Enterprise Integrator (LEI)” on page 29. On the other hand, updates issued by DECS or programmatic connectors are carried out immediately on the host system. 186 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products 11.2.4 Redundant data or direct enterprise access Table 8. Redundant data or direct enterprise access Condition Redundant storage (data in host and Domino) Direct access: enterprise data lookups and updates over one table Direct access: enterprise data lookups and updates over a number of tables DECS + ++ - LEI ++ - Prog ++ ++ As Table 8 shows, LEI is a good choice for setting up redundant data storage. In this type, some or all of the data resides in both the Domino database and the host system. DECS (an OK choice for redundant data) sets up one document per DB2 record in the Domino database. DECS always stores at least the keyfield in the Domino database; it may store some of the other data fields as well. The contents of all the fields is stored only in the host system. Storing all fields redundantly in Domino using DECS would not make sense, since the Domino database would then be all that is needed for your application. The programmatic model enables you to work with either redundant data storage or truly non-redundant direct access to the enterprise subsystem. If pure direct enterprise access is used, you don’t need to worry about data conflicts. The host system will take care of conflict management. But only small amounts of data at a time can be accessed. This can be done using the programmatic connectors or DECS. On the other hand, redundant data storage can move high volumes of data and enable offline work, for which LEI is the preferred tool. The choice is strongly dependent on the distribution of the data, the update intervals, and the need for the enterprise data to be up-to-date. 1. Intervals of data usage and updates • Short intervals of updating may keep the working data up-to-date. The only way to accomplish this with LEI is to have a single Domino database on one server. This way, replication conflicts would be eliminated. The update of the host system would be delayed. • DECS can handle frequent update intervals on the host system, but only with a small number of tables. Chapter 11. Building an enterprise application 187 • Complex updates over many tables should be done using the programmatic model. If you choose a server-based programmatic approach, be aware of performance limits in an application that calls for massive parallel accesses. 2. Parallel workload Table 9. Suitability of connector model Condition Massively parallel data access to Notes database and single point of asynchronous data transfer to host system. Massively parallel data access to Notes database and multiple distributed point of data transfer to host system. DECS + + LEI ++ - Prog -- • Massively parallel workloads should not be handled using programmatic access to a server, since they might experience performance problems. • DECS provides fast performance in synchronous enterprise system connections. A complex relational model could present major difficulties though. Be aware of missing locks with enterprise data while editing the document in Notes. 3. Accessing distributed data • As long as the data is accessed for reading only, all connector models are suitable. There should be no concerns with data consistency. • When you incorporate distributed updates into your architecture, the updating model has to be designed very carefully. For detailed information, refer to 11.3, “Considerations when updating data” on page 189. 4. Offline work necessary Table 10. Suitability of connector model Condition Offline work with data on a laptop DECS -- LEI ++ Prog + If offline work is necessary, the best tool to use is LEI. It lets you produce redundant copies of the enterprise data on a laptop in the form of a Notes database. If you need a flexible method and you don’t have to move large amounts of data, you can design a solution based on asynchronous agents using programmatic tools. 5. Interfaces to other applications existing, planned or possible Always keep in mind the possibility of interfacing to other applications, when designing your enterprise solution. 188 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products 6. Web browser or Notes Client All three models supply good access methods for Web browsers and for Notes clients. Note: A Web-related problem will be fixed in an upcoming version of DECS. It is described in SPR # YASI4P64QZ. 7. Is a generic model possible? When you create a solution, especially using the programmatic model, always consider a generic approach to your enterprise connections. - Use reusable connector modules for enterprise data access. - Try to define an overall interface model to your connector modules. - Use parameter input instead of hardcoded parameters in the connection code modules. - Use Notes databases as containers for easy-to-administer connector modules parameters. 11.3 Considerations when updating data When connecting a Domino application to an enterprise system, two different system concepts are involved: loosely-structured documented-oriented Notes databases and structured relational databases. This could cause problems, especially when updating. Compared to relational database systems on enterprise servers, Domino has loose data consistency techniques. This is by design, because Domino databases offer easy data distribution without much administrative overhead or the need for special system capabilities. The main intent of Domino databases is to share and distribute information. 11.3.1 Comparison of the two different data management concepts Domino doesn’t offer complex transaction management, unlike a DB2 database which is created for handling business transactions. Even though Domino offers transaction logging on a certain level, it doesn’t provide a programmable commit or rollback. Domino also doesn’t offer the referential integrity found in relational database systems for maintaining data consistency (correctness of data). Domino databases are based on redundancy. Domino doesn’t rely on a relational data model. It is a data container model without any relationship of levels between data. Chapter 11. Building an enterprise application 189 Domino records any conflicts when replicating or saving. This is a partly automatic, partly manual resolution mechanism for distributed data. This mechanism cannot be matched directly to a relational database, because it overrides referential integrity. Therefore, when transactions or referential integrity are used on an enterprise system, data is kept in a normalized form. This means there is no redundant data between tables. This must reflect the Domino part of the application. So these enterprise system concepts have to be incorporated in the enterprise application design. 11.3.2 Considerations when updating enterprise data If an enterprise application updates a host database, its design should reflect one of these two principles to minimize data inconsistency: 1. Use synchronous real-time updates to the enterprise system. This gives an immediate response to the user during data consistency failures by using popup messages. 2. For asynchronous update access, use one logical point of access to the enterprise database. This means only one user ID should transfer the data to the enterprise system, with no parallel paths. Try to assure a certain level of data consistency before updating the data to the host database. Of course, there could be reasons for not designing an application in these ways. For example, it can be very powerful to hold a subset of the host data in a Notes database, work on the data, and write the modifications as updates to the host data. This approach is also used in the LCLSX and LS:DO example in this redbook. With this technique, enterprise data can even be modified offline on a laptop. The data can be updated in the host system when logging into the LAN, for example. LEI or programmatic access to the enterprise system can be used in this solution. This scenario implies that some additional data locking mechanisms are included in the application design and implemented in the Domino application. When using DECS with update access to the host system, you might also need to consider data locking while data is being modified in Notes. The scenario in Figure 105 on page 191 could happen. The computer symbol denotes access to the enterprise data. The fetched data is stored in a Notes database, modified, and updated at the enterprise system after a period of time. The enterprise data access can be issued by servers or clients using 190 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products LEI direct transfer, DECS, or programmatic access. The fetch of enterprise data on the right is executed after the one on the left. The update of the left “old data” contains the modifications of the left. The right-hand update is done having the modifications of the right and overwriting the modifications of the left. Thus the modifications from the dotted arrow are lost. Figure 105. Update timing problem with multiple asynchronous data modifications To avoid such a scenario, one solution would be to add a column to each critical table. This column would contain a locking flag, to be managed and checked by the Domino application. 11.3.3 Transactional considerations Domino and S/390 enterprise subsystems both feature transaction logging. Domino transactions Domino Release 5 features transaction logging, which can be activated by database. The units of work are fixed and cannot be programmatically changed. A Domino transaction unit of work can, for example, consist of saving a Notes document. When transaction logging is activated and a user executes a save of a document, it is written to a sequential log. As soon as the log entry is done the user can continue working. Later the changes are physically written to the Notes database. Domino logging is used for database backup, recovery and fixup, improving server start time after crash, and for increasing performance. It cannot be used for business transactions. For further details, refer to the Domino Administration Help database. Chapter 11. Building an enterprise application 191 S/390 transactions S/390 subsystems such as CICS and DB2 provide transaction management. This means that the unit of work, which defines what to do in a transaction, is flexible and can be set dynamically in the application code or SQL statements. In this way, several program steps or update accesses across different tables can be combined into one unit of work. The execution of this unit of work would be the business transaction. Each transaction is committed at the end, which causes the updates to be written permanently. If a system crashes, the whole transaction can be rolled back to bring the data to a consistent state. 11.3.3.1 Using transactions with connectors DECS doesn’t offer transaction parameters. Each single update to a relational database is treated as a DB2 transaction. LEI features some DB2 transaction settings, as shown in Figure 106. Rollback can be activated and the unit of work can be varied, after which the commit is issued. Figure 106. LEI transaction option LCLSX features flexible DB2 transaction handling. The number of operations between commits can be set in the LCConnection.Properties. Manual commits and rollbacks can be executed using LCConnection.Action. For detailed information, refer to the LCLSX documentation. MQLSX can trigger CICS transactions using MQSeries. The result of a CICS transaction can be received in Domino through MQSeries. MQSeries itself works in a transaction-based manner. Some applications may require transactions across more than one table of a DB2 database or across different application steps. This can be done using a CICS application or the transactional DB2 access. When using a DB2 transaction, the logic has to be implemented in a Domino application using 192 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products LCLSX transaction handling. If a transaction-based CICS application is available, the usage of the CICS transaction with MQSeries would probably be the best solution. 11.4 Performance considerations Here is a list of general performance tips: • Large amounts of data movement should done using LEI. • DECS provides fast enterprise data access through a Notes document. • Programmatic enterprise data access provides good performance on smaller volumes of data (fetching or updating 10% of a database with medium-size documents). • Performance depends on the LAN or WAN network connection throughput and bandwidth. It also depends on the size and workload of the computer system. • LCLSX performs better than LS:DO. Performance can even be enhanced using LCLSX connection pooling. • Avoid massively parallel access when using server-based connector programming. If performance and a high host workload is an important issue, consider using programmatic access on the Notes Client. This involves installing the client of the enterprise subsystem on each workstation. 11.4.1 Mapping complex relational models to Notes Databases To map a relational database to a document-based database such as Lotus Notes can be very challenging. It depends on the complexity of the relational model of the enterprise subsystem. It is impossible to mirror a complex relational database completely with a Notes database. Every relationship has to be maintained manually using application logic. Data inconsistency would be a major concern. DECS and LEI need a one-to-one relationship between each form activity and DB2 table. Activities can be ordered and combined in a specific manner. Some calculations and transformations can be done using the formula language or LotusScript codes in the options; however, this might be time-consuming and costly in performance. Programmatic access can be easily adapted to complex relational models. The hard part is the nonrelational concept of Notes document storage. As we Chapter 11. Building an enterprise application 193 mentioned, it is impossible to maintain a complex relational model in Notes with a reasonable amount of effort. So to integrate Domino databases with complex relational table models of relational databases, here are some suggestions: • Simplify the subset of data of the relational model which has to be accessed by Notes, especially if updated by Notes. • Consider using updatable views for data entry to simplify the relational structure of fetches and updates. Be aware of limitations with updatable views. Refer to the relational database documentation. • Create a detailed concept, including which table rows are going to be loaded in Notes documents and which rows are being loaded as multivalues or lists. The “row to document” relationship is easier to maintain, but sometimes it is not possible to create a document for each row in each table. • Be careful of transactions where the unit of work is spread over multiple tables. 194 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Appendix A. DECS activity options This appendix provides a detailed look at the activity options that are available in DECS. A.1 General options The general options available are shown in Table 11. Each general option is discussed in turn, and business scenarios for their use are explained as well. Table 11. General options General option Monitor Order Description The Monitor Order option is used if you use more than one real-time activity for a single Domino form. You may specify the order in which the realtime activities will intercept the document’s events. Business application Monitor Order acts like an SQL Join. The monitor order option should be used when the external data sources you are accessing are not from the same relational environment. If you have employee data on DB2 and work information on Oracle, you can specify order 1 for the DB2 activity. That activity will extract a department number which is used by the Oracle activity to extract department data using order 2. Note: You must specify keeping selected real-time fields or all real-time fields so that follow-on activities can process. © Copyright IBM Corp. 2001 195 Maximum Connection s Realtime activities can open more than one connection to the external data source. The higher the number you enter here, the better your performance will be when a very large number of users access documents at the same time. Note: During the reading or editing of a document, a connection is idle and available to service other users. This means that two users can use the same connection, provided either of them is idle at any one time. This is also described as pooled connections. Once a connection has been established, it will remain active until its associated activity is stopped. Any Domino database you have that has a high usage rate and is monitored by DECS would qualify to have its maximum connections option increased. This option would be useful in centralized applications where one Domino database using DECS to access external data would be used by many people. Information such as a company directory would fall into this category. We recommend using a value of 2 or 3 in this field to start. Note: A high number of connections for any application may require a communication server installed with Domino instead of a communication client. Form Override Selecting this option causes the real-time Activity to process the selected events for all the documents in the Domino database, regardless of the form. This option is useful for databases that contain forms that use a common set of fields or a common subset of fields, provided all the forms have the mapped key fields. This option is used for views that use form formulas or documents that change the form field. This option can also be used along with the Filter Formula option. 196 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Filter Formula This option allows you to create a formula that defines the documents that the real-time Activity will monitor. For all events, you can only reference fields stored in the Domino documents. Combining a filter formula with the form override allows you to restrict which forms should be processed by your activity. Click Form Override to on, and add a Filter Formula of Form = “Memo” | Form = “Reply” which forces DECS to process only the Memo and Reply forms. Another useful application for Filter Formulas is to control submission of data to the external system. If you want to only create or update external data that is flagged as public and not in process in your Domino database, your Filter Formula would be Status = “public.” Any application of these settings must be set so that they conform with your integrity requirements. When you use the first option, you run the risk of creating many log entries for your activity. This may be an acceptable start for a new DECS process; however, the errors must be handled, rules must be established, and then you can change to the option to Allow precision loss. Tight control of integrity may require the use of a data dictionary to control Domino field lengths and dynamic validation formulas that use a dictionary to perform length checks. This degree of control would be necessary for Create and Update events. Should you miss any validations, you must decide if the Domino data can be truncated or if you will risk precision loss (option three versus option two). Data Integrity: There are three levels of data integrity. The level affects what happens when data is sent between the Domino document and the external data source. Prevent both precision and data loss: - this option will write an error to the Log for any data loss resulting from a data type conversion. Allow precision loss: this option will not report loss of numerical or datetime precision as a result of a data type conversion. Allow precision loss and truncation of text (excluding key fields): - in addition to precision loss, this option will truncate text data when necessary to conform to field lengths in the external data source. Key fields will not be truncated even with this option selected. Appendix A. DECS activity options 197 Trim Trailing Spaces This option affects any trailing spaces that exist in the Text fields of the external data source. There are three choices: Trim spaces on all fields: - select this setting to trim trailing spaces from all text fields. Trim spaces on all non key fields: - select this setting to trim trailing spaces only from data fields, not from the key fields. Do not trim spaces on any fields: - select this option to leave trailing spaces in all fields. External data sources will pad blanks or other unreadable data at the end of their fixed length text fields. When these fields are read by DECS, the unreadable data is converted to spaces and placed in Domino. This will cause odd presentation of retrieved data. Domino data will wrap to the next line in a form. Domino views that categorize on retrieved data will react oddly to column formulas. If you match any data between Domino and the external data source, do not trim the spaces. If you find matching is still not correct, consider changing the fixed text format in your external data source to variable length (that is, from CHAR to VARCHAR). Note: Trimming only occurs when reading data from the external source. 198 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Caching This option is used to disable caching in the HTTP server for monitored documents. When a document is retrieved, the HTTP server in Domino may cache it to avoid disk access for the next retrieval. For rarely changing external data source records, caching may be fine. For a realtime situation with changing data, caching should be disabled. An unchecked caching option will enable it. Use this option for reference material available over the Internet. Employee handbook information, company policies and product White Papers are just a few applications where caching should be enabled. Order entry or order status systems are more dynamic and would require caching to be disabled. Note: Keep in mind that this is a Disabling option, not an Enabling option. This option is only effective in Domino’s HTTP server. Appendix A. DECS activity options 199 Data Storage Remove All Real time Fields from Documents: - use this option if you want to remove all the data fields mapped in the Activity from the Domino document before it is saved to disk. This is the default. Leave All Real time Fields in Documents: use this option if you want to leave all the data fields in the Domino document, rather than removing them after updating the external source (see above). This option only takes effect when creating or updating a document when the Activity is active. Opening the document and making no changes does not trigger this option. Leave Selected Real time Fields in Documents: - use this option if you want to leave selected data fields in the Domino document. The Save Fields button that appears when you enable this option lists the Domino data fields from which you can select. Selecting one of these options may not be a preference for you to decide. Look at your integration requirements to determine if any of these options must be set. When using the Open event only, the default option is enough. You may feel that keeping all the fields on the form will improve performance. It is not so. The Open event will always retrieve data, whether you store the data or not. In some cases, the default performs better. The first option is best for reference- based or inquiry-based Domino databases that do not update the external source. Standard examples like a company directory are quite possible, provided the Domino database is not used for input. The next two options have more unique uses. If you will be using the Update event, you must store any fields identified as key fields in other activities (see Monitor Order). This means that the key field is always stored, no matter what you select here. If you use the Open event and the Monitor Order option, fields required by the follow-on activities must also be stored. Using the company directory as an example, assume your Domino database has a directory view containing some of the data retrieved from the external source. Those fields referenced in the view must be stored in your form. Note: For option three, you must select at least one data field; otherwise the default option applies. 200 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products A.2 Create event options The create event options available are shown in Table 12. Applicable business scenarios are included, along with the descriptions to help you use these options. Table 12. Create event options Create event option Pre-Create Formula Description This option runs a Domino formula before the document data is stored in the external data source. This provides an opportunity to compute additional fields or modify existing fields. This option runs a stored procedure in the external data source system to store data that has been entered in the document. Business application You can build a formula using the Domino formula language. Use this to manage fixed lengths, apply default values to blank fields, or compute hidden fields that are mapped. If you have a Call Center application in Domino that stores call information in your external system, you can use a formula to set a random call identifier: FIELD Call_ID:= @Unique In this example, Call_ID must exist as a computed field and must be mapped to the external data source. Your current company directory on your external system uses defined procedures to manage input. These procedures may be defined to distribute results to multiple external tables. Now that you have moved to Domino, you want to integrate the fastest way possible. Enter the name of your stored procedure in this field and press F9. DECS will retrieve the input parameter requirements for that procedure and present them to you. For each parameter, select the Domino field that corresponds to the input parameter and then let DECS integrate with your stored procedures rather than your external tables. Stored Procedure Appendix A. DECS activity options 201 A.3 Open event options The open event options available are shown in Table 13. In this section, each open event option is discussed and applicable business scenarios are listed to help you use these options. Table 13. Open event options Open event option Post-Open Formula Description This option runs a Domino formula after the document data is retrieved from the external data source. Business application You can use this formula to change retrieved data that can be expanded or translated to take advantage of the Domino interface. You can modify names, coded fields (such as 1 for yes or 0 for no). Note: Do not use a Post-Open formula together with the Conflict Detection item in the Update Event Option as this would continually flag your document as a conflict and never update the external source. 202 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Stored Procedure This option runs a stored procedure in the external source to determine the data that will be retrieved into the document. The realtime keys are supplied to the stored procedure as input parameters. The stored procedure must produce a result set with both the keys and fields present. If no matching record is found in the external data source when opening a document, there is the option to create a new record in the external system, generate an error which will appear as an error box for Notes clients, or ignore the error and allow the document to continue opening but without any external data. This option can be used for the same reason you would use it in the Create Event options, except in the reverse direction. With your company directory on your external system, Domino has an application that is used for viewing this information. The external system used a stored procedure to do this; now you can use Domino instead. Enter the name of your stored procedure in this field and press F9. DECS will retrieve the input parameter requirements for that procedure and present them to you. For each parameter, select the field that corresponds to the input parameter and then let DECS integrate with your stored procedures rather than your external tables. Missing External Records You may find this option an important one to deal with. Issues like this involve ownership and direction of data integration (that is, is the data moving both ways or one way — from Domino or to Domino). The default option to generate an error will notify the client that the external data record is not found. For environments where the external source is the owner or master of the data, use Generate Error or Ignore. If Domino is the Master, use Create Record. If your application, the company directory, allows data entry from both sides, you will have to decide the best option. Note: Deletions from the external source will not be noticed by DECS, therefore making the Create Record choice is dangerous. If the external source is the master—do not use Create Record. Appendix A. DECS activity options 203 A.4 Update event options The update event options available are shown in Table 14. In this section, each update event option is discussed and applicable business scenarios are listed to help you use these options. Table 14. Update event options Update event option Pre-Update Formula Description When a document is updated (edited, then saved), this option runs a Domino formula before the document data is saved in the external source. This gives you the chance to change field values. Business application This is very similar to the Pre-Create formula and usually they are the same formula. Typically you will want to create or update records in the external source using the same rules. Note: Be aware of your Conflict Detection option when using a Pre-Update formula. Do not let your choices conflict. The Pre-Update formula is run before conflict detection is determined. See the Create Event Option Stored Procedure option. Both the create and update options may have similar stored procedures. If these stored procedures are different, this is a decision made at the external source. Update procedures may generate reports that create statistics unique to updates. Follow the guidelines put forth by your external system. Stored Procedure When a document is updated, you have the option to run a stored procedure in the external source. This will store the data that has been changed in the document. The realtime keys and fields are supplied to the stored procedure as input parameters. 204 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Conflict Detection This option ensures that the external data has not changed since the document was opened. If it has changed, the update to the external source will fail. This option is very useful when many people have access to your Domino database. Team databases, where any one external record can be updated by the team, can make good use of this option. Note: See the Post-Open formula option for conflict detection restrictions. Note: Each time you edit and save the Domino document, an update event occurs. With conflict detection on, you cannot edit and save in more than one edit session. Exit the document and reopen each time you want to update data. Field Level Updates This option causes the real-time Activity to not update fields in the external data source unless the same fields in the Domino document have been edited. External applications that monitor data activity may require the setting of a field to indicate a change has occurred. An interesting example of this is to update a trigger flag in the external source each time the Domino document changes. Have Lotus Enterprise Integrator (LEI) poll the trigger and then use an LEI direct transfer or replication activity to move the change to another external data source. The trigger in Domino can be set using the Pre-Update formula or a QuerySave event. Appendix A. DECS activity options 205 Key Field Updates Block: Do not allow updates to key fields in the Domino document or the external data records. Delete/Insert: Updates to key fields will cause the original record in the external source to be deleted and a new record with the new key added. Ignore: Do not update the key fields in the external source. If a key field is edited, the change will be stored in Domino but the key fields in the external source will not change. Block is the default in this situation and is the better choice. For a realtime activity that is only updating, Block should be used. Your external systems may control key creation and deletion and therefore should have their activity simplified by using this. Delete/Insert is the opposite. It allows all key changes to go through. The Ignore option is not common but available. For situations where you want to deposit data but do not know the key, DECS will move your update, but its reference will be gone after the key change in Domino. This may be sufficient for survey responses and any application where Domino “Depositor” access is used. Note: DECS uses the Connection ID that you specified in the connection document. This ID has full access to the external source and associated user account privileges defined. To limit who makes updates or changes in general, consider using options like this in combination with strict Access Control List (ACL) settings, document security and roles. 206 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products A.5 Delete event options The delete event options available are shown in Table 15. In this section, each delete event option is discussed and applicable business scenarios are listed to help you use these options. Table 15. Delete event options Delete event options Pre-Delete Formula Description When a document is deleted, this option runs a Domino formula before the document data is removed from the external source. This provides you with a chance to create or modify fields. Note: The external account ID associated with the connection document must have deletion rights to delete external data. Business application When you delete an external record, you may want to log the occurrence. You can create a Pre-Delete formula that mails document information to a log database for audit purposes. Note: You should indicate that the fields used in the pre-delete formula be saved on the document, otherwise they will be blank. Stored Procedure When a document is deleted, this option executes a stored procedure in the external source to remove the data related to the document. The realtime keys are supplied to the stored procedure as input parameters. External systems that have stored procedures for deleting data can be used by DECS. This allows you to easily integrate Domino into your existing processes. If you have a stored procedure that logs deletions on the external system, enter the procedure name, press F9 and you will be presented with the available input parameters. Appendix A. DECS activity options 207 208 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Appendix B. LC LSX class properties and methods This appendix shows the properties and methods for the LSLSX classes. B.1 LCSession The LCSession class provides error information useful in error handling. It also provides for query and lookup of available connectors (see the first example). You do not need the LCSession class to connect to a data source, but it is recommended because it gives good error feedback. The following tables list the LCSession properties and methods. See the LC LSX documentation for syntax and details. LCSession property Status Description Status of an LCSession. Zero, or LCSUCCESS, indicates no error. A non-zero value (represented by an LCFAIL_XXX constant) indicates an error state. LCSession methods ClearStatus GetStatus GetStatusText ListConnector ListMetaConnector LookupConnector LookupMetaConnector Sleep Description Clears the Session status, putting the Session in a non-error state. Obtains the current Session status. Obtains the error text string corresponding to a status code. Lists all installed connectors available for LC LSX. Lists all installed metaconnectors available for an LC LSX installation. Determines if a specified connector is available. Determines if a specified metaconnector is available. Suspends script execution for a specified period of time. © Copyright IBM Corp. 2001 209 B.2 LCConnection The LCConnection class represents an instance of a Lotus connector. This class provides query and data access to the external system. Multiple instances of an LCConnection class can be allocated to a single connector. LCConnection properties depend on the specific connection. Typical properties include LCConnection.Database, LCConnection.UserID, and LCConnection.Password. The following table lists the LCConnection methods. See the LC LSX documentation for syntax and details. LCConnection methods Action Call Catalog Connect Copy Create Disconnect Drop Execute Fetch GetProperty GetProperty Insert ListProperty LookupProperty Description Performs one of a set of predefined actions, such as reset, truncate, commit, rollback, clear. Performs a connector-independent procedure call with parameters. Produces a result set containing a metadata catalog. Establishes a connection to a data provider. Copies an existing connection. Creates a new metadata object. Disconnects from a data provider. Drops an existing metadata object. Executes a statement against the data source. The statement is provided in the data source’s language. Retrieves records from the current result set. Gets a property value for a connection. Gets a property as a particular data type. Inserts new records into the data provider. Lists supported properties and values. Verifies the support of a property. 210 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Remove Select Removes records from the data source. Key values are provided. No keys are required for writeback operations. Performs a connector-independent selection controlled by various connector properties. Conditional key inequalities, timestamp, and other control is supported. Sets a property value for a connection. Sets a property as a particular data type. Updates records in the data source. Key values and update values are provided. No keys are required for writeback operations. SetProperty SetProperty Update B.3 LCFieldlist The LCFieldlist class is the primary class for manipulating data through a connection. It binds a group of fields together with names and a default order. When you generate a result set and pass in an empty fieldlist, the connector automatically populates the fieldlist. For each data element of the result set, the fieldlist receives the element’s name and an LCField object of the corresponding data type. The result set can be controlled by manually building the fieldlist before generating the result set, or by using the FieldNames property of the connection (see FieldOut in the example on LCFieldList). The Select and Call connection methods use an optional fieldlist of keys or parameters to restrict the result set. You construct this fieldlist manually and pass it to the Select method. You construct a key or parameter list by appending or inserting names and datatypes to the list. These methods create fields in the fieldlist and return the fields for further manipulation. The fields are then given values and, using field flags, can be given conditions such as greater-than and not-equal (see keyList in the example on LCFieldList). The following tables list the LCFieldlist properties and methods. See the LC LSX documentation for syntax and details. LCFieldlist properties FieldCount Fields Description Long. Read-only. Number of fields in a fieldlist. Variant. Read-only. Array of LCField objects. Appendix B. LC LSX class properties and methods 211 Names RecordCount Sequence Variant. Array of strings. Long. Read-only. Number of records per field. Long. Read-only. A fieldlist sequence number. LCFieldlist methods Append Copy CopyField CopyRef GetField GetName IncludeField Insert List Lookup Map MapName Merge MergeVirtual Remove Replace SetName Description Appends a field to an existing fieldlist. Creates a duplicate copy of an LCFieldlist and all its data. Copies an existing field within a fieldlist at a specified position. Creates a new FieldList object as a partial copy of another fieldlist. Gets a field reference from a fieldlist result set and places its value into a variable. Gets a copy of the name of a field within a fieldlist. Includes an existing field in a fieldlist. Inserts a new field into an existing fieldlist at a specified index position. Iterates through fields in a fieldlist, optionally returning information. Locates a field in a fieldlist based on the field name. Remaps fields in a fieldlist. Maps fields with different names. Merges two fieldlists, creating a new mapping fieldlist. Merges two fieldlists, creating a new mapping and virtual fieldlist. Removes an existing field from a fieldlist. Replaces a field within a fieldlist. Changes the name of a field within a fieldlist. 212 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products B.4 LCField LCField is a storage class that contains one or more data values. The data type of a field applies to all the values and can be one of the four advanced datatypes. The following tables list the LCField properties and methods. See the LC LSX documentation for syntax and details. LCField properties Count Datatype Flags IsNull Text Value Description Long. One or greater. A counter for the fieldlist record count. Long. One of the Lotus Connector data types. Long. Zero or more field flags. Boolean. True or False. String. Array of string elements. Array of LotusScript data types. The values in the array depend on the data type of the field. LCField methods ClearVirtualCode Compare Convert Copy GetCurrency GetDatetime GetFieldList GetFloat GetFormatNumber GetFormatStream Description Clears the specified virtual code for the field. Compares data values between two fields and returns the relationship. Converts data values to the data type of the destination field. Creates a copy of a field. Retrieves a currency data type from a value in a field. Retrieves a datetime data type from a value in a field. Retrieves a fieldlist from a field. Retrieves a LotusScript double data type from a value in a field. Retrieves the format of a number type field. Retrieves the format of a stream type field. Appendix B. LC LSX class properties and methods 213 GetInt GetNumeric GetStream LookupVirtualCode SetCurrency SetDatetime SetFieldList SetFloat SetFormatDatetime SetFormatNumber SetFormatStream SetInt SetNumeric SetStream SetVirtualCode Retrieves an integer value from a value in a field. Retrieves a numeric value from a value in a field. Retrieves a stream value from a value in a field. Check if a specific virtual code was set for a field. Assigns the currency value to the specified index of the field. Assigns the datetime value to the specified index of the field. Assigns the fieldlist value to the specified index of the field. Assigns a value to a field of type float. Assigns the current format setting for a datetime field. Assigns the current format setting for a number field. Assigns the current format setting for a stream field. Assigns a value to a field of type long. Assigns a value to a field of type LCNumeric. Assigns a value to a field of type LCStream (text or binary). Adds a virtual code to the list of virtual codes for a field. B.5 LCStream LCStream is a general purpose text and binary data type. A stream has a format that details the character set of the text and any special attributes of the binary data. Use it to store and manipulate text or binary data in the supported character sets. The following tables list the LCStream properties. See the LC LSX documentation for syntax and details. LCStream properties Flags Format Length Description Long. The flags for the stream. Long. The stream data format. Long. The length of the stream data. 214 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products MaxLength Long. Read-only. The maximum valid data length for the stream. Any value is valid, with a value of zero indicating no maximum length. Long. Read-only. Range of elements in a stream. Valid only for List formats. String. Text representation of the stream. Variant. An array. If the stream is a string, it is a one-element array. If the stream is a number or datetime, it is an array of numbers. It can also be an array of strings for text lists. Long. Read-only. Number of elements in a stream. Valid only for List formats. RangeCount Text Value ValueCount LCStream methods Append Clear Compare Convert Copy DatetimeListGetRange DatetimeListGetValue DatetimeListInsertRange DatetimeListInsertValue DatetimeListRemoveRange DatetimeListRemoveValue Extract Description Appends one stream to another to yield a third LCStream object containing the data from both. Clears a stream value and properties. Compares two LCStream objects. Converts a stream to a particular stream format. Copies one LCStream to another. Gets a range of values in a DatetimeList LCStream object. Retrieves a datetime value from a specified place in a DatetimeList LCStream object. Inserts a datetime range into a DatetimeList LCStream object. Inserts a value into a DatetimeList LCStream object. Removes a range from a DatetimeList LCStream object. Removes a value from a DatetimeList LCStream object. Creates a new LCStream object with part of the data from an existing LCStream object. Appendix B. LC LSX class properties and methods 215 Merge NumberListGetRange NumberlistGetValue NumberListInsertRange NumberListInsertValue NumberListRemoveRange NumberListRemoveValue ResetFormat SetFormat TextListFetch TextListInsert TextListRemove Trim Combines one stream into another, creating a new stream. Selects a particular range from a number list LCStream object. Retrieves a specified value from a number list LCStream object. Inserts a number range into a number list LCStream object. Inserts a value into a number list LCStream object. Removes a range of numbers from a number list LCStream object. Removes a value from a number list LCStream object. Resets the format of an LCStream object, without affecting the data or other properties. Sets the format for an LCStream object. Fetches a text list from a text list stream object and assigns it to another stream object. Inserts text or a text list into a text list LCStream object. Removes a string from a text list LCStream object. Trims trailing spaces from a text stream. 11.5 LCNumeric The LCNumeric class is a container for high precision numbers. The following tables list the LCNumeric methods and properties. See the LC LSX documentation for syntax and details. LCNumeric properties Precision Scale Description Long. Read-only. Precision and scale are set when the LCNumeric object is constructed. Long. Read-only. Precision and scale are set when the LCNumeric object is constructed. 216 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Text Value String representation. Double. Value conversion between Lotus connectors and LotusScript double. LCNumeric methods Add Compare Copy Subtract Description Adds two numeric values, producing the sum. Compares two numeric values, returning a value indicating the relationship between them. Makes a copy of a numeric value. Subtracts one numeric value from another, producing the result. 11.6 LCCurrency The LCCurrency class is a fixed point decimal data type with 4 decimal places and 19 digits of precision. (This data type is mathematically equivalent to the LotusScript data type and is provided to support connections with a dedicated currency.) The following tables list the LCCurrency properties and methods. See the LC LSX documentation for syntax and details. LCCurrency properties Text Value Description A string representation. The value of a LotusScript Currency data type. LCCurrency methods Add Compare Copy Subtract Description Adds two currency values, producing the sum. Compares two currency values and returns the relationship. Makes a copy of an LCCurrency object. Subtracts an LCCurrency value from another, producing the result. Appendix B. LC LSX class properties and methods 217 11.7 LCDatetime The LCDatetime class is a date and time data type that is accurate to the hundredth of a second and that specifies time zones and daylight saving time. The following tables list the LCDatetime methods and properties. See the LC LSX documentation for syntax and details. LCDatetime properties Day DST Hour Hundredth Julian Minute Month Second Text Ticks Value Weekday Year Zone Description Long. Day of month. Valid values 1 to 31. Boolean. Indicates whether daylight saving time is in effect. Long. Hours. Valid values 0 to 23. Long. Hundredth. Valid values 0 to 99. Long. The Julian date. Long. Minutes. Valid values 0 to 59. Long. Month. Valid values 1 to 12. Long. Seconds. Valid values 0 to 59. String. A string representation of the date. Long. Tick time representing the hundredths of seconds since midnight. Valid values 0 to 8640000. Variant. LotusScript Variant containing the datetime. Long. Read-only. Integer indicating the day of the week. Valid values 1 to 7. Sunday = 1. Long. Integer indicating the year. Valid values 1 to 32767. Long. Integer indicating the time zone. Valid values -12 to 12. LCDatetime methods Adjust Clear Compare Description Alters a datetime by a specified number of units. Clears a datetime value. Compares two datetime values, returning a value indicating the relationship between them. 218 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Copy GetDiff SetConstant SetCurrent Makes a copy of a LCDatetime object. Returns the difference between two datetimes in the requested time units. Produces a special constant Datetime commonly used for comparisons. Sets a Datetime value to the current system time. Appendix B. LC LSX class properties and methods 219 220 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Appendix C. Sample LotusScript agent code Here are all the agents we developed for the sample applications. They are listed by connector type. The original application code is also on the attached CD. C.1 LCLSX For each agent, the following statement is added to the options section of the agent: Uselsx "*LSXLC" C.1.1 Code of Fetch Employee keyed agent Sub Initialize On Error Goto Handler ' Declare Notes Objects Dim NSession As New NotesSession Dim DB As NotesDatabase Dim Agent As NotesAgent Dim count As Long Dim SQLString As String Dim hr_id As String Dim EmpDoc As NotesDocument'Fetched Row from DB2 Table Dim ParmDoc As NotesDocument 'Parameter Doc from Agent created by Button 'Declare LC Objects Dim Session As New LCSession Dim src As LCConnection Dim FieldOut As New LCFieldList ' Fieldlist populated after Select Dim KeyList As New LCFieldList ' key Fieldlist Dim FLDLastname As LCField Dim FLDFirstname As LCField Dim FLDEmpno As LCField Dim FLDDeptname As LCField Dim kfld As LCField ' Field used for the key Fieldlist 'Get Notes Docs Set DB = NSession.currentdatabase Set Agent = NSession.currentagent 'Read key Parameter from Agent Parameter Document Set ParmDoc = db.GetDocumentbyID(agent.ParameterDocID) Print "Parm Document opened, NoteID = "+ ParmDoc.NoteID tkey = Parmdoc.GetItemValue("LCKEY" ) Print "key " + tkey(0) + "fetched" 'Establish DB2 Connection Session.ClearStatus Set src = New LCConnection ("db2") '‘Create Connection object src.Database = "DB2G" src.Metadata = "DSN8610.EMPLOYEE_NO_BLOB" src.UserID ="FUST" © Copyright IBM Corp. 2001 221 src.Password = "lnotes" Print "Establishing Connection" src.Connect '‘Connect to db2 data source ‘EILLAB’ Print "Connection established" 'Create key fieldlist Set kfld = keylist.append("LASTNAME", LCTYPE_TEXT) kfld.Flags = LCFIELDF_KEY kfld.value = tkey(0) Print "Key is "+ tkey(0) 'Do a keyed Select on the table count = src.Select(keylist,1,fieldout) 'Set LC Fields Set FLDlastname = Fieldout.Lookup ("LASTNAME") Set FLDFirstname = Fieldout.Lookup ("FIRSTNME") Set FLDEmpno = Fieldout.Lookup ("EMPNO") Set FLDHierarchy = Fieldout.Lookup ("DEPTNAME") 'Loop over Resultset While (src.Fetch (Fieldout) > 0) 'Create Document for each Row / Resultset entry Set empdoc = db.createdocument empdoc.form= "Person" empdoc.Firstname = FldFirstname.text(0) empdoc.Lastname = Fldlastname.text(0) empdoc.Hierarchy = FLDHierarchy.text(0) empdoc.Empno = FLDEmpNo.text(0) Call empdoc.Save (True, False) count = count + 1 Wend ret = ParmDoc.Remove(True) 'remove Agent Parameter Document src.Disconnect '‘Disconnect from db2 data source ‘DB2G’ Exit Sub Handler: '‘Error Handler If ( session.status <> LCSUCCESS) Then Print session.GetstatusText, 0, _ + "The following Lotus Connector error has occurred." Else Print Error$, 0, _ + "The following LotusScript error has occurred." End If End Sub C.1.2 Code of Update/Insert Emp agent Sub Initialize On Error Goto Handler ' Declare Notes Objects Dim NSession As New NotesSession Dim DB As NotesDatabase Dim Agent As NotesAgent Dim count As Long Dim ParmDoc As NotesDocument 'Declare LC Objects Dim Session As New LCSession 'Parameter Doc = Employee Document 222 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Dim Dim Dim Dim src As LCConnection FieldLst As New LCFieldList kfld As LCField fld As LCField Set DB = NSession.currentdatabase Set Agent = NSession.currentagent 'Read key Parameter from Employee Document Set ParmDoc = db.GetDocumentbyID(agent.ParameterDocID) Print "Parm Document opened, NoteID = "+ ParmDoc.NoteID tkey = Parmdoc.GetItemValue("EMPNO" ) Print "key " + tkey(0) + "fetched" 'Establish DB2 Connection Session.ClearStatus Set src = New LCConnection ("db2") '‘Create Connection object src.Database = "DB2G" src.Metadata = "DSN8610.EMPLOYEE_NO_BLOB" src.UserID ="FUST" src.Password = "lnotes" Print "Establishing Connection" src.Connect '‘Connect to db2 data source ‘EILLAB’ Print "Connection established" 'Create key fieldlist to be updated or inserted Set kfld = FieldLst.append("EMPNO", LCTYPE_TEXT) kfld.Flags = LCFIELDF_KEY kfld.value = tkey(0) Set fld = FieldLst.append("LASTNAME", LCTYPE_TEXT) fld.Text = Parmdoc.Lastname(0) Set fld = FieldLst.append("FIRSTNME", LCTYPE_TEXT) fld.Text = Parmdoc.Firstname(0) Set fld = FieldLst.append("DEPTNAME", LCTYPE_TEXT) fld.Text = Parmdoc.Hierarchy(0) 'Do a Update on the table if the row exists (key = EMPNO) count = src.Update(FieldLst,1,1) Print Cstr(count) + " rows updated" ' Do a Insert if row doesn't exist (key = EMPNO) If count = 0 Then count = src.Insert(FieldLst,1,1) Print Cstr(count) + " rows inserted" End If If count > 0 Then ret = ParmDoc.Remove(True) 'remove Document only if Table has been updated/inserted End If src.Disconnect '‘Disconnect from db2 data source ‘DB2G’ Exit Sub Handler: '‘Error Handler If ( session.status <> LCSUCCESS) Then Print session.GetstatusText, 0, _ + "The following Lotus Connector error has occurred." Else Print Error$, 0, _ + "The following LotusScript error has occurred." End If Appendix C. Sample LotusScript agent code 223 End Sub C.1.3 Code of the delete row agent Sub Initialize On Error Goto Handler ' Declare Notes Objects Dim NSession As New NotesSession Dim DB As NotesDatabase Dim Agent As NotesAgent Dim count As Long Dim ParmDoc As NotesDocument 'Declare LC Objects Dim Session As New LCSession Dim src As LCConnection Dim FieldLst As New LCFieldList Dim kfld As LCField Dim fld As LCField Set DB = NSession.currentdatabase Set Agent = NSession.currentagent 'Read key Parameter from Employee Document Set ParmDoc = db.GetDocumentbyID(agent.ParameterDocID) Print "Parm Document opened, NoteID = "+ ParmDoc.NoteID tkey = Parmdoc.GetItemValue("EMPNO" ) Print "key " + tkey(0) + "fetched" 'Establish DB2 Connection Session.ClearStatus Set src = New LCConnection ("db2") '‘Create Connection object src.Database = "DB2G" src.Metadata = "DSN8610.EMPLOYEE_NO_BLOB" src.UserID ="FUST" src.Password = "lnotes" src.MapByName = True Print "Establishing Connection" src.Connect '‘Connect to db2 data source ‘EILLAB’ Print "Connection established" 'Create key fieldlist with key of the row to be removed Set kfld = FieldLst.append("EMPNO", LCTYPE_TEXT) kfld.Flags = LCFIELDF_KEY kfld.value = tkey(0) 'Do a Delete on the table if the row exists (key = EMPNO) count = src.Remove(FieldLst,1,1) Print Cstr(count) + " rows deleted" If count > 0 Then ret = ParmDoc.Remove(True) 'remove Document only if row has been deleted Print "deleted" End If src.Disconnect 'Disconnect from db2 data source ‘DB2G’ Exit Sub Handler: '‘Error Handler 'Parameter Doc = Employee Document 224 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products If ( session.status <> LCSUCCESS) Then Print session.GetstatusText, 0, _ + "The following Lotus Connector error has occurred." Else Print Error$, 0, _ + "The following LotusScript error has occurred." End If End Sub C.2 LS:DO For each agent, the following statement is added to the options section of the agent: Uselsx "*LSXODBC" C.2.1 The LS:DO Fetch Emps agent Sub Initialize Dim con As New ODBCConnection Dim qry As New ODBCQuery Dim result As New ODBCResultSet Dim Dim Dim Dim Dim Dim Dim Dim NSession As New NotesSession DB As NotesDatabase Agent As NotesAgent count As Long SQLString As String hr_id As String EmpDoc As NotesDocument'Fetched Row from DB2 Table ParmDoc As NotesDocument 'Parameter Doc from Agent created by Button 'Get Notes Docs Set DB = NSession.currentdatabase Set Agent = NSession.currentagent Print "LS:DO Agent" 'Read key Parameter from Agent Parameter Document Set ParmDoc = db.GetDocumentbyID(agent.ParameterDocID) Print "Parm Document opened, NoteID = "+ ParmDoc.NoteID tkey = Parmdoc.GetItemValue("LCKEY" ) Print "key " + tkey(0) + "fetched" 'connect to DB2G using "fust" ID and "lnotes" password If Not con.ConnectTo("db2g", "fust", "lnotes") Then Print "Could not connect to DB2G" Exit Sub End If 'execute the SQL against the Employee_no_blob table Set qry.Connection = con Set result.Query = qry SQLStr$ = "SELECT * FROM DSN8610.EMPLOYEE_NO_BLOB WHERE LASTNAME = '" _ & tkey(0) & "'" qry.SQL = SQLStr$ result.Execute 'iterate through the resultset If result.IsResultSetAvailable Then Do result.NextRow Appendix C. Sample LotusScript agent code 225 'Create Document for each Row / Resultset entry Set empdoc = db.createdocument empdoc.form= "Person" empdoc.Firstname = result.GetValue("FIRSTNME") empdoc.Lastname = result.GetValue("LASTNAME") empdoc.Hierarchy = result.GetValue("DEPTNAME") empdoc.Empno = result.GetValue("EMPNO") Call empdoc.Save (True, False) Loop Until result.IsEndOfData result.Close(DB_CLOSE) Else Print "No data retrieved " Exit Sub End If 'disconnect con.Disconnect End Sub C.3 MQLSX For each agent, the following statement is added to the options section of the agent: Uselsx "mqlsx" C.3.1 The WebMQPutOrder agent Sub Initialize 'Declare MQObjects Dim mqs As MQSession Dim mqqm As MQQueueManager Dim mqq As MQQueue Dim mqm As MQMessage Dim mqpmo As MQPutMessageOptions Dim mqgmo As MQGetMessageOptions Dim mqp As MQProcess Dim QueueName Dim Dim Dim Dim Dim Dim Dim Dim Dim Dim T ErrString PutMsg GetMsg msgout msgin As String As As As As As As String String Integer Integer String String db As NotesDatabase session As NotesSession Agent As NotesAgent ParmDoc As NotesDocument Set session = New NotesSession Set db = session.CurrentDatabase 'Read MQ string values from DocumentContext (Document where agent is activated) Set ParmDoc = session.DocumentContext Stat$= ParmDoc.Status(0) CustNumber$ = ParmDoc.CustomerNumber(0) 226 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products CustName$ = ParmDoc.CustomerName(0) Item$ = ParmDoc.Item(0) Phone$ = Cstr(ParmDoc.NoteID) & " OrderDate$ = Cstr(ParmDoc.Date(0)) Amount$ = Cstr(ParmDoc.Amount(0)) Comment$ = ParmDoc.Comment(0) " 'Specifiy name of the Queue to put the message in QueueName$ = "SG245682.NOTES.OUT.QUEUE" On Error Goto Err_Routine On Error 32000 Resume Next ' Creating New MQSession Set mqs = New MQSession If mqs.CompletionCode <> MQCC_OK Then Print "Error: MQSession cc: " & mqs.CompletionCode Print "Error: MQSession rc: " & mqs.ReasonCode End If ' Initiate MQQueueManager, MQPutMessageOptions, Message Set mqqm = New MQQueueManager Set mqpmo = New MQPutMessageOptions Set mqm = New MQMessage ' mqqm.Connect QmgrNames$ = "MQSX" mqqm.name = QmgrNames$ Call mqqm.Connect ' Access the queue QOpenOptions& = 0 Set mqq = mqqm.AccessQueue(QueueName$, QOpenOptions&, "","","") ' PUT Msg '--------------' Write string into Queue mqm.WriteString(Stat$ & CustNumber$ & CustName$ & Item$ & Phone$ & OrderDate$ & Amount$ & Comment$) If mqm.CompletionCode <> MQCC_OK Then Print "Error: MQSession cc: " & mqs.CompletionCode Print "Error: MQSession rc: " & mqs.ReasonCode Else Print "Your Order is shipped. You will receive the confirmation shortly." End If 'setting MessageType to MQMT_DATAGRAM mqm.Messagetype = MQMT_DATAGRAM mqm.Format = MQFMT_STRING ' Put the msg Call mqq.put(mqm,mqpmo) ' Commit the message Call mqqm.Commit ' Disconnect Call mqqm.Disconnect Appendix C. Sample LotusScript agent code 227 Goto End_Routine Err_Routine: ErrString = "Err_Routine: Error " & Err() & " on line " & Erl() & "(" & Error$(Err()) & ")" Print ErrString If Not ( mqp Is Nothing ) Then Call mqp.ClearErrorCodes End If If Not ( mqpmo Is Nothing ) Then Call mqpmo.ClearErrorCodes End If If Not ( mqgmo Is Nothing ) Then Call mqgmo.ClearErrorCodes End If If Not ( mqm Is Nothing ) Then Call mqm.ClearErrorCodes End If If Not ( mqq Is Nothing ) Then Call mqq.ClearErrorCodes End If If Not ( mqqm Is Nothing ) Then Call mqqm.ClearErrorCodes End If If Not ( mqs Is Nothing ) Then Call mqs.ClearErrorCodes End If Resume Next '----------------------------------------------------------------------End_Routine: If Not ( mqp Is Nothing ) Then Call mqp.ClearErrorCodes Delete mqp End If If Not ( mqpmo Is Nothing ) Then Call mqpmo.ClearErrorCodes Delete mqpmo End If If Not ( mqgmo Is Nothing ) Then Call mqgmo.ClearErrorCodes Delete mqgmo End If If Not ( mqm Is Nothing ) Then Call mqm.ClearErrorCodes Delete mqm End If If Not ( mqq Is Nothing ) Then Call mqq.ClearErrorCodes 228 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Delete mqq End If If Not ( mqqm Is Nothing ) Then Call mqqm.ClearErrorCodes Delete mqqm End If If Not ( mqs Is Nothing ) Then Call mqs.ClearErrorCodes Delete mqs End If End Sub C.3.2 The MQGetOrderStatus agent Sub Initialize 'Declare MQ Objects Dim mqs As MQSession Dim mqqm As MQQueueManager Dim mqq As MQQueue Dim mqm As MQMessage Dim mqpmo As MQPutMessageOptions Dim mqgmo As MQGetMessageOptions Dim mqp As MQProcess Dim QueueName Dim Dim Dim Dim Dim Dim Dim Dim Dim Dim T ErrString PutMsg GetMsg msgout msgin As String As As As As As As String String Integer Integer String String db As NotesDatabase session As NotesSession Agent As NotesAgent ParmDoc As NotesDocument Set session = New NotesSession Set db = session.CurrentDatabase Set Agent = session.currentagent Print "Agent QMGetOrderStatus started" 'Specify Name of Queue to poll QueueName$ = "SG245682.NOTES.IN.QUEUE" On Error Goto Err_Routine On Error 32000 Resume Next ' Creating New MQSession Set mqs = New MQSession If mqs.CompletionCode <> MQCC_OK Then Print "Error: MQSession cc: " & mqs.CompletionCode Print "Error: MQSession rc: " & mqs.ReasonCode End If Appendix C. Sample LotusScript agent code 229 ' Initiate MQQueueManager, MQPutMessageOptions, Message Set mqqm = New MQQueueManager Set mqgmo = New MQGetMessageOptions Set mqm = New MQMessage ' mqqm.Connect to Queue Manager MQSX QmgrNames$ = "MQSX" mqqm.name = QmgrNames$ Call mqqm.Connect ' Access the queue QOpenOptions& = 0 Set mqq = mqqm.AccessQueue(QueueName$, QOpenOptions&, "","","") ' GET MSG '--------------'Setting Message Options mqgmo.options = MQGMO_FAIL_IF_QUIESCING + _ MQGMO_SYNCPOINT T$ = "17.Queue depth before get: " & mqq.CurrentDepth Print T$ 'Check # Queue entries ' Get the message Call mqq.Get(mqm,mqgmo) If mqs.CompletionCode <> MQCC_OK Then Print "Error: " & T$ & " cc: " & mqs.CompletionCode Print "Error: " & T$ & " rc: " & mqs.ReasonCode End If Print "Got the Message" ' Read the message msgin$ = mqm.ReadString(mqm.MessageLength) Print "Read the Message" ' Commit the get Call mqqm.Commit T$ = "24.After Get and COMMIT queue depth is: " & mqq.CurrentDepth Print T$ 'Check # Queue entries ' Disconnect Print "1" Call mqqm.Disconnect Print "2" 'Read Data into form of Document searched with NoteID DocID$ = Trim$(Mid$(msgin$,48,8)) 'Get NoteID of corresponding Doc from Queue string Set ParmDoc = db.GetDocumentbyID(DocID$) Print "Document opened" ParmDoc.Status = Left$(msgin$,1) ParmDoc.CustomreNumber = Mid$(msgin$,2,6) ParmDoc.CustomerName = Mid$(msgin$,8,20) ParmDoc.Item = Mid$(msgin$,28,20) ParmDoc.Date = Mid$(msgin$,56,8) ParmDoc.Amount = Mid$(msgin$,64,8) ParmDoc.Comment = Mid$(msgin$,72,9) Call ParmDoc.Save(True, False) 230 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Goto End_Routine Err_Routine: ErrString = "Err_Routine: Error " & Err() & " on line " & Erl() & "(" & Error$(Err()) & ")" Print ErrString If Not ( mqp Is Nothing ) Then Call mqp.ClearErrorCodes End If If Not ( mqpmo Is Nothing ) Then Call mqpmo.ClearErrorCodes End If If Not ( mqgmo Is Nothing ) Then Call mqgmo.ClearErrorCodes End If If Not ( mqm Is Nothing ) Then Call mqm.ClearErrorCodes End If If Not ( mqq Is Nothing ) Then Call mqq.ClearErrorCodes End If If Not ( mqqm Is Nothing ) Then Call mqqm.ClearErrorCodes End If If Not ( mqs Is Nothing ) Then Call mqs.ClearErrorCodes End If Resume Next '----------------------------------------------------------------------End_Routine: If Not ( mqp Is Nothing ) Then Call mqp.ClearErrorCodes Delete mqp End If If Not ( mqpmo Is Nothing ) Then Call mqpmo.ClearErrorCodes Delete mqpmo End If If Not ( mqgmo Is Nothing ) Then Call mqgmo.ClearErrorCodes Delete mqgmo End If If Not ( mqm Is Nothing ) Then Call mqm.ClearErrorCodes Delete mqm End If If Not ( mqq Is Nothing ) Then Appendix C. Sample LotusScript agent code 231 Call mqq.ClearErrorCodes Delete mqq End If If Not ( mqqm Is Nothing ) Then Call mqqm.ClearErrorCodes Delete mqqm End If If Not ( mqs Is Nothing ) Then Call mqs.ClearErrorCodes Delete mqs End If End Sub 232 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Appendix D. Sample MQSeries-CICS source code This appendix contains the source code for our CICS transactions used with Domino for S/390 agents. We used standard IBM-supplied samples, so their modification should not be difficult. It also allows you to see what changes are needed in order to make your applications Domino-aware. We used C programming language, but you can use language of your preference, such as C++, COBOL, PL/1, or Assembler. CICS TS V1R3 contains sample transactions DMNU, DBRW, DADD, DINQ and DUPD. They call programs DFH$DALL, DFH$DMNU and DFH$DBRW. These programs use BMS map sets DFH$DMA, DFH$DMB, DFH$DMC and DFH$DMD to communicate with users using 3270 terminals. In the following section we show BMS map sets. They did not require any MQSeries-related changes, but we made some updates in order to help users to call the right transactions. Updates in C programs are of two kinds. The first is to update every line of code referring to the DFH$xxx sample map sets and programs to refer to our ITSOxxx files. The second is to add include files, variables, and functions needed for MQSeries. There are also a few changes in the program logic in order to send the correct data to the Domino for S/390 MQLSX agent. All changes are highlighted in boldface. D.1 BMS map sets This is the Assembler source code for map set ITSODMA. The code is based on CICS sample DFH$DMD. The name is changed to ISODM and we also changed MDF fields so that they tell users to use our sample transactions QMNU, QINQ, QBRW and QUPD. TITLE ‘FILEA - MAP FOR OPERATOR INSTRUCTIONS - C’ *********************************************************************** * * * MODULE NAME = ITSODMA * * * * DESCRIPTIVE NAME = Operator Instructions Map for Sample Application * * * * * *---------------------------------------------------------------------* * * * * *********************************************************************** MAPSETA DFHMSD TYPE=&SYSPARM,MODE=INOUT,CTRL=(FREEKB,FRSET),LANG=C, * STORAGE=AUTO,TIOAPFX=YES,COLOR=BLUE, * MAPATTS=(COLOR,HILIGHT,PS,VALIDN) DFHDGA DFHMDI SIZE=(12,40) DFHMDF POS=(1,10),LENGTH=21,INITIAL=’OPERATOR INSTRUCTIONS’, * © Copyright IBM Corp. 2001 233 MSG KEY HILIGHT=UNDERLINE DFHMDF POS=(1,32),LENGTH=1,ATTRB=PROT DFHMDF POS=(3,1),LENGTH=29,INITIAL=’OPERATOR INSTR - ENTER U’ DFHMDF POS=(4,1),LENGTH=38,INITIAL=’FILE INQUIRY - ENTER Q AND NUMBER’ DFHMDF POS=(5,1),LENGTH=38,INITIAL=’FILE BROWSE - ENTER W AND NUMBER’ DFHMDF POS=(6,1),LENGTH=38,INITIAL=’FILE ADD - ENTER D AND NUMBER’ DFHMDF POS=(7,1),LENGTH=38,INITIAL=’FILE UPDATE - ENTER D AND NUMBER’ DFHMDF POS=(11,1),LENGTH=39,INITIAL=’PRESS CLEAR TO EXIT’ DFHMDF POS=(12,1),LENGTH=18,INITIAL=’ENTER TRANSACTION:’ DFHMDF POS=(12,20),LENGTH=4,ATTRB=IC,COLOR=GREEN, HILIGHT=REVERSE DFHMDF POS=(12,25),LENGTH=6,INITIAL=’NUMBER’ DFHMDF POS=(12,32),LENGTH=6,ATTRB=NUM,COLOR=GREEN, HILIGHT=REVERSE DFHMDF POS=(12,39),LENGTH=1 DFHMSD TYPE=FINAL END QMN* QIN* QBR* QAD* QUP* * * This is the Assembler source code for map set ITSODMB. The code is the same as CICS sample DFH$DMB, except the name is changed to ISODMB. TITLE ‘FILEA - MAP FOR FILE INQUIRY/UPDATE - C’ *********************************************************************** * * * MODULE NAME = ITSODMB * * * * DESCRIPTIVE NAME = Inquire/Update Map for Sample Application * * * * * * * *---------------------------------------------------------------------* * * * * *********************************************************************** MAPSETB DFHMSD TYPE=&SYSPARM,MODE=INOUT,CTRL=(FREEKB,FRSET),LANG=C, * STORAGE=AUTO,TIOAPFX=YES, * MAPATTS=(COLOR,HILIGHT,PS,VALIDN) DFHDGB DFHMDI SIZE=(12,40) TITLE DFHMDF POS=(1,15),LENGTH=12 DFHMDF POS=(3,1),LENGTH=8,INITIAL=’NUMBER:’,COLOR=BLUE NUMB DFHMDF POS=(3,10),LENGTH=6 DFHMDF POS=(3,17),LENGTH=1 DFHMDF POS=(4,1),LENGTH=8,INITIAL=’NAME: ‘,COLOR=BLUE NAME DFHMDF POS=(4,10),LENGTH=20,ATTRB=(UNPROT,IC) DFHMDF POS=(4,31),LENGTH=1 DFHMDF POS=(5,1),LENGTH=8,INITIAL=’ADDRESS:’,COLOR=BLUE ADDR DFHMDF POS=(5,10),LENGTH=20,ATTRB=UNPROT DFHMDF POS=(5,31),LENGTH=1 DFHMDF POS=(6,1),LENGTH=8,INITIAL=’PHONE: ‘,COLOR=BLUE PHONE DFHMDF POS=(6,10),LENGTH=8,ATTRB=UNPROT DFHMDF POS=(6,19),LENGTH=1 DFHMDF POS=(7,1),LENGTH=8,INITIAL=’DATE: ‘,COLOR=BLUE DATE DFHMDF POS=(7,10),LENGTH=8,ATTRB=UNPROT DFHMDF POS=(7,19),LENGTH=1 DFHMDF POS=(8,1),LENGTH=8,INITIAL=’AMOUNT: ‘,COLOR=BLUE AMOUNT DFHMDF POS=(8,10),LENGTH=8,ATTRB=NUM DFHMDF POS=(8,19),LENGTH=1 DFHMDF POS=(9,1),LENGTH=8,INITIAL=’COMMENT:’,COLOR=BLUE 234 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products COMMENT MSG1 MSG3 DFHMDF DFHMDF DFHMDF DFHMDF DFHMSD END POS=(9,10),LENGTH=9,ATTRB=UNPROT POS=(9,20),LENGTH=1 POS=(11,1),LENGTH=39 POS=(12,1),LENGTH=39 TYPE=FINAL This is the source code for BMS map set ITSODMC. The code is the same as CICS sample DFH$DMC, except the name is changed to ISODMC. TITLE ‘FILEA - MAP FOR FILE BROWSE - C’ *********************************************************************** * * * MODULE NAME = ITSODMC * * * * DESCRIPTIVE NAME = Browse Map for Sample Application * * * * * *---------------------------------------------------------------------* * * * * *********************************************************************** MAPSETC DFHMSD TYPE=&SYSPARM,MODE=INOUT,CTRL=(FREEKB,FRSET),LANG=C, * STORAGE=AUTO,TIOAPFX=YES, * MAPATTS=(COLOR,HILIGHT,PS,VALIDN) DFHDGC DFHMDI SIZE=(12,40) DIR DFHMDF POS=(1,1),LENGTH=1,ATTRB=IC DFHMDF POS=(1,3),LENGTH=1 DFHMDF POS=(1,15),LENGTH=11,INITIAL=’FILE BROWSE’, * COLOR=BLUE,HILIGHT=UNDERLINE DFHMDF POS=(1,27),LENGTH=1,ATTRB=PROT DFHMDF POS=(3,1),LENGTH=6,INITIAL=’NUMBER’,COLOR=BLUE DFHMDF POS=(3,17),LENGTH=4,INITIAL=’NAME’,COLOR=BLUE DFHMDF POS=(3,32),LENGTH=6,INITIAL=’AMOUNT’,COLOR=BLUE NUMBER1 DFHMDF POS=(4,1),LENGTH=6 NAME1 DFHMDF POS=(4,9),LENGTH=20 AMOUNT1 DFHMDF POS=(4,30),LENGTH=8 NUMBER2 DFHMDF POS=(5,1),LENGTH=6 NAME2 DFHMDF POS=(5,9),LENGTH=20 AMOUNT2 DFHMDF POS=(5,30),LENGTH=8 NUMBER3 DFHMDF POS=(6,1),LENGTH=6 NAME3 DFHMDF POS=(6,9),LENGTH=20 AMOUNT3 DFHMDF POS=(6,30),LENGTH=8 NUMBER4 DFHMDF POS=(7,1),LENGTH=6 NAME4 DFHMDF POS=(7,9),LENGTH=20 AMOUNT4 DFHMDF POS=(7,30),LENGTH=8 MSG0 DFHMDF POS=(10,1),LENGTH=39,COLOR=BLUE, * INITIAL=’PRESS CLEAR TO END BROWSE OPERATION’ MSG1 DFHMDF POS=(11,1),LENGTH=39,COLOR=BLUE, * INITIAL=’PRESS PF1 OR TYPE F TO PAGE FORWARD’ MSG2 DFHMDF POS=(12,1),LENGTH=39,COLOR=BLUE, * INITIAL=’PRESS PF2 OR TYPE B TO PAGE BACKWARD’ DFHMSD TYPE=FINAL END This is the Assembler source code for map set ITSODMD. The code is the same as CICS sample DFH$DMD, except the name is changed to ISODMD. *********************************************************************** * * * MODULE NAME = ITSODMD * * * Appendix D. Sample MQSeries-CICS source code 235 * * *---------------------------------------------------------------------* * * * CHANGE ACTIVITY : * * * * * *********************************************************************** MAPSETD DFHMSD TYPE=&SYSPARM,MODE=OUT,CTRL=(FREEKB,FRSET),LANG=C, * STORAGE=AUTO,TIOAPFX=YES,COLOR=BLUE, * MAPATTS=(COLOR,HILIGHT,PS,VALIDN) DFHDGD DFHMDI SIZE=(1,40),COLOR=GREEN NUMBER DFHMDF POS=(1,1),LENGTH=6 NAME DFHMDF POS=(1,9),LENGTH=20 AMOUNT DFHMDF POS=(1,30),LENGTH=8 HEADING DFHMDI SIZE=(3,40),HEADER=YES DFHMDF POS=(1,5),LENGTH=18,INITIAL=’LOW BALANCE REPORT’, * HILIGHT=UNDERLINE DFHMDF POS=(1,24),LENGTH=1,ATTRB=PROT DFHMDF POS=(1,30),LENGTH=4,INITIAL=’PAGE’ PAGEN DFHMDF POS=(1,35),LENGTH=3 DFHMDF POS=(3,1),LENGTH=6,INITIAL=’NUMBER’ DFHMDF POS=(3,17),LENGTH=4,INITIAL=’NAME’ DFHMDF POS=(3,32),LENGTH=6,INITIAL=’AMOUNT’ FOOTING DFHMDI SIZE=(2,40),TRAILER=YES,JUSTIFY=LAST DFHMDF POS=(2,1),LENGTH=38, * INITIAL=’PRESS CLEAR AND TYPE P/N TO SEE PAGE N’ FINAL DFHMDI SIZE=(2,40),TRAILER=YES,JUSTIFY=LAST DFHMDF POS=(2,10),LENGTH=14,INITIAL=’END OF REPORT.’ DFHMSD TYPE=FINAL END D.2 C source code for CICS/MQSeries programs This is the C source code for program ITSODMNU. The code is based on CICS sample DFH$DMNU. We changed all references in the include file and map set to refer to our sample files. /********************************************************************/ /* */ /* Module Name = ITSODMNU */ /* */ /* Descriptive Name = Operator Instructions Menu sAmple Application */ /* */ /* */ /*------------------------------------------------------------------*/ /* */ /* */ /********************************************************************/ #include “itsdga.h” main() { EXEC CICS SEND MAP(“dfhdga “) MAPSET(“ITSDGA”) MAPONLY ERASE; EXEC CICS RETURN; } This is the C source code for program ITSODALL. The code is based on CICS sample DFH$DALL. We changed all references in the include files and map sets to refer to our sample files. We have added a C include file for the 236 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products MQSeries API. We also added function WriteMQ() . We changed the program flow so that every time record is added or updated in VSAM file FILEA, the same record is written to the message queue. Our queue is named SG245682.NOTES.IN.QUEUE. /********************************************************************/ /* */ /* Module Name = ITSODALL */ /* */ /* Descriptive Name = File Inquiry/Update for Sample Application */ /* */ /* */ /*------------------------------------------------------------------*/ /* */ /* */ /********************************************************************/ #include “dfhbmsca.h” /* BMS definitions */ #include “itsdga.h” /* Logical maps for ITSDGA */ #include “itsdgb.h” /* Logical maps for ITSDGB */ #include “dfh$dfil.h” /* FILEA definition */ #include #include #include /* MQSeries include /* @D1A */ MILAN */ int rcode; #define #define #define #define QADD QINQ QUPD QMNU (1) (2) (3) (4) /* RESP value /* /* /* /* Code Code Code Code for for for for QADD QINQ QUPD QMNU TRANID TRANID TRANID TRANID */ */ */ */ */ */ static int trnid; static char messages[50]; static char keynum[6]; struct loga_struct { struct loghdr_struct { unsigned char lday[4]; unsigned char ltime[4]; unsigned char lterml[4]; } loghdr; struct filea_struct logrec; }; static struct loga_struct loga; static struct filea_struct *commarea; static short int comlen; /* MQSeries API variables MQHCONN HConn = MQHC_DEF_HCONN; MQHOBJ HObj; MQLONG OpenOptions = MQOO_OUTPUT; MQMD MsgDesc = { MQMD_DEFAULT }; MQOD ObjDesc = { MQOD_DEFAULT }; MQPMO PutMsgOpts = { MQPMO_DEFAULT }; MQLONG CompCode; MQLONG Reason; static void dmnu() /* Coded TRANID /* Messages area */ /* Key area */ /* Definition of loga_struct*/ /* loga definition /* COMMAREA definition /* Length of COMMAREA --MILAN-- */ */ */ */ Appendix D. Sample MQSeries-CICS source code 237 { int i; dfhdga.dfhdgao.msga = DFHBMASB; for (i=strlen(messages);i<40;i++) messages[i] = ‘ ‘; memcpy(dfhdga.dfhdgao.msgo,messages,39); EXEC CICS SEND MAP(“dfhdga “) MAPSET(“ITSDGA”) ERASE; EXEC CICS RETURN; } /* MQSeries Write to a queue --MILAN-static void WriteMQ() { memset( ObjDesc.ObjectName, ‘ ‘, MQ_Q_NAME_LENGTH ); strncpy( ObjDesc.ObjectName, “SG245682.NOTES.IN.QUEUE”, 23); MsgDesc.Persistence = MQPER_PERSISTENT; OpenOptions = MQOO_OUTPUT; MQOPEN(HConn, &ObjDesc, OpenOptions, &HObj, &CompCode, &Reason); if (CompCode != MQCC_OK) { strcpy(messages,”MQ OPEN FAILED”); dmnu(); } MQPUT(HConn, HObj, &MsgDesc, &PutMsgOpts, filea_size, &filea, \ &CompCode, &Reason); if (CompCode != MQCC_OK) { strcpy(messages,”MQ PUT FAILED”); dmnu(); } else { printf(“Message put to queue %s:\n”, ObjDesc.ObjectName); } MQCLOSE(HConn, &HObj, MQCO_NONE, &CompCode, &Reason); if (CompCode != MQCC_OK) { strcpy(messages,”MQ CLOSE FAILED”); dmnu(); } return; } */ static int Verify_Name(char *string,short int length) /* @D1C */ { for(;length>0;length--,string++) if(strchr(“ABCDEFGHIJKLMNOPQRSTUVWXYZ .-’”,*string)==0) return(0); return(1); } static int Verify_Amount(char *string,short int length) { for(;length>0;length--,string++) if(strchr(“0123456789.$”,*string)==0) return(0); return(1); } static int IsNumeric(char *string,int length) { for(;length>0;length--,string++) if (!isdigit((int)(*string))) return(0); return(1); } /* @D1C */ /* @D1C */ 238 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products static void Notmodf() { strcpy(messages,”RECORD NOT MODIFIED”); dmnu(); } static void Duprec() { strcpy(messages,”DUPLICATE RECORD”); dmnu(); } static void Badleng() { strcpy(messages,”PLEASE ENTER AN ACCOUNT NUMBER”); dmnu(); } static void Badchars() { strcpy(messages,”ACCOUNT NUMBER MUST BE NUMERIC”); dmnu(); } static void Notfound() { strcpy(messages,”INVALID NUMBER - PLEASE REENTER”); dmnu(); } static void Map_Fail() { strcpy(messages,”PRESS CLEAR TO EXIT”); dmnu(); } static void Errors() { EXEC CICS DUMP DUMPCODE(“ERRS”); dmnu(); } static void Cics_Control() { EXEC CICS RETURN TRANSID(dfheiptr->eibtrnid) COMMAREA(commarea) LENGTH(comlen); } static void Map_Build() { memcpy(dfhdgb.dfhdgbo.numbo,filea.numb,6); memcpy(dfhdgb.dfhdgbo.nameo,filea.name,20); memcpy(dfhdgb.dfhdgbo.addro,filea.addrx,20); memcpy(dfhdgb.dfhdgbo.phoneo,filea.phone,8); memcpy(dfhdgb.dfhdgbo.dateo,filea.datex,8); memcpy(dfhdgb.dfhdgbo.amounto,filea.amount,8); memcpy(dfhdgb.dfhdgbo.commento,filea.comment,9); return; } static void Map_Send() Appendix D. Sample MQSeries-CICS source code 239 { EXEC CICS SEND MAP(“dfhdgb “) MAPSET(“ITSDGB”) ERASE; return; } static void Data_Error() { dfhdgb.dfhdgbo.msg3a = DFHBMASB; memcpy(dfhdgb.dfhdgbo.msg3o, \ “DATA ERROR - CORRECT AND PRESS ENTER “,36); dfhdgb.dfhdgbo.amounta = DFHUNNUM; dfhdgb.dfhdgbo.namea = DFHBMFSE; dfhdgb.dfhdgbo.phonea = DFHBMFSE; dfhdgb.dfhdgbo.datea = DFHBMFSE; dfhdgb.dfhdgbo.commenta = DFHBMFSE; EXEC CICS SEND MAP(“dfhdgb “) MAPSET(“ITSDGB”) DATAONLY; comlen = sizeof(struct filea_struct); Cics_Control(); /* No return from ‘Cics_Control’ */ } static void Read_Input() { EXEC CICS RECEIVE MAP(“dfhdgb “) MAPSET(“ITSDGB”) RESP(rcode); switch (rcode) { case DFHRESP(NORMAL) : break; case DFHRESP(MAPFAIL): Notmodf(); default: Errors(); } switch (trnid) { case QUPD : { EXEC CICS READ UPDATE FILE(“FILEA “) INTO(&filea) LENGTH(filea_size) RIDFLD(commarea->numb) RESP(rcode); switch (rcode) { case DFHRESP(NORMAL) : break; case DFHRESP(NOTFND) : Notfound(); /* No return from */ default: Errors(); } if (memcmp(&filea,commarea, \ sizeof(struct filea_struct))!=0) { memcpy(dfhdgb.dfhdgbo.msg1o, \ “RECORD UPDATED BY OTHER USER, TRY AGAIN”,39); dfhdgb.dfhdgbo.msg1a = DFHBMASB; dfhdgb.dfhdgbo.msg3a = DFHPROTN; Map_Build(); EXEC CICS SEND MAP(“dfhdgb “) MAPSET(“ITSDGB”) DATAONLY; *commarea = filea; comlen = sizeof(struct filea_struct); Cics_Control(); /* ‘Cics_Control’ does not return */ } else { filea.stat = ‘1’; /* --MILAN-- Change because of MQLSX Agent*/ strcpy(messages,”RECORD UPDATED”); } break; } case QADD : { filea.stat = ‘1’; /* --MILAN-- Change because of MQLSX Agent*/ strcpy(messages,”RECORD ADDED”); break; } 240 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products default : Errors(); } if && && && && && (dfhdgb.dfhdgbi.namel == 0 \ dfhdgb.dfhdgbi.addrl == 0 \ dfhdgb.dfhdgbi.phonel == 0 \ dfhdgb.dfhdgbi.datel == 0 \ dfhdgb.dfhdgbi.amountl == 0 \ dfhdgb.dfhdgbi.commentl == 0) Notmodf(); /* No return from ‘Notmodf’ */ switch (trnid) { case QADD : { if (!Verify_Name(dfhdgb.dfhdgbi.namei, \ dfhdgb.dfhdgbi.namel)) Data_Error(); /* No return from ‘Data_Error’ */ } case QUPD : { if (dfhdgb.dfhdgbi.namel !=0 ) if (!Verify_Name(dfhdgb.dfhdgbi.namei, \ dfhdgb.dfhdgbi.namel)) Data_Error(); /* No return from ‘Data_Error’ */ if (dfhdgb.dfhdgbi.amountl != 0) if (!Verify_Amount(dfhdgb.dfhdgbi.amounti, \ dfhdgb.dfhdgbi.amountl)) Data_Error(); /* No return from ‘Data_Error’ */ } } if (trnid == QADD) memcpy(filea.numb,commarea->numb,6); if (dfhdgb.dfhdgbi.namel != 0) memcpy(filea.name,dfhdgb.dfhdgbi.namei,20); if (dfhdgb.dfhdgbi.addrl != 0) memcpy(filea.addrx,dfhdgb.dfhdgbi.addri,20); if (dfhdgb.dfhdgbi.phonel != 0) memcpy(filea.phone,dfhdgb.dfhdgbi.phonei,8); if (dfhdgb.dfhdgbi.datel != 0) memcpy(filea.datex,dfhdgb.dfhdgbi.datei,20); if (dfhdgb.dfhdgbi.amountl != 0) memcpy(filea.amount,dfhdgb.dfhdgbi.amounti,8); else if (trnid == QADD) memcpy(filea.amount,”$0000.00”,8); if (dfhdgb.dfhdgbi.commentl != 0) memcpy(filea.comment,dfhdgb.dfhdgbi.commenti,9); loga.logrec = filea; memcpy(loga.loghdr.lday,dfheiptr->eibdate,4); memcpy(loga.loghdr.ltime,dfheiptr->eibtime,4); memcpy(loga.loghdr.lterml,dfheiptr->eibtrmid,4); EXEC CICS WRITEQ TD QUEUE(“LOGA”) FROM(&loga) LENGTH(sizeof(struct loga_struct)) RESP(rcode); switch(rcode) { case DFHRESP(NORMAL) : break; default : strcpy(messages,”TRANSACTION TERMINATED”); Errors(); } if (trnid == QUPD) { EXEC CICS REWRITE FILE(“FILEA “) FROM(&filea) LENGTH(filea_size) RESP(rcode); switch(rcode) { case DFHRESP(NORMAL) : { WriteMQ(); break; } case DFHRESP(DUPREC) : Duprec(); /* No return from here */ Appendix D. Sample MQSeries-CICS source code 241 default: Errors(); } } else { EXEC CICS WRITE FILE(“FILEA “) FROM(&filea) LENGTH(filea_size) RIDFLD(commarea->numb) RESP(rcode); switch(rcode) { case DFHRESP(NORMAL) : { WriteMQ(); break; } case DFHRESP(DUPREC) : Duprec(); /* No return from here */ case DFHRESP(NOTFND) : Notfound(); /* No return from here */ default: Errors(); } } dmnu(); /* No return from ‘dmnu’ */ } /********************************************************************/ /* Entry point of the program. */ /********************************************************************/ main() { struct filea_struct com_spc; /* Get Addressability of the EIB EXEC CICS ADDRESS COMMAREA(commarea); /* Get addressability of the COMMAREA /* Code the trnid to one of QADD, QINQ, QUPD or QMNU if (memcmp(dfheiptr->eibtrnid,”QADD”,4)==0) { trnid = QADD; } else if (memcmp(dfheiptr->eibtrnid,”QINQ”,4)==0) { trnid = QINQ; } else if (memcmp(dfheiptr->eibtrnid,”QUPD”,4)==0) { trnid = QUPD; } else if (memcmp(dfheiptr->eibtrnid,”QMNU”,4)==0){ trnid = QMNU; } else trnid = 0; if (dfheiptr->eibcalen != 0) Read_Input(); EXEC CICS ADDRESS EIB(dfheiptr); */ */ */ /* No return from Read_Input */ commarea = &com_spc; EXEC CICS RECEIVE MAP(“dfhdga “) MAPSET(“ITSDGA”) RESP(rcode); switch (rcode) { case DFHRESP(NORMAL) : break; case DFHRESP(MAPFAIL): Map_Fail(); default: Errors(); } if (dfhdga.dfhdgai.keyl == 0) Badleng(); /* No return from ‘Bad_Leng’ */ if (!IsNumeric(dfhdga.dfhdgai.keyi,6)) Badchars(); /* No return from ‘Bad_Chars’ */ memcpy(keynum,dfhdga.dfhdgai.keyi,6); switch (trnid) { case QADD : { 242 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products memcpy(dfhdgb.dfhdgbo.titleo,”FILE ADD “,12); memcpy(dfhdgb.dfhdgbo.msg3o, \ “ENTER DATA AND PRESS ENTER KEY “,39); memcpy(dfhdgb.dfhdgbo.numbo,dfhdga.dfhdgai.keyi,6); memcpy(commarea->numb,dfhdga.dfhdgai.keyi,6); dfhdgb.dfhdgbo.namea = DFHBMUNP; dfhdgb.dfhdgbo.addra = DFHBMUNP; dfhdgb.dfhdgbo.phonea = DFHBMUNP; dfhdgb.dfhdgbo.datea = DFHBMUNP; dfhdgb.dfhdgbo.amounta = DFHBMUNN; dfhdgb.dfhdgbo.commenta = DFHBMUNP; memcpy(dfhdgb.dfhdgbo.amounto,”$0000.00”,8); comlen = 7; Map_Send(); Cics_Control(); /* Cics_Control does not return */ } case QINQ : case QUPD : { /* Remember to handle conditions. */ EXEC CICS READ FILE(“FILEA “) INTO(&filea) LENGTH(filea_size) RIDFLD(keynum) RESP(rcode); switch(rcode) { case DFHRESP(NORMAL) : break; case DFHRESP(NOTFND) : Notfound(); default : Errors(); } if (trnid == QINQ) { memcpy(dfhdgb.dfhdgbo.titleo,”FILE INQUIRY”,12); memcpy(dfhdgb.dfhdgbo.msg3o, \ “PRESS ENTER TO CONTINUE “,39); Map_Build(); /* Protect all fields on the map */ dfhdgb.dfhdgbo.namea = DFHBMPRO; dfhdgb.dfhdgbo.addra = DFHBMPRO; dfhdgb.dfhdgbo.phonea = DFHBMPRO; dfhdgb.dfhdgbo.datea = DFHBMPRO; dfhdgb.dfhdgbo.amounta = DFHBMPRO; dfhdgb.dfhdgbo.commenta = DFHBMPRO; Map_Send(); EXEC CICS RETURN TRANSID(“QMNU”); } else { memcpy(dfhdgb.dfhdgbo.titleo,”FILE UPDATE “,12); memcpy(dfhdgb.dfhdgbo.msg3o, \ “CHANGE FIELDS AND PRESS ENTER “,39); *commarea = filea; dfhdgb.dfhdgbo.namea = DFHBMUNP; dfhdgb.dfhdgbo.addra = DFHBMUNP; dfhdgb.dfhdgbo.phonea = DFHBMUNP; dfhdgb.dfhdgbo.datea = DFHBMUNP; dfhdgb.dfhdgbo.amounta = DFHBMUNN; dfhdgb.dfhdgbo.commenta = DFHBMUNP; Map_Build(); Map_Send(); comlen = sizeof(struct filea_struct); Cics_Control(); /* ‘Cics_Control’ does not reurn */ } } default : Errors(); /* End switch } */ Appendix D. Sample MQSeries-CICS source code 243 } /* End main */ This is the C source code for program ITSODBRW. The code is based on CICS sample DFH$DBRW. We changed all references in include files and map sets to refer to our sample files. /********************************************************************/ /* */ /* Module Name = DFH$DBRW */ /* */ /*------------------------------------------------------------------*/ /* */ /* */ /********************************************************************/ #include “dfhbmsca.h” /* BMS definitions */ #include “dfhaid.h” /* Attention identifiers */ #include “itsdga.h” /* Logical maps for DFH$DMA */ #include “itsdgc.h” /* Logical maps for DFH$DGC */ #include “dfh$dfil.h” /* Definition of FILEA */ #include /* @D1A */ #include /* @D1A */ int rcode; unsigned char rid[6]; unsigned char ridf[6]; unsigned char ridb[6]; unsigned char status = ‘ ‘; unsigned char currop; unsigned char lastop; char messages[40]; static void Dmnu() { int i; memset(&dfhdga.dfhdgao,’\0’,sizeof(dfhdga.dfhdgao)); dfhdga.dfhdgao.msga = DFHBMASB; for (i=strlen(messages);i<40;i++) messages[i]=’ ‘; memcpy(dfhdga.dfhdgao.msgo,messages,39); EXEC CICS SEND MAP(“dfhdga “) MAPSET(“ITSDGA”) ERASE; EXEC CICS RETURN; } static void TooHigh() { status = ‘H’; memcpy(ridf,rid,6); memcpy(ridb,rid,6); dfhdgc.dfhdgco.diro = ‘ ‘; memcpy(dfhdgc.dfhdgco.msg1o, \ “HI-END OF FILE “,39); dfhdgc.dfhdgco.msg1a = DFHBMASB; EXEC CICS SEND MAP(“dfhdgc “) MAPSET(“ITSDGC”) ERASE; return; } static void TooLow() { status = ‘L’; memcpy(ridf,”000000”,6); /* @D1C */ 244 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products memcpy(ridb,”000000”,6); dfhdgc.dfhdgco.diro = ‘ ‘; memcpy(dfhdgc.dfhdgco.msg2o, \ “LO-END OF FILE “,39); dfhdgc.dfhdgco.msg2a = DFHBMASB; EXEC CICS SEND MAP(“dfhdgc “) MAPSET(“ITSDGC”) ERASE; return; } static void Notfound() { strcpy(messages,”END OF FILE - PLEASE RESTART”); EXEC CICS ENDBR FILE(“FILEA “); Dmnu(); /* No return from Dmnu */ } static void Smsg() { strcpy(messages,”PRESS CLEAR TO EXIT”); Dmnu(); /* No return from ‘Dmnu’ */ } static void Errors() { EXEC CICS DUMP DUMPCODE(“ERRS”); Dmnu(); /* No return from ‘Dmnu’ */ } static int Verify_Name(char *string,int length) { for(;length>0;length--,string++) if(strchr(“ABCDEFGHIJKLMNOPQRSTUVWXYZ .-’”,*string)==0) return(0); return(1); } static int Verify_Amount(char *string,int length) { for(;length>0;length--,string++) if(strchr(“0123456789.›$”,*string)==0) return(0); return(1); } static int IsNumeric(char *string,int length) { for(;length>0;length--,string++) if (!isdigit((int)(*string))) return(0); return(1); } /* D1C */ /* D1C */ static int Build_Next() { int i; for (i=1;i<=4;i++) { EXEC CICS READNEXT INTO(&filea) LENGTH(filea_size) Appendix D. Sample MQSeries-CICS source code 245 } FILE(“FILEA “) RIDFLD(rid) RESP(rcode); switch(rcode) { case DFHRESP(NORMAL): break; case DFHRESP(NOTFND): Notfound(); case DFHRESP(ENDFILE) : TooHigh(); return(1); default: Errors(); } /* End Switch */ switch (i) { case (1): { memcpy(dfhdgc.dfhdgco.number1o,filea.numb,6); memcpy(dfhdgc.dfhdgco.name1o,filea.name,20); memcpy(dfhdgc.dfhdgco.amount1o,filea.amount,8); memcpy(ridb,rid,6); break; } case (2): { memcpy(dfhdgc.dfhdgco.number2o,filea.numb,6); memcpy(dfhdgc.dfhdgco.name2o,filea.name,20); memcpy(dfhdgc.dfhdgco.amount2o,filea.amount,8); break; } case (3): { memcpy(dfhdgc.dfhdgco.number3o,filea.numb,6); memcpy(dfhdgc.dfhdgco.name3o,filea.name,20); memcpy(dfhdgc.dfhdgco.amount3o,filea.amount,8); break; } case (4): { memcpy(dfhdgc.dfhdgco.number4o,filea.numb,6); memcpy(dfhdgc.dfhdgco.name4o,filea.name,20); memcpy(dfhdgc.dfhdgco.amount4o,filea.amount,8); break; } } /* End Switch } /* End For return(0); /* End Build_Next() */ */ */ static int Build_Prev() { int i; for (i=1;i<=4;i++) { EXEC CICS READPREV INTO(&filea) LENGTH(filea_size) FILE(“FILEA “) RIDFLD(rid) RESP(rcode); switch(rcode) { case DFHRESP(NORMAL): break; case DFHRESP(NOTFND): Notfound(); case DFHRESP(ENDFILE) : TooLow(); return(1); default: Errors(); } /* End Switch */ switch (i) { case (4): { memcpy(dfhdgc.dfhdgco.number1o,filea.numb,6); 246 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products memcpy(dfhdgc.dfhdgco.name1o,filea.name,20); memcpy(dfhdgc.dfhdgco.amount1o,filea.amount,8); memcpy(ridb,rid,6); break; } case (3): { memcpy(dfhdgc.dfhdgco.number2o,filea.numb,6); memcpy(dfhdgc.dfhdgco.name2o,filea.name,20); memcpy(dfhdgc.dfhdgco.amount2o,filea.amount,8); memcpy(ridb,rid,6); break; } case (2): { memcpy(dfhdgc.dfhdgco.number3o,filea.numb,6); memcpy(dfhdgc.dfhdgco.name3o,filea.name,20); memcpy(dfhdgc.dfhdgco.amount3o,filea.amount,8); memcpy(ridb,rid,6); break; } case (1): { memcpy(dfhdgc.dfhdgco.number4o,filea.numb,6); memcpy(dfhdgc.dfhdgco.name4o,filea.name,20); memcpy(dfhdgc.dfhdgco.amount4o,filea.amount,8); memcpy(ridb,rid,6); break; } } /* End Switch } /* End For return(0); /* End Build_Prev() */ */ */ } static void Page_Forward() { currop = ‘F’; /* Code to reset fields + attrb in MAP C;*/ memcpy(rid,ridf,6); if (Build_Next()!=0) return; memcpy(ridf,rid,6); EXEC CICS SEND MAP(“dfhdgc “) MAPSET(“ITSDGC”) ERASE; return; } static void Page_Backward() { currop = ‘B’; memcpy(rid,ridb,6); memcpy(ridf,ridb,6); if (lastop != ‘B’ && status !=’H’) { EXEC CICS READPREV INTO(&filea) LENGTH(filea_size) FILE(“FILEA “) RIDFLD(rid) RESP(rcode); switch(rcode) { case DFHRESP(NORMAL): break; case DFHRESP(ENDFILE) : TooLow(); return; default: Errors(); } /* End Switch */ } if (Build_Prev()!=0) Appendix D. Sample MQSeries-CICS source code 247 return; memcpy(ridb,rid,6); EXEC CICS SEND MAP(“dfhdgc “) MAPSET(“ITSDGC”) ERASE; return; } static void Receive() { while (1) { lastop = currop; EXEC CICS RECEIVE MAP(“dfhdgc “) MAPSET(“ITSDGC”) RESP(rcode); switch (rcode) { case DFHRESP(NORMAL): break; case DFHRESP(MAPFAIL): break; default: Errors(); } /* End Switch */ switch (dfheiptr->eibaid) { case DFHCLEAR : Smsg(); case DFHPF1 : Page_Forward(); continue; case DFHPF2 : Page_Backward(); continue; default: if (rcode==DFHRESP(MAPFAIL)) Smsg(); } /* End Switch switch(dfhdgc.dfhdgci.diri) { case ‘F’: { Page_Forward(); break; } case ‘B’: { Page_Backward(); break; } case ‘Q’: { Errors(); } default: { EXEC CICS SEND MAP(“dfhdgc “) MAPSET(“ITSDGC”); } } /* End switch /* End While(1) /* End Receive() */ } } */ */ */ main() { EXEC CICS ADDRESS EIB(dfheiptr); EXEC CICS RECEIVE MAP(“dfhdga “) MAPSET(“ITSDGA”) RESP(rcode); switch(rcode) { case DFHRESP(NORMAL) : break; case DFHRESP(MAPFAIL) : Smsg(); default: Errors(); } /* End Switch */ if (dfhdga.dfhdgai.keyl == 0) { memcpy(rid,”000000”,6); memcpy(ridf,”000000”,6); } 248 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products else { if (IsNumeric(dfhdga.dfhdgai.keyi,6)) { memcpy(rid,dfhdga.dfhdgai.keyi,6); memcpy(ridf,dfhdga.dfhdgai.keyi,6); memcpy(ridb,dfhdga.dfhdgai.keyi,6); } else { strcpy(messages, \ “ACCOUNT NUMBER MUST BE NUMERIC”); Dmnu(); /* No return from ‘Dmnu’ */ } } EXEC CICS STARTBR FILE(“FILEA “) RIDFLD(rid) RESP(rcode); switch (rcode) { case DFHRESP(NORMAL) : break; case DFHRESP(NOTFND) : Notfound(); default : Errors(); } /* End Switch */ /* ESTABLISH ‘START’ */ if (memcmp(rid,”999999”,6)!=0) { Page_Forward(); } else { status = ‘H’; Page_Backward(); } Receive(); /* No return from Receive */ } This is the C source code for program ITSOGALL. This piece of code was written from scratch specifically for our sample application. /********************************************************************/ /* */ /* Module Name = DFH$DALL */ /* */ /* Descriptive Name = File Inquiry/Update for Sample Application */ /* */ /* @BANNER_START@ */ /* 5655-147 */ /* CICS 5.3.0 */ /* (Element of CICS Transaction Server */ /* Version 1 Release 3) */ /* @BANNER_END@ */ /* */ /* STATUS = 4.1.0 */ /* */ /*------------------------------------------------------------------*/ /* */ /* Change Activity: */ /* */ /* PN= REASON REL YYMMDD HDXIII : REMARKS */ /* $P0= 210 890825 : Created. */ /* $P1= M90474 330 910807 HDBWSH : Prologue fixed. */ /* $D1= I06048 410 930913 HD7OPJW: C++ support */ /* */ Appendix D. Sample MQSeries-CICS source code 249 /********************************************************************/ #include “dfhbmsca.h” /* BMS definitions */ #include “itsdga.h” /* Logical maps for DFH$DGA */ #include “itsdgb.h” /* Logical maps for DFH$DGB */ #include “dfh$dfil.h” /* FILEA definition */ #include #include /* @D1A */ #include /* MQSeries include MILAN */ #define messageSize 80 #define maxMessageLength ((24576 - 49 )) /* MQSeries Read from a queue int main() { /* MQSeries API variables MQHCONN HConn = MQHC_DEF_HCONN; MQHOBJ HObj = 0; MQLONG OpenOptions; MQMD MsgDesc = { MQMD_DEFAULT }; MQOD ObjDesc = { MQOD_DEFAULT }; MQGMO GetMsgOpts = { MQGMO_DEFAULT }; MQLONG CompCode; MQLONG Reason; int rcode = 0; long dataLength = 0; char msgBuffer??( maxMessageLength ??); char aKey??( 6 ??); --MILAN-- */ --MILAN-- */ memset( ObjDesc.ObjectName, ‘ ‘, MQ_Q_NAME_LENGTH ); strncpy( ObjDesc.ObjectName, “SG245682.NOTES.OUT.QUEUE”, 24); OpenOptions = MQOO_INPUT_SHARED + MQOO_BROWSE; GetMsgOpts.Options = MQGMO_NO_WAIT + MQOO_BROWSE; MQOPEN(HConn, &ObjDesc, OpenOptions, &HObj, &CompCode, &Reason); if (CompCode != MQCC_OK) { printf(“MQ OPEN FAILED”); EXEC CICS RETURN; } GetMsgOpts.Options = MQGMO_NO_WAIT + MQGMO_ACCEPT_TRUNCATED_MSG; GetMsgOpts.Options += MQGMO_SYNCPOINT; MQGET(HConn, HObj, &MsgDesc, &GetMsgOpts, filea_size, &msgBuffer, \ &dataLength, &CompCode, &Reason); if (CompCode != MQCC_OK) { printf(“MQ GOT FAILED. No more messages?”); EXEC CICS RETURN; } else { msgBuffer??( 0 ??) = ‘1’; strncpy(aKey, msgBuffer+1, 6); printf(“Msg with key >%s< got from queue: %s\n”, aKey, msgBuffer); EXEC CICS WRITE FILE(“FILEA “) FROM(msgBuffer) LENGTH(dataLength) RIDFLD(aKey) RESP(rcode); /* switch(rcode) { case DFHRESP(NORMAL) : printf(“Write to FILEA successful\n”); case DFHRESP(DUPREC) : printf(“Duplicate record in FILEA\n”); case DFHRESP(NOTFND) : printf(“Record not found in FILEA\n”); default: printf(“Other CICS error occured, code=%d\n”, rcode); } */ EXEC CICS SYNCPOINT } 250 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products MQCLOSE(HConn, &HObj, MQCO_NONE, &CompCode, &Reason); if (CompCode != MQCC_OK) { printf(“MQ CLOSE FAILED”); } EXEC CICS RETURN; return; } Appendix D. Sample MQSeries-CICS source code 251 252 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Appendix E. Workaround for manual field mapping in DECS As explained in 6.2.2.1, “Problems we experienced” on page 102, we experienced an error in the DECS activity documents as we pressed the Map Fields button. We had an overflow error message. In our case the cause was the heavy use of field level help. We created a workaround using manual field mapping, which is not available through DECS. The automatically-filled fields in the DECS activity document are computed fields, which cannot be edited. These computed fields are populated by hidden fields. These hidden fields have to be populated manually, because DECS takes the field mapping information from of these hidden fields. Follow these steps to manually insert field mappings. 1. Open the DECS administrator in Domino Designer 2. Open the RealTime Notes form. 3. Open the hidden fields section in the top of the form. 4. Open the src/dest related fields, as shown in Figure 107. 5. Change the following fields from computed to editable, and deactivate the hide function in the field properties. a. b. c. d. SrcKeyList SrcFieldList DestKeyList SrcKeyList Figure 107. Changing the mapping fields in the Notes Realtime form 6. Now open the desired DECS Activity document and populate the fields in the top of the document as shown in Figure 108 on page 254. Always enter only the field or column name. 7. Save the activity document and activate it. © Copyright IBM Corp. 2001 253 Figure 108. Editable field mapping Notes form field in DECS activity 254 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Appendix F. Special notices This redbook is intended to help system architects, database administrators, and Notes developers integrate subsystem data and applications with Domino applications in a S/390 environment. The information in this publication is not intended as the specification of any programming interfaces that are provided by Lotus Enterprise Integration connector products. See the PUBLICATIONS section of the Programming Announcements for Domino Enterprise Connection Services (DECS), Lotus Enterprise Integrator (LEI), LotusScript Extension for Lotus Connector (LCLSX), and MQSeries LotusScript Extensions (MQLSX) 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, North Castle Drive, Armonk, NY 10504-1785. 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 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 © Copyright IBM Corp. 2001 255 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. The following terms are trademarks of the International Business Machines Corporation in the United States and/or other countries: AS/400 AT CICS CICS/ESA CT Current DB2 DB2 Connect DB2 Universal Database Domino DRDA DXT IBM Lotus Lotus Notes Lotus SmartSuite MQSeries Net.Data Netfinity Notes OS/390 RACF Redbooks Redbooks Logo RS/6000 S/390 SmartSuite SP SupportPac System/390 VTAM WebSphere Wizard XT 400 The following terms are trademarks of other companies: Tivoli, Manage. Anything. Anywhere.,The Power To Manage., Anything. Anywhere.,TME, NetView, Cross-Site, Tivoli Ready, Tivoli Certified, Planet Tivoli, and Tivoli Enterprise are trademarks or registered trademarks of Tivoli Systems Inc., an IBM company, in the United States, other countries, or both. In Denmark, Tivoli is a trademark licensed from Kjøbenhavns Sommer - Tivoli A/S. C-bus is a trademark of Corollary, Inc. in the United States and/or other countries. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and/or other 256 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products â countries. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States and/or other countries. PC Direct is a trademark of Ziff Communications Company in the United States and/or other countries and is used by IBM Corporation under license. ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel Corporation in the United States and/or other countries. UNIX is a registered trademark in the United States and other countries licensed exclusively through The Open Group. SET, SET Secure Electronic Transaction, and the SET Logo are trademarks owned by SET Secure Electronic Transaction LLC. Other company, product, and service names may be trademarks or service marks of others. Appendix F. Special notices 257 258 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Appendix G. Related publications The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this redbook. G.1 IBM Redbooks For information on ordering these publications see “How to get IBM Redbooks” on page 263. • Enterprise Integration with Domino for S/390, SG24-5150 • Lotus Domino R5.0 Enterprise Integration: Architecture and Products, SG24-5593 • Lotus Domino for S/390 Release 5: Installation, Customization and Administration, SG24-2083 • Lotus Domino for S/390 Release 5: Performance Tuning & Capacity Planning, SG24-5149 • Lotus Domino Release 5: A Developer’s Handbook, SG24-5331 • Porting C Applications to Lotus Domino on S/390, SG24-2092 • MQSeries Primer, Redpaper • Lotus Notes and Domino 5.0 Security Infrastructure Revealed, SG24-5341 • Connecting Domino to the Enterprise Using Java, SG24-5425 G.2 IBM Redbooks collections Redbooks are also available on the following CD-ROMs. Click the CD-ROMs button at ibm.com/redbooks for information about all the CD-ROMs offered, updates and formats. Collection Kit Number IBM System/390 Redbooks Collection SK2T-2177 IBM Networking Redbooks Collection SK2T-6022 IBM Transaction Processing and Data Management Redbooks Collection SK2T-8038 IBM Lotus Redbooks Collection SK2T-8039 Tivoli Redbooks Collection SK2T-8044 IBM AS/400 Redbooks Collection SK2T-2849 IBM Netfinity Hardware and Software Redbooks Collection SK2T-8046 IBM RS/6000 Redbooks Collection SK2T-8043 IBM Application Development Redbooks Collection SK2T-8037 IBM Enterprise Storage and Systems Management Solutions SK3T-3694 CD-ROM Title © Copyright IBM Corp. 2001 259 G.3 Other resources These publications are also relevant as further information sources: • MQSeries Application Programming Guide, SC33-0807 • MQSeries Command Reference, SC33-1369 • MQSeries for OS/390: Concepts and Planning Guide, GC34-5650 • MQSeries for OS/390: System Management Guide, SC34-5374 • MQSeries LotusScript Extension, SC34-5404 • MQSeries Intercommunication, SC33-1872 • CICS TS for OS/390: CICS External Interfaces Guide, SC33-1944 • CICS TS for OS/390: CICS System Definition Guide, SC33-1682 • DB2 V6 for OS/390 ODBC Guide and Reference, SC26-9005 • DB2 for OS/390 Administration Guide, SC26-9003 • MQSeries Application Programming Guide, SC33-0807 • MQSeries-CICS/ESA Bridge User’s Guide (from the MQSeries SupportPacs home page -- see section G.4) Lotus products come with extensive help databases and documentation. These include: • Domino Designer help • Domino Administration help • LSX for Lotus Connectors manual • DECS documentation • LEI documentation • MQLSX documentation G.4 Referenced Web sites These Web sites are also relevant as further information sources: • http://www.s390.ibm.com/products/domino/ Domino for S/390 home page • http://www.software.ibm.com/ts/cics/ CICS TS home page 260 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products • http://www.software.ibm.com/ts/cics/txppacs/ CICS TS SupportPacs home page • http://www.software.ibm.com/ts/mqseries/ MQSeries home page • http://www.software.ibm.com/ts/mqseries/txppacs/ MQSeries SupportPacs home page • http://http://www.lotus.com/home.nsf/welcome/eizone Lotus Enterprise Integration Products home page • http://www.software.ibm.com/ts/mqseries/library • http://www.lotus.com/enterpriseintegration •http://www.lotus.com/home.nsf/welcome/eizone •http://w3.itso.ibm.com •http://w3.ibm.com •http://www.elink.ibmlink.ibm.com/pbl/pbl Appendix G. Related publications 261 262 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products How to get IBM Redbooks This section explains how both customers and IBM employees can find out about IBM Redbooks, redpieces, and CD-ROMs. A form for ordering books and CD-ROMs by fax or e-mail is also provided. • Redbooks Web Site ibm.com/redbooks Search for, view, download, or order hardcopy/CD-ROM Redbooks from the Redbooks Web site. Also read redpieces and download additional materials (code samples or diskette/CD-ROM images) from this Redbooks site. 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. • E-mail Orders Send orders by e-mail including information from the IBM Redbooks fax order form to: In United States or Canada Outside North America • Telephone Orders United States (toll free) Canada (toll free) Outside North America 1-800-879-2755 1-800-IBM-4YOU Country coordinator phone number is in the “How to Order” section at this site: http://www.elink.ibmlink.ibm.com/pbl/pbl e-mail address pubscan@us.ibm.com Contact information is in the “How to Order” section at this site: http://www.elink.ibmlink.ibm.com/pbl/pbl • Fax Orders United States (toll free) Canada Outside North America 1-800-445-9269 1-403-267-4455 Fax phone number is in the “How to Order” section at this site: http://www.elink.ibmlink.ibm.com/pbl/pbl This information was current at the time of publication, but is continually subject to change. The latest information may be found at the Redbooks Web site. IBM Intranet for Employees IBM employees may register for information on workshops, residencies, and Redbooks by accessing the IBM Intranet Web site at http://w3.itso.ibm.com/ and clicking the ITSO Mailing List button. Look in the Materials repository for workshops, presentations, papers, and Web pages developed and written by the ITSO technical professionals; click the Additional Materials button. Employees may access MyNews at http://w3.ibm.com/ for redbook, residency, and workshop announcements. © Copyright IBM Corp. 2001 263 IBM Redbooks fax order form Please send me the following: Title Order Number Quantity First name Company Address City Telephone number Invoice to customer number Credit card number Last name Postal code Telefax number Country VAT number Credit card expiration date Card issued to Signature We accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card not available in all countries. Signature mandatory for credit card payment. 264 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Glossary ACL Access control list. A list of database users (individual users, Lotus Domino servers, and groups of users and/or servers) created and updated by the database manager. The ACL specifies which users can access the database and what tasks they can perform. Address space An OS/390 construct used to represent a batch job, TSO/E user, started task, OS/390 UNIX Systems Services user, or forked USS process. An address space control block (ASCB) points to many other control blocks used to manage the virtual storage, I/O resources and programs used by the work unit. A USS process creates an address space. ADSM ADSTAR Distributed Storage Manager. IBM product for distributed file backup, restore, archive and more. The products have been rebranded to Tivoli Data Manager (TDM). APAR Authorized Program Analysis Report. IBM record of a software problem. Canonical Format Format for storing hierarchical names that displays the hierarchical attribute of each component of the name. For example, the canonical format for the name Reuben Smith/ Ottawa/Acme/CA is: CN=Reuben Smith/OU=Ottawa/O=Acme/C=CA where: CN is the common name, OU is the organizational unit, O is the organization, and C is the country code. CMG Computer Measurement Group. They hold conferences on technology management and performance evaluation. DADSM Direct Access Device Space Management. Routines of the OS/390 operating system that manage disk storage. DAE Dump Analysis and Elimination. DECS Domino Enterprise Connection Services. A forms-based interface that allows integration to external data from Domino applications. DFSMS Data Facility Storage Management Subsystem. A software suite that automatically manages data from creation to expiration. DFSMS/MVS provides allocation control for availability and performance, backup/recovery and disaster recovery services, space management, tape management, and reporting and simulation for performance and configuration tuning. DNN Domino Named Network DNS Domain Name System. A function to associate names and addresses on Internet domain servers. Domain A Domino domain is a collection of Domino servers and users that share a common Domino directory. The primary function is mail routing. Users' domains are determined by the location of their server-based mail files. GAN Global area network. GRS Global Resource Serialization. An OS/390 base component that manages serialization. HTTP Hypertext Transmission Protocol. An Internet protocol used to transfer files from one computer to another. ICM Internet Cluster Manager. Domino component for failover and load balancing of HTTP clustering. IMAP Internet Message Access Protocol. A mail protocol that allows clients running it to retrieve mail from a host mail server also running the protocol. IMAP is similar to POP3 but has additional features. For example, it supports three modes of mailbox access. You can enable IMAP on a Domino server. I/O Input/output. IPCS Interactive Problem Control System. An OS/390 tool for examining operating system and subsystem dumps. The OS/390 flavor of IPCS is written in all caps. ipcs Inter-Process Communication System. A UNIX programming model to coordinate and serialize separate threads. The UNIX ipcs is usually written in lower case characters. © Copyright IBM Corp. 2001 265 IPL Initial program load. The initialization procedure that causes an operating system to start operation. IRIS A wholly owned division of Lotus. They developed the Domino/Notes product. ITSO International Technical Support Organization. JES2 Job Entry Subsystem/2. A component of OS/390 that manages the initiation and termination of batch jobs, TSO users and started tasks as well as printed output. LAN Local area network. LDAP Lightweight Directory Access Protocol. A set of protocols for accessing information directories. LDAP is based on the X.500 protocol, but supports TCP/IP, which is necessary for Internet access. Because it's a simpler version of X.500, LDAP is sometimes called X.500-lite. You can enable LDAP on a Domino server to allow LDAP clients to access information in Domino directory, for example, e-mail addresses. Logical partition In LPAR mode, a subset of the processor unit resources that is defined to support the operation of a system control program (SCP). Logically partitioned mode (LPAR) A mode that allows the operator to allocate hardware resources of the processor unit among several logical partitions. Lotus A wholly-owned subsidiary of IBM, and the owner of the Domino/Notes product. LotusScript A version of BASIC that offers not only standard capabilities of structured programming languages, but a powerful set of language extensions that enable object-oriented development within and across products. Its interface to Notes is through predefined object classes. LPAR Logical Partition. System/390 capability to divide up the processors, memory and channels so that several operating system images can run independently on the same machine. LS:DO The ODBCConnection, ODBCQuery, and ODBCResultSet classes, collectively called the LotusScript Data Object (LS:DO), provide properties and methods for accessing and updating tables in external databases through the ODBC (Open Database Connectivity) Version 2.0 standard. MIB Management Information Base. Defines the scope of what can be managed by SNMP. MIME Multipurpose Internet Mail Extensions. Software that allows you to attach non-text files to Internet mail messages. Non-text files include graphics, spreadsheets, formatted word-processor documents, and sound files. MTA Mail transfer agent. A message transfer agent, also called a gateway, is a program that translates messages between mail formats. NAB Notes Name and Address Book. Now called the Domino directory or Personal Address Book. NNN Notes Named Network. Now DNN or Domino Named Network. NNS Notes Name Service. Domino service for converting Fully Qualified Domain Names or Host names to a TCP/IP address. NNSC Notes Name Service Cache. Hidden fields in the user’s personal NAB Location document that is used when accessing the Domino server in question or in the server document of the server that initiated the connection to the other Domino server. NNTP Network News Transfer Protocol. Protocol that supports reading newsgroups, posting new articles, and transferring articles between news servers. When enabled on a Domino server, allows NNTP clients to access newsgroups on the server and allows the Domino server to exchange news with other NNTP servers. NRPC or Notes RPC Notes remote procedure call. This is the architectural layer of Notes used for all Notes-to-Notes communication. You can set up either the HTTP or the SOCKS proxy to work with RPC. NSF The file extension for a Notes database file (.NSF). A database file contains the data for an application. Its structure is composed of forms, 266 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products fields, folders, views, and other presentation features, such as a navigator and a database icon. NTF The file extension for a Notes template file (.NTF). A template file contains the structure for the database—that is, forms, folders, and views—but does not contain documents. Domino Designer comes with a collection of templates that you can use to create system and application databases. NTI Notes Transport Interface. The component of Domino server that manages communications. ODBC Open Database Connectivity. A standard developed by Microsoft for accessing external data. ODBC has four components: the ODBC-enabled application; the ODBC Driver Manager; ODBC drivers; data sources. Lotus Notes is an ODBC-enabled application. ODS On Disk Structure. The format in which a Notes database is physically stored on disk, this is also called a database format. In Release 5, the ODS version of a database is listed on the Info tab of the Database Properties box. POP3 Post Office Protocol (level 3). A mail protocol that allows clients running it to retrieve mail from a host mail server also running the protocol. You can enable POP3 on a Domino server. PTF Program Temporary Fix. A temporary solution or by-pass for a problem diagnosed by IBM as resulting from an error in a current unaltered release of the program. QMR Quarterly Maintenance Release. Lotus software upgrade package, distributed quarterly, to give customers the latest release level of Domino/Notes code. The entire package must be installed, as it is a complete code replacement. QMU Quarterly Maintenance Upgrade. Lotus software upgrade package distributed between QMRs and designated by a letter, for example 5.0.4a. It is for critical or widespread fixes to Domino code. RMF Resource Measurement Facility. Monitors the activity of the OS/390 system. It is useful for capacity planning, performance tuning, and problem diagnosis. RMF gives information about system resources, workload groups, DASD controllers, and DASD volumes. SIMS Support Information Management System. Lotus internal databases for tracking problems SMF System Management Facilities. OS/390 facility for recording performance and capacity data. S/MIME Secure/MIME. A secure version of the MIME protocol that allows users to send encrypted and electronically signed mail messages, even if users have different mail programs. SDSF Spool Display Search Facility. OS/390 tool for JES2 systems that allows a TSO user to view and route output from the JES2 spool and to view the SYSLOG and issue commands to OS/390 if authorized. SLA Service level agreement. SMTP Simple Mail Transfer Protocol. The Internet standard host-to-host mail transport protocol. It traditionally operates over TCP/IP using port 25. SMTP does not provide a mailbox facility, or any special features beyond basic mail transport. SNMP Simple Network Management Protocol. A TCP/IP protocol to enable managing remote hosts. SPR Software Problem Record. Lotus software problem record tracking record. SSL Secure Sockets Layer. Security protocol for the Internet and intranets that provides communications privacy and authentication for Domino server tasks that operate over TCP. TCB Task Control Block. An OS/390 construct that represents a dispatchable unit of work. One address space can create multiple tasks. A USS thread creates a TCB in OS/390. TCP/IP Transmission Control Protocol/Internet Protocol. Network protocols that define the Internet. Originally designed for UNIX, TCP/IP software is now available for every major computer operating system. 267 TDP Tivoli Data Protection. terabyte A trillion characters of data. TSO/E Time Sharing Option/Extended. The principal interactive interface to OS/390. UNIX An operating system developed at Bell Laboratories (trademark of UNIX System Laboratories, licensed exclusively by X/Open Company, Ltd.). URL Uniform Resource Locator. VIPA Virtual Internet Protocol (IP) addressing. A virtual TCP/IP address that can direct network traffic to more than one physical adapter. VTOC Volume Table of Contents. A list on each disk volume of the files and space it contains. WAN Wide area network. 268 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Index Symbols /notesdata 10, 32 /usr/lpp/lotus 32 @functions 89 architecture 184 design 183 enterprise 183 framework 3 integration 5 middleware 3 office 6 tools 183 archive activity 48, 126 ASCII 84, 85 editor 10 Numerics 3270 application 171, 172 terminal 169 A access control list (ACL) 89, 206 DECS 206 accessing DB2 233 ACL see access control list (ACL) action button 30 Action method LCConnection in LotusScript 210 activity 63 document (DECS) 14 form 63 killing 42 adapters 169 Add method LCCurrency in LotusScript 217 LCNumeric in LotusScript 217 add-in code 84 Adjust method LCDatetime in LotusScript 218 admin-backup activity 48 administration database 13 DECS 13 admin-purge log activity 48 ADMINSERVER 33 advanced scheduling options 144 agent 147 debugging 148 manager 148 run on server 147 API toolkit 85 Append method LCFieldList in LotusScript 212 LCStream in LotusScript 215 application B batch adapter 79 batch/TSO adapter 169 BLOBs 107 browsing cache clearing 42 button hotspot 152 C C language application 85 C/C++ 85 cache, clearing 42 CAE for DB2 31 call 151 Call method LCConnection in LotusScript 210 catalog 151 Catalog method LCConnection 210 CGI program 63 CICS 169, 173 application 174, 175, 176 , 183 with MQSeries 169, 173 classes 69 classes, description of LotusScript connector 68 clear browsing cache 42 clear lock agent 42 Clear method LCDatetime in LotusScript 218 LCStream in LotusScript 215 ClearStatus method LCSession in LotusScript 209 ClearVirtualCode method LCField in LotusScript 213 © Copyright IBM Corp. 2001 269 code add-in 84 sample 85 code page conversion errors 151 conversion tables 78 command activity 48, 110 center 132 show tasks 34 commitment control 19 Compare method LCCurrency in LotusScript 217 LCDatetime in LotusScript 218 LCField in LotusScript 213 LCNumeric in LotusScript 217 LCStream in LotusScript 215 Connect method LCConnection in LotusScript 210 connection defining 17 document 21 pooling 162 connector 6 LotusScript classes 68 models DECS 183 LEI 183 programmatic 183 products 86 programmatic 67 connector code 83, 84 , 89 server-based 147 writing your own 83 advantages 83 maintenance 83 performance 83 console messages 87 Convert method LCField in LotusScript 213 LCStream in LotusScript 215 Copy method LCConnection in LotusScript 210 LCCurrency in LotusScript 217 LCDatetime in LotusScript 219 LCField in LotusScript 213 LCFieldList in LotusScript 212 LCNumeric in LotusScript 217 LCStream in LotusScript 215 CopyField method LCFieldList in LotusScript 212 CopyRef method LCFieldList in LotusScript 212 Count property LCField in LotusScript 213 Create method LCConnection in LotusScript 210 D data conversion 85 external source 19, 23 journaling (DECS) 19 database name 110 searching 27 synchronization 130 Datatype property LCField in LotusScript 213 datatypes 69 DatetimeListGetRange method LCStream in LotusScript 215 DatetimeListGetValue method LCStream in LotusScript 215 DatetimeListInsertRange method LCStream in LotusScript 215 DatetimeListInsertValue method LCStream in LotusScript 215 DatetimeListRemoveRange method LCStream in LotusScript 215 DatetimeListRemoveValue method LCStream in LotusScript 215 Day property LCDatetime in LotusScript 218 DB2 156 database 183 deleting rows 160 inserting 156 ODBC driver 93 querying call 151 catalog 151 execute 151 select 151 remote instances 95 270 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products setting up 93 table, deleting rows 160 DB2 Connect 31 DDL statement 97 Debug_AMgr 149 debugging 148 declarative tools 183 DECS See Domino Enterprise Connection Services (DECS) decsext 11 DECSNativeText 11 DECSTranslation 11 design 85 designated server 42 DFH$DM 233 DFH$DMB 234 DFH$DMC 235 DFH$DMD 233, 235 DFH$DMNU 236, 244 direct transfer activity 49 Disconnect method LCConnection in LotusScript 210 Domino 86 console (DOMCON) 87 Designer 79 extension manager 11 multi-threading 147 server console 34 logging 26 Domino Enterprise Connection Services Caching option 199 Conflict Detection option 202, 205 Create Event options 201 Data Integrity option 197 Data Storage option 200, 207 Delete Event options 207 Field Level Updates option 205 Filter Formula option 196, 197 Form Override option 196, 197 General activity options 195 Key Field Updates option 206 Maximum Connections option 196 Missing External Records option 203 Monitor Order option 195, 200 Open Event options 202 Post-Open formula 202, 205 Pre-Create formula 201 Pre-Delete formula 207 Pre-Update formula 204, 205 Stored Procedure option 201, 203, 204, 207 Trim Trailing Spaces option 198 Update Event options 202, 204 Domino Enterprise Connection Services (DECS) 6, 9, 105 activity 16 defining 21 real-time 21 administration database 13, 14 connections 17 creating activity 22 views 16 commitment control 19 connections 16, 17 defining 17 document 21, 24 controlling 11 data sources 18 external 23 field level help 102 field mapping error 102 initialize keys 17, 104 installing 9 journaling 19 logging 26 manual startup 12 mapping 24 menu commands 17 metadata 22 model of connecting 183 navigator 14 performance 196, 200 realtime 9, 11 fields 106 running 12 with LEI 9 scheduling 26 user assistant 16, 22 view option 97 Web browser 106 with DB2 99 wizard 15, 21 creating connections 17 Year 2000 12 Domino for OS/390 169 Drop method LCConnection in LotusScript 210 271 DSNZPARM 94 DST property LCDatetime in LotusScript 218 G GetCurrency method LCField in LotusScript 213 GetDatetime method LCField in LotusScript 213 GetDiff method LCDatetime in LotusScript 219 GetField method LCFieldList in LotusScript 212 GetFieldList method LCField in LotusScript 213 GetFloat method LCField in LotusScript 213 GetFormatNumber method LCField in LotusScript 213 GetFormatStream method LCField in LotusScript 213 GetInt method LCField in LotusScript 214 GetName method LCFieldList in LotusScript 212 GetNumeric method LCField in LotusScript 214 GetProperty method LCConnection in LotusScript 210 GetStatus method LCSession in LotusScript 209 GetStatusText method LCSession in LotusScript 209 GetStream method LCField in LotusScript 214 E EBCDIC 84, 85 encryption 64 key 18 enterprise application 85, 183 connector 85 computing 3 data 9 environment variables 32 ERP 29 error conditions 85 Event handling LotusScript Data Object 72 execute 151 synchronously 141 Execute method LCConnection in LotusScript 210 export 32 extension manager 11 external data source 19, 23 Extract method LCStream in LotusScript 215 F Fetch method LCConnection in LotusScript 210 field mapping 122, 134 FieldCount property LCFieldList in LotusScript 211 Fields property LCFieldList in LotusScript 211 file transfer program (ftp) 84 Flags property LCField in LotusScript 213 LCStream in LotusScript 214 flat file 172 Format property LCStream in LotusScript 214 formula 49 frameset 176 full text index 26 functions 89 H hierarchical file system (HFS) 86 hotspot 152 Hour property LCDatetime in LotusScript 218 HTML form 63 HTTP 177 access to data 5 server 89 server partitioning 86 Hundredth property LCDatetime in LotusScript 218 Hyper-Text Transfer Protocol DECS caching option 199 272 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products I IBM, shopping 174 IMS with MQSeries 169 IncludeField method LCFieldList in LotusScript 212 indexing, full text 26 initialize keys 14 , 17 error encountered 14 input mode 87 Insert method LCConnection in LotusScript 210 LCFieldList in LotusScript 212 INSTALLCLUSTER 33 INSTALLSERVER 33 Intel server 85 IsNull property LCField in LotusScript 213 ITSODMB 234 ITSODMC 235 ITSODMD 235 ITSODMNU 236, 244, 249 J journaling 19 Julian property LCDatetime in LotusScript 218 K key field transfer 65 keyed retrieval 150, 152 KeyFilename 88 keys, initializing 14, 17 kill activity 42 L LCConnection 62 LotusScript class 69 LCConnection class description of LotusScript 210 LCCurrency LotusScript class 70 LCCurrency class description of LotusScript 217 LCDatetime LotusScript class 70 LCDatetime class description of LotusScript 218 LCField LotusScript class 70 LCField class description of LotusScript 213 LCFieldlist 62 LotusScript class 69 LCFieldlist class description of LotusScript 211 LCLSX 184 see also Lotus Connectors LotusScript Extensions LCNumeric LotusScript class 70 LCNumeric class description of LotusScript 216 LCSession 62 LotusScript class 69 LCSession class description of LotusScript 209 LCStream LotusScript class 70 LCStream class description of LotusScript 214 LCTEST 14, 44, 95, 111 LEI See Lotus Enterprise Integrator (LEI) leiclean 33 Length property LCStream in LotusScript 214 libascii 85 toolkit 85 link pack area (LPA) 86 List method LCFieldList in LotusScript 212 ListConnector method LCSession in LotusScript 209 ListMetaConnector method LCSession in LotusScript 209 ListProperty method LCConnection in LotusScript 210 local queue 79 log 16, 26, 148, 191 link 116 Log_AgentManager 149 Lookup method LCFieldList in LotusScript 212 LookupConnector method LCSession in LotusScript 209 273 LookupMetaConnector method LCSession in LotusScript 209 LookupProperty method LCConnection in LotusScript 210 LookupVirtualCode method LCField in LotusScript 214 Lotus Connectors LotusScript Extensions (LCLSX) programming 150 Lotus Enterprise Integrator (LEI) 6 activity admin-backup 48 admin-purge 48 archive 48, 126 author privileges 54 command 48, 110 constructing 53, 64 constructing with action buttons 53 create agent 60 direct transfer 49, 64 document 36, 47 form 63 killing 42 map fields 58, 65 polling 49, 139 realtime 50, 63, 65, 145 replication 51, 130 RunASAP 61, 66 running by schedule 62 sample scenario 63 scripted 53 select metadata 55, 65 starting 40 administration 43 database 30, 35, 36 menu commands 40 navigator 38 architecture 29 coexisting with DECS 9 commands administrator 35 server console 34 configuration document 37 administrator 37 client 37 server 37 connection creating 40 document 37, 43 to DB2 109 connectors constructing 45, 63 DB2 44, 63 file 44 models of 184 Notes 44, 64 testing 44, 64 text 44 data sources, supported 44 designated server 42 development client 30 direct transfer activity 49 ERP connections 29 field mapping 122 installation 31 command file 32 introduction 29 LCLSX extensions 62 log 40, 136 database 30 link 116 LotusScript agents 30 metaconnection 41 metaconnector 46 Notes direct transfer 119 RunASAP 43, 114 running as add in task 34 sample databases 31 script vault 30 server console commands 34 servertasks 34 shutdown 43 stop 43 Lotus multi-byte character set (LMBCS) 84 Lotus NotesPump 9 LotusScript agents 30, 147 code 89 Data Object (LSDO -- see also LSDO) 71 Extension (LSX) 84 LotusScript Extension for Lotus Connectors (LCLSX) 6, 67 LSDO 84, 148, 184 programming 164 LSX 84 M Map method 274 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products LCFieldList in LotusScript 212 MapName method LCFieldList in LotusScript 212 mapping 20, 30 MaxLength property LCStream in LotusScript 215 Merge method LCFieldList in LotusScript 212 LCStream in LotusScript 216 MergeVirtual method LCFieldList in LotusScript 212 message polling 179 queue 170 message queue manager 79, 169 message queueing interface (MQI) 72 metaconnector collapse/expand 46 connection broker 46 constructing 47 in LEI 46 metering 46 order 46 metadata 22, 30, 67, 120, 127 defined 67 Minute property LCDatetime in LotusScript 218 miscellaneous events view 26 Month property LCDatetime in LotusScript 218 MQ options 180 MQForum 82 MQGET 180 MQGetMessageOptions class 75 MQLSX See MQSeries Lotus Script Extensions (MQLSX) mqlsxown script 79 MQMessage class 75 MQProcess class 75 MQPutMessageOptions class 75 MQQueue class 75 MQQueueManager class 75 MQSeries 87, 169, 173 batch/TSO adapter 169 C header files 75 CICS 169 for OS/390 169 IMS 169 message queueing interface (MQI) 72 processes 171 setting up 169 MQSeries LotusScript Extensions (MQLSX) 6, 72, 74, 169, 173, 184 tracing 78 MQSeries-CICS adapter 169 MQSeries-CICS bridge 169, 170, 171 MQSession Class 75 multi-threading 147 multivalue field 98, 105, 107 N Names property LCFieldList in LotusScript 212 Net.Data 5 network file system (NFS) 84 non-journaled data 63 non-programmatic connectors 6 non-relational database 172 Notes C/C++ API 84 Notes direct transfer 119 notes.ini 10 DECSCenturyBoundary 12 DECSNativeText 11 DECSTranslation 11 servertasks 10, 12, 34 notesdata 10, 32 NotesPump 9, 84 NumberListGetRange method LCStream in LotusScript 216 NumberListGetValue method LCStream in LotusScript 216 NumberListInsertRange method LCStream in LotusScript 216 NumberListInsertValue method LCStream in LotusScript 216 NumberListRemoveRange method LCStream in LotusScript 216 NumberListRemoveValue method LCStream in LotusScript 216 O ODBC 71, 148 driver 93 initialization file 93 OEDITASCII 10 OMVS 87 275 input mode 87 organization database 98 override 21 owner of DB2 table 20 P Parallel Sysplex 3 parameter document 166 password 18, 63 performance 83, 162, 191 tips 193 polling activity 49, 139 agent 177 frequency 144 pooled connection 196 porting applications 85 Precision property LCNumeric in LotusScript 216 primary key 132 replication 51 primary key/timestamp replication 52 procedure, stored 162 procurement 173 program logic 86 programmatic connectors model 184 programmatic connectors 6, 67, 147 property fields 63 DECS 9, 11 fields 106 LEI 9 RecordCount property LCFieldList in LotusScript 212 redundant data 183 relational database management system (RDBMS) 85 Remove method LCConnection in LotusScript 211 LCFieldList in LotusScript 212 Replace method LCFieldList in LotusScript 212 replication 132 activity 51, 130 primary key 51 primary key/timestamp 52, 132 ResetFormat method LCStream in LotusScript 216 result set 68 robustness 85 run on server 147, 165 RunASAP 137 S sample code 85 databases 31 Scale property LCNumeric in LotusScript 216 scripted activity 53 search a database 27 Second property LCDatetime in LotusScript 218 security 88 select 151 Select method LCConnection in LotusScript 211 Sequence property LCFieldList in LotusScript 212 servertasks 10, 12, 34, 84 LEI 34 SetConstant method LCDatetime in LotusScript 219 SetCurrency method LCField in LotusScript 214 SetCurrent method LCDatetime in LotusScript 219 Q QBRW 233 QINQ 233 QMNU 233 queues, MQSeries 170 QUPD 233 R RACF 86, 97, 112 user ID 86 RangeCount property LCStream in LotusScript 215 realtime access 184 activity 50, 145 276 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products SetDatetime method LCField in LotusScript 214 SetFieldList method LCField in LotusScript 214 SetFloat method LCField in LotusScript 214 SetFormat method LCStream in LotusScript 216 SetFormatDatetime method LCField in LotusScript 214 SetFormatNumber method LCField in LotusScript 214 SetFormatStream method LCField in LotusScript 214 SetInt method LCField in LotusScript 214 SetName method LCFieldList in LotusScript 212 SetNumeric method LCField in LotusScript 214 SetProperty method LCConnection in LotusScript 211 SetStream method LCField in LotusScript 214 SetVirtualCode method LCField in LotusScript 214 Shop IBM 174 show tasks command 34 skills required 89 Sleep method LCSession in LotusScript 209 SPUFI 97, 116, 132 SQL 114, 132, 151 query 49 Status property LCSession in LotusScript 209 STEPLIB 78, 94 sticky bit 86 stored procedure 162 string comparison 153 Subtract method LCCurrency in LotusScript 217 LCNumeric in LotusScript 217 SupportPac 77 tablespace 110 testing 85 environment 86 partitioning 86 Text property LCCurrency in LotusScript 217 LCDatetime in LotusScript 218 LCField in LotusScript 213 LCNumeric in LotusScript 217 LCStream in LotusScript 215 TextListFetch method LCStream in LotusScript 216 TextListInsert method LCStream in LotusScript 216 TextListRemove method LCStream in LotusScript 216 Ticks property LCDatetime in LotusScript 218 timestamp archiving 130 tool, application 183 toolkit API 85 libascii 85 tracing 78 transaction logging 189 rate 86 high 86 Trim method LCStream in LotusScript 216 TSODMA 233 U UNIX 85 UNIX 95 85 Update method LCConnection in LotusScript 211 updating 156 UseLSX 72, 153 user assistant 16, 22 user ID, server 32 V Value property LCCurrency in LotusScript 217 LCDatetime in LotusScript 218 LCField in LotusScript 213 LCNumeric in LotusScript 217 T table owner 20 277 LCStream in LotusScript 215 ValueCount property LCStream in LotusScript 215 variables, checking 153 verify document 80 viascii 10 VSAM dataset 171, 172 file 174, 176, 183 W Web 149, 177 WebSphere Application Server 5 Weekday property LCDatetime in LotusScript 218 wizard interface (DECS) 14 writing your own connector code 83 X XPG4 UNIX Profile 85 Y Year property LCDatetime in LotusScript 218 Z Zone property LCDatetime in LotusScript 218 278 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products IBM Redbooks review Your feedback is valued by the Redbook authors. In particular we are interested in situations where a Redbook "made the difference" in a task or problem you encountered. Using one of the following methods, please review the Redbook, addressing value, subject matter, structure, depth and quality as appropriate. • Use the online Contact us review redbook form found at ibm.com/redbooks • Fax this form to: USA International Access Code + 1 914 432 8264 • Send your comments in an Internet note to redbook@us.ibm.com Document Number Redbook Title Review SG24-5682-00 Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products What other subjects would you like to see IBM Redbooks address? Please rate your overall satisfaction: Please identify yourself as belonging to one of the following groups: Your email address: The data you provide here may be used to provide you with information from IBM or our business partners about our products, services or activities. Questions about IBM’s privacy policy? O Very Good O Good O Average O Poor O Solution Developer O Customer O Business Partner O IBM, Lotus or Tivoli Employee O None of the above O Please do not use the information collected here for future marketing or promotional contacts or other communications beyond the scope of this transaction. The following link explains how we protect your personal information. ibm.com/privacy/yourprivacy/ © Copyright IBM Corp. 2001 279 Lotus Domino for S/390 Release 5: Enterprise Integration (0.5” spine) 0.475”<->0.875” 250 <-> 459 pages ® Lotus Domino for S/390 Release 5: Enterprise Integration Using Domino Connector Products Connect collaborative computing applications to enterprise host systems Install, configure and use Lotus connector products in S/390 Sample code and scenarios provided The robustness and scalability of S/390, teamed with the collaboration tools of Lotus Domino, makes a powerful combination. To increase the business power of a S/390 Domino environment, you can integrate the data and applications on your S/390 with the collaborative application environment of the Domino system. This IBM Redbook tells you how to connect collaborative computing applications to enterprise host systems. We give a detailed description of the Lotus connector products available on the S/390, including installation and configuration. We provide sample code that reads, updates, and deletes enterprise data from DB2. In addition, we show how to interface to CICS using MQSeries on the host, without needing client code on each workstation. This redbook will help system architects, database administrators, and Notes developers to integrate S/390 data and applications with Domino applications in a S/390 environment. INTERNATIONAL TECHNICAL SUPPORT ORGANIZATION BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment. For more information: ibm.com/redbooks SG24-5682-00 ISBN 0738419583