Lotus Connectors and Connectivity GuideFile/lccon6.pdf · iv Lotus Connectors and Connectivity Guide. 234 Connectivity to a Collapse/Expand ... Note The LC LSX is supplied with the

Copyright

Under the copyright laws, neither the documentation nor the software may be copied, photocopied,reproduced, translated, or reduced to any electronic medium or machine-readable form, in whole or inpart, without the prior written consent of IBM Corporation, except in the manner described in thedocumentation or the applicable licensing agreement governing the use of the software.

©Copyright 1985 - 2002 Lotus Development Corporation

©Copyright 2002 IBM CorporationLotus Software, IBM Software GroupOne Rogers StreetCambridge, MA 02142

All Rights Reserved.

List of Trademarks

Domino, cc:Mail, Notes, NotesBench, Domino Connectors, Domino Enterprise Connection Services,IBM Lotus Enterprise Integrator for Domino (LEI), and Notes/FX are trademarks; and Freelance,Freelance Graphics, Lotus, Lotus Notes, LotusScript, Notes Mail, NotesSQL, NotesView, 1-2-3,Organizer, SmartIcons, and SmartSuite are registered trademarks of Lotus Development Corporationand/or IBM Corporation in the United States, other countries, or both. OS/2 Warp and PowerPC aretrademarks and AIX, IBM, OS/2 Presentation Manager, and SNA are registered trademarks, andDB2/2 and RS/6000 are trademarks of International Business Machines Corporation. Tivoli/Courier isa trademark of Tivoli Systems and/or IBM Corporation in the United States, other countries, or both.

All other trademarks are the property of their respective owners.

Disclaimer

THIS DOCUMENTATION IS PROVIDED FOR REFERENCE PURPOSES ONLY. WHILE EFFORTSWERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATIONCONTAINED IN THIS DOCUMENTATION, THIS DOCUMENTATION IS PROVIDED "AS IS"WITHOUT ANY WARRANTY WHATSOEVER AND TO THE MAXIMUM EXTENT PERMITTED,LOTUS DISCLAIMS ALL IMPLIED WARRANTIES, INCLUDING WITHOUT LIMITATION THEIMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR APARTICULAR PURPOSE, WITH RESPECT TO THE SAME. LOTUS SHALL NOT BE RESPONSIBLEFOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, DIRECT, INDIRECT,CONSEQUENTIAL OR INCIDENTAL DAMAGES, ARISING OUT OF THE USE OF, OR OTHERWISERELATED TO, THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION.NOTWITHSTANDING ANYTHING TO THE CONTRARY, NOTHING CONTAINED IN THISDOCUMENTATION OR ANY OTHER DOCUMENTATION IS INTENDED TO, NOR SHALL HAVETHE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM LOTUS (OR ITSSUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF THEAPPLICABLE LICENSE AGREEMENT GOVERNING THE USE OF THIS SOFTWARE.

13When to Use IBM Distributed Database

Connection Services (DDCS) . . . . . . .

12Sample Steps for DB2 Administration

Client Configuration on UNIX . . . . . .

12Sample Steps for DB2 Administration

Client Configuration on NT . . . . . . .

11Getting Started . . . . . . . . . . . . . . . . . .11Connection for DB2 CAE and DDCS . . . .11ODBC DB2/400 Connectivity . . . . . . . .

9Connectivity to DB2 on iSeries . . . . . . . . .8Connectivity to DB2 . . . . . . . . . . . . . . .7Supported Activities . . . . . . . . . . . . . . .7DB2 Connectivity . . . . . . . . . . . . . . . . . . .72 Connectivity . . . . . . . . . . . . . . . . . .

5Examples . . . . . . . . . . . . . . . . . . . . . .5Running CONTEST . . . . . . . . . . . . . . . .4Syntax . . . . . . . . . . . . . . . . . . . . . . . .4Testing LEI Connections with CONTEST . . . .3Running DCTEST . . . . . . . . . . . . . . . . .3Syntax . . . . . . . . . . . . . . . . . . . . . . . .2

Testing Connectivity to External DataSources with DCTEST . . . . . . . . . . . .

2Supported Data Sources . . . . . . . . . . . . .1Overview . . . . . . . . . . . . . . . . . . . . . . . .11 DCTEST and CONTEST . . . . . . . .

xiContact and Support Information . . . . . . .viiiRelated Documentation . . . . . . . . . . . .viiOrganization of this Manual . . . . . . . . .viiPreface . . . . . . . . . . . . . . . . . . . . . . .

26Processing Empty and NULL Values in

LEI and DECS . . . . . . . . . . . . . . . .

26Transferring Attachments . . . . . . . . . . .25

Processing RTF Fields Between Notes andRDBMS . . . . . . . . . . . . . . . . . . . .

24LEI and Metaconnections: Specialized

Intermediate Connections . . . . . . . . .

24Using Multiple Connections of the Same

Type . . . . . . . . . . . . . . . . . . . . . .

23Connectors and Supported Data Sources . . .23Connectors Overview . . . . . . . . . . . . . . .23

3 Introduction to LotusConnectors . . . . . . . . . . . . . . . . . . .

21Sybase Connectivity Test . . . . . . . . . . .20Requirements for Sybase Connectivity . . .20Sybase Connectivity . . . . . . . . . . . . . . . .19OLE DB Connectivity Test . . . . . . . . . .19Requirements for OLE DB Connectivity . .19OLE DB Connectivity . . . . . . . . . . . . . . .18Oracle 8 Connectivity Test . . . . . . . . . .18Requirements for Oracle 8 Connectivity . .18Oracle 8 Connectivity . . . . . . . . . . . . . . .17Oracle 7 Connectivity Test . . . . . . . . . .17Requirements for Oracle 7 Connectivity . .17Oracle 7 Connectivity . . . . . . . . . . . . . . .16ODBC Connectivity Test . . . . . . . . . . .16Requirements for ODBC Connectivity . . .16ODBC Connectivity . . . . . . . . . . . . . . . . .15DB2 Connectivity Test . . . . . . . . . . . . .

i

Contents

59Notes Form Creation . . . . . . . . . . . . . .58LEI Replication of Notes . . . . . . . . . . . .58Activity Command Statements . . . . . . .58

Considerations when Working with theLotus Connector for Notes . . . . . . . .

46Fields in the Connection Document . . . .45Common Features . . . . . . . . . . . . . . . .44Notes Connection Document for LEI . . . . . .44Supported Characteristics . . . . . . . . . . .43Terminology . . . . . . . . . . . . . . . . . . .43

Introduction to the Lotus Connector forNotes . . . . . . . . . . . . . . . . . . . . . .

434 Lotus Connector for Notes . . . . .

40Connector Data Type Conversion Tables . . .39

Connectors and Supported RealTimeActivities . . . . . . . . . . . . . . . . . . .

38Connectors and Supported Data Manage-

ment Activities . . . . . . . . . . . . . . . .

37Calling External Procedures . . . . . . . . . . .35Creating Connection Documents . . . . . . . .34Manual Button . . . . . . . . . . . . . . . . . .32Common Connection Document Fields . .30

Features Common to All ConnectionDocuments . . . . . . . . . . . . . . . . . .

30Considerations . . . . . . . . . . . . . . . . . .29

Viewing or Editing ConnectionDocuments in DECS . . . . . . . . . . . .

29Creating a New Connection in DECS . . .29

Viewing or Editing ConnectionDocuments in LEI . . . . . . . . . . . . . .

29Creating a New Connection Document in

LEI . . . . . . . . . . . . . . . . . . . . . . .

28Connection Pooling . . . . . . . . . . . . . . .28Connection Documents . . . . . . . . . . . . . .27

Supported Connector Characteristics - List ofTerms . . . . . . . . . . . . . . . . . . . . .

85Fetch . . . . . . . . . . . . . . . . . . . . . . . .84Execute . . . . . . . . . . . . . . . . . . . . . .83Data Type Considerations . . . . . . . . . .83DB2 Data Types . . . . . . . . . . . . . . . . . . .80

Example: Sample LC LSX Agent to Call aDB2 Stored Procedure . . . . . . . . . . .

79Example: DB2 Stored Procedure in SQL . .78Example: DB2 Stored Procedure in C . . . .77

Considerations when Using StoredProcedures . . . . . . . . . . . . . . . . . .

76Stored Procedures . . . . . . . . . . . . . . . . . .75Fields in the DECS Connection Document . .74Common Features . . . . . . . . . . . . . . . .74DB2 Connection Document for DECS . . . . .69Fields in the LEI Connection Document . .68Common Features . . . . . . . . . . . . . . . .68DB2 Connection Document for LEI . . . . . . .67Supported Characteristics . . . . . . . . . . . . .66Identity Columns . . . . . . . . . . . . . . . . . .66Terminology . . . . . . . . . . . . . . . . . . .65Obtaining Updated DB2 Information . . .65Introduction to the Lotus Connector for DB2 .655 Lotus Connector for DB2 . . . . . .

63Lotus Connector for Notes Properties . . . . .63Virtual Fields . . . . . . . . . . . . . . . . . . .62Create . . . . . . . . . . . . . . . . . . . . . . .62Insert/Update . . . . . . . . . . . . . . . . . .61Fetch . . . . . . . . . . . . . . . . . . . . . . . .61Execute . . . . . . . . . . . . . . . . . . . . . .60Notes Data Types . . . . . . . . . . . . . . . . . .60

Moving Text List Data over DifferentPlatforms . . . . . . . . . . . . . . . . . . .

59Depositor Level Access . . . . . . . . . . . .59Notes @Functions . . . . . . . . . . . . . . . .

ii Lotus Connectors and Connectivity Guide

107Fields in the LEI Connection Document .106Common Features . . . . . . . . . . . . . . .104ODBC Connection Document for LEI . . . .104Supported Characteristics . . . . . . . . . .103Terminology . . . . . . . . . . . . . . . . . .103

Introduction to the Lotus Connector forODBC . . . . . . . . . . . . . . . . . . . .

1037 Lotus Connector for ODBC . . .

100File System Metadata . . . . . . . . . . . . .98

Considerations When Working with theLotus Connector for File System . . . . .

98Fields in the DECS Connection Document .96File System Connection Document for DECS .94Fields in the LEI Connection Document . .94Common Features . . . . . . . . . . . . . . . .92File System Connection Document for LEI . .92Supported Characteristics . . . . . . . . . . . . .91Terminology . . . . . . . . . . . . . . . . . . . . .91

Introduction to the Lotus Connector for FileSystem . . . . . . . . . . . . . . . . . . . . .

916 Lotus Connector for FileSystem . . . . . . . . . . . . . . . . . . . . . . .

89DB2 Database on a Different iSeries

System than Domino Server . . . . . . .

88DB2 Database on Same iSeries System as

Domino Server . . . . . . . . . . . . . . . .

88Accessing DB2 on an iSeries System Using

the Lotus Connector for DB2 . . . . . . .

88Problem Determination . . . . . . . . . . . .88Error Logging . . . . . . . . . . . . . . . . . .88Error Logging and Problem Determination . .87

Understanding Notes Data Type TransferConversions . . . . . . . . . . . . . . . . .

87XML Data Types . . . . . . . . . . . . . . . .86Create . . . . . . . . . . . . . . . . . . . . . . .85Insert/Update . . . . . . . . . . . . . . . . . .

137Lotus Connector for Oracle 7 Properties . . .137

Transferring Data Between Oracle andNotes . . . . . . . . . . . . . . . . . . . . .

136Transferring Data From Notes to Oracle 7

136Transferring Data From Oracle 7 to Notes

136Oracle 7 Field Mapping and NULL Entries .135Create . . . . . . . . . . . . . . . . . . . . . .135Insert/Update . . . . . . . . . . . . . . . . .134Fetch . . . . . . . . . . . . . . . . . . . . . . .133Execute . . . . . . . . . . . . . . . . . . . . .133Oracle 7 Data Types . . . . . . . . . . . . . . .132

The Lotus Connector for Oracle 7 andOutput Parameters . . . . . . . . . . . .

131Calling Oracle 7 Stored Procedures . . . . . .130Character Data Types and Key Fields . . . .129Fields in the DECS Connection Document

127Oracle 7 Connection Document for DECS . .123Fields in the LEI Connection Document .122Common Features . . . . . . . . . . . . . . .121Oracle 7 Connection Document for LEI . . .120Supported Characteristics . . . . . . . . . . . .120Terminology . . . . . . . . . . . . . . . . . . . .119

Introduction to the Lotus Connector forOracle 7 . . . . . . . . . . . . . . . . . . .

1198 Lotus Connector for Oracle 7 .

117Lotus Connector for ODBC Properties . . . .117

Considerations When Working with theLotus Connector for ODBC . . . . . . .

116Create . . . . . . . . . . . . . . . . . . . . . .115Insert/Update . . . . . . . . . . . . . . . . .114Fetch . . . . . . . . . . . . . . . . . . . . . . .113Execute . . . . . . . . . . . . . . . . . . . . .113ODBC Data Types . . . . . . . . . . . . . . . .112Fields in the DECS Connection Document

110ODBC Connection Document for DECS . . .

Contents iii

167Fields in the DECS Connection Document

166Common Features . . . . . . . . . . . . . . .165OLE DB Connection Document for DECS . .160Fields in the LEI Connection Document .160Common Features . . . . . . . . . . . . . . .159OLE DB Connection Document for LEI . . .158Supported Characteristics . . . . . . . . . .157Terminology . . . . . . . . . . . . . . . . . .157

Introduction to the Lotus Connector for OLEDB . . . . . . . . . . . . . . . . . . . . . . .

15710 Lotus Connector for OLE DB .

156Lotus Connector for Oracle 8 Properties . . .156Create . . . . . . . . . . . . . . . . . . . . . .156Insert/Update . . . . . . . . . . . . . . . . .155Fetch . . . . . . . . . . . . . . . . . . . . . . .155Execute . . . . . . . . . . . . . . . . . . . . .154Oracle 8 Data Types . . . . . . . . . . . . . . .152

Example: Sample LC LSX Agent to Call anOracle Stored Procedure . . . . . . . . .

151Example: Oracle Stored Procedure . . . .151

The Lotus Connector for Oracle 8 andOutput Parameters . . . . . . . . . . . .

150Stored Procedures . . . . . . . . . . . . . . . . .149Character Data Types and Key Fields . . . .149Table/View/Procedure Selection . . . .148Fields in the DECS Connection Document

146Oracle 8 Connection Document for DECS . .143Fields in the LEI Connection Document .142Common Features . . . . . . . . . . . . . . .140Oracle 8 Connection Document for LEI . . .140Supported Characteristics . . . . . . . . . .139Terminology . . . . . . . . . . . . . . . . . .139

Introduction to the Lotus Connector forOracle 8 . . . . . . . . . . . . . . . . . . .

1399 Lotus Connector for Oracle 8 .

194Execute . . . . . . . . . . . . . . . . . . . . .194Sybase Data Types . . . . . . . . . . . . . . . .193Calling Sybase Stored Procedures . . . . . . .193Troubleshooting and Supported Versions

192Data Insert . . . . . . . . . . . . . . . . . . .192Replication . . . . . . . . . . . . . . . . . . .192Sybase Operational Considerations . . . . . .191Fields in the DECS Connection Document

189Sybase Connection Document for DECS . . .186Fields in the LEI Connection Document .185Common Features . . . . . . . . . . . . . . .184Sybase Connection Document for LEI . . . .183Supported Characteristics . . . . . . . . . .183Terminology . . . . . . . . . . . . . . . . . .183

Introduction to the Lotus Connector forSybase . . . . . . . . . . . . . . . . . . . .

18311 Lotus Connector for Sybase .

182Lotus Connector for OLE DB Properties . . .182Create . . . . . . . . . . . . . . . . . . . . . .182Insert/Update . . . . . . . . . . . . . . . . .181Fetch . . . . . . . . . . . . . . . . . . . . . . .181Execute . . . . . . . . . . . . . . . . . . . . .180Microsoft Access 2000 Data Types . . . . . .180Create . . . . . . . . . . . . . . . . . . . . . .179Insert/Update . . . . . . . . . . . . . . . . .178Fetch . . . . . . . . . . . . . . . . . . . . . . .177Execute . . . . . . . . . . . . . . . . . . . . .176Microsoft SQL Server Data Types . . . . . .175

Using Stored Procedures to ApproximateOutput Parameters . . . . . . . . . . . .

171Stored Procedure Example . . . . . . . . .170Calling MS SQL Server Stored Procedures .169

Lotus Connector for OLE DB OperationalConsiderations . . . . . . . . . . . . . .

iv Lotus Connectors and Connectivity Guide

234Connectivity to a Collapse/Expand

Metaconnection . . . . . . . . . . . . . .

233Collapse/Expand Metaconnector . . . . . . .232Common Features . . . . . . . . . . . . . . .231Introduction to Metaconnectors . . . . . . . .23113 Lotus Metaconnectors for LEI

229Lotus Connector for Text Properties . . . . .228Create . . . . . . . . . . . . . . . . . . . . . .228Insert . . . . . . . . . . . . . . . . . . . . . . .227Fetch . . . . . . . . . . . . . . . . . . . . . . .227Execute . . . . . . . . . . . . . . . . . . . . .226Lotus Connector for Text Data Types . . . .219Fields in the LEI Connection Document .218Common Features . . . . . . . . . . . . . . .217Text Connection Document for LEI . . . . . .209Using Field Options . . . . . . . . . . . . .208Defining Target Files . . . . . . . . . . . . .207

Binary Input Files Using Fixed LengthRecords . . . . . . . . . . . . . . . . . . .

205Text Input Files Using Multiple Lines per

Record . . . . . . . . . . . . . . . . . . . .

203Defining Source Files . . . . . . . . . . . . .202For Target Connection Access . . . . . . .201For Source Connection Access . . . . . . .201

Field Options and Text Information Defini-tion Syntax . . . . . . . . . . . . . . . . .

200Supported Characteristics . . . . . . . . . .200Terminology . . . . . . . . . . . . . . . . . .199Supported LEI Activities Considerations

199Introduction to the Lotus Connector for Text

19912 Lotus Connector for Text . . . .

197Lotus Connector for Sybase Properties . . .197Create . . . . . . . . . . . . . . . . . . . . . .196Insert/Update . . . . . . . . . . . . . . . . .195Fetch . . . . . . . . . . . . . . . . . . . . . . .

245Index . . . . . . . . . . . . . . . . . . . . . . . .

243Trace Metaconnector Properties . . . . . .242Trace Metaconnection Document . . . . .242Activity Log File . . . . . . . . . . . . . . . .242Trace Metaconnector . . . . . . . . . . . . . . .241Order Metaconnector Data Types . . . . .241

Using the Order Metaconnector with aReplication Activity . . . . . . . . . . . .

241Order Metaconnector Properties . . . . .240Order Metaconnection Document . . . . . . .240Connectivity to an Order Metaconnection

239Order Metaconnector . . . . . . . . . . . . . .239Meter Metaconnector Data Types . . . . .238Supported Characteristics . . . . . . . . . .237Meter Metaconnector Properties . . . . . .236Meter Metaconnection Document . . . . .236Connectivity to a Meter Metaconnection

236Meter Metaconnector . . . . . . . . . . . . . . .236

Collapse/Expand Metaconnector DataTypes . . . . . . . . . . . . . . . . . . . . .

235Using the Collapse/Expand Metaconnec-

tor with a Replication Activity . . . . .

234Collapse/Expand Metaconnection

Document . . . . . . . . . . . . . . . . . .

Contents v

This page intentionally left blank.

Preface

This document provides information about the Lotus Connectors suppliedwith IBM Lotus Enterprise Integrator for Domino (LEI) and DominoEnterprise Connection Services (DECS). These Connectors can be used withLEI, DECS, Lotus Connector LotusScript Extensions (LC LSX), and LotusEnterprise Solution Builder for Domino (ESB).

Note The LC LSX is supplied with the Domino Server and Designer, NotesClient, LEI, and DECS.

This manual also provides information about setting up and using LotusConnectors, including information about required software and instructionsfor testing connectivity.

This manual is a core component of both the LEI and DECS userdocumentation set.

The following information is presented:

• Description of each Connector supplied with LEI and DECS, includingproperties and values on each Connection Document

• Software requirements for connecting to external data sources andaccessing the data in those external sources

• Supplied connectivity testing programs DCTEST and CONTEST

Organization of this ManualThis manual contains the following chapters.

continued

This chapter describes connectivityconsiderations for each of the suppliedConnectors.

Chapter 2Connectivity

This chapter provides information andinstructions for running the connectivity testprograms DCTEST and CONTEST.

Chapter 1DCTEST and CONTEST

The preface provides information about theorganization of this manual, relateddocumentation, and Lotus support.

Preface

DescriptionChapter

vii

This chapter provides information about theLotus Metaconnectors for LEI.

Chapter 13Lotus Metaconnectors for LEI

This chapter provides information about theLotus Connector for Text.

Chapter 12Lotus Connector for Text

This chapter provides information about theLotus Connector for Sybase.

Chapter 11Lotus Connector for Sybase

This chapter provides information about theLotus Connector for OLE DB.

Chapter 10Lotus Connector for OLE DB

This chapter provides information about theLotus Connector for Oracle 8.

Chapter 9Lotus Connector for Oracle 8

This chapter provides information about theLotus Connector for Oracle 7.


This chapter provides information about theLotus Connector for ODBC.

Chapter 7Lotus Connector for ODBC

This chapter provides information about theLotus Connector for File System.

Chapter 6Lotus Connector for File System

This chapter provides information about theLotus Connector for DB2.

Chapter 5Lotus Connector for DB2

This chapter provides information about theLotus Connector for Notes.

Chapter 4Lotus Connector for Notes

This chapter provides introductoryinformation about each of the supplied LotusConnectors.

Chapter 3Introduction to Lotus Connectors

DescriptionChapter

Related DocumentationThis section lists documentation that you may find useful as you learnabout and use the various Lotus Connectors.

Note Two of the four LEI user documentation files (Lotus Connectors andConnectivity Guide - lccon6.nsf and Lotus Connector LotusScript ExtensionsGuide - lsxlc6.nsf) are also part of the DECS documentation set and are nowsupplied with Domino only, not LEI. To obtain these two neededdocumentation databases, you must either install DECS or perform acustom install of the Domino server and select the DECS User Assistanceoption. These two files are also available at http://www.notes.net. TheirPDF equivalents are available only at http://www.notes.net.

viii Lotus Connectors and Connectivity Guide

LEI DocumentationDocumentation for LEI is available online with the product distribution andat http://www.notes.net. The LEI documentation set is listed below:

• IBM Lotus Enterprise Integrator for Domino (LEI) Activities and User Guide-- Provides information and instructions for using LEI and its Activities(leidoc.nsf and leidoc.pdf).

• IBM Lotus Enterprise Integrator for Domino (LEI) Installation Guide --Provides installation, configuration, and migration instructions for LEI(leiig.nsf and leiig.pdf).

• Lotus Connectors and Connectivity Guide -- Provides information on howto set up and use the supplied Lotus Connectors, including informationabout required software and instructions for testing connectivity(lccon6.nsf). This documentation file is installed with Domino, not LEI.The lccon6.pdf file is available for download at http://www.notes.net.

• Lotus Connector LotusScript Extensions Guide -- Describes the LotusConnector LotusScript Extensions, which can be used in writingscripted sessions for accessing enterprise data (lsxlc6.nsf). Thisdocumentation file is installed with Domino, not LEI. The lsxlc6.pdf fileis available for download at http://www.notes.net.

• IBM Lotus Enterprise Integrator for Domino (LEI) Release Notes -- Therelease notes (readme.txt) contain information about the current releaseof LEI that may not be included in the documentation set.

Current information about LEI can also be found at the following Web site:

http://www.lotus.com/

DECS DocumentationDocumentation for DECS is available online with the product distributionand at http://www.notes.net. It is comprised of three separate manuals asfollows:

• Domino Enterprise Connection Services User's Guide -- Providesinformation and instructions for using DECS (decsdoc6.nsf).

• Lotus Connectors and Connectivity Guide -- Provides information on howto set up and use the supplied Lotus Connectors, including informationabout required software and instructions for testing connectivity(lccon6.nsf). This documentation file is installed with Domino, not LEI.The lccon6.pdf file is available for download at http://www.notes.net.

• Lotus Connector LotusScript Extensions Guide -- Describes the LotusConnector LotusScript Extensions, which can be used in writingscripted sessions for accessing enterprise data (lsxlc6.nsf). Thisdocumentation file is installed with Domino, not LEI. The lsxlc6.pdf fileis available for download at http://www.notes.net.

Preface ix

• Domino Enterprise Connection Services (DECS) Release Notes -- The releasenotes for DECS are contained in the same database as the DominoRelease notes. See Domino documentation for more information.

Current information about DECS can be found at the following Web site:

http://www.lotus.com/ei

Other DocumentationFor more information about related tools, refer to the following documents:

�� Domino Administrator’s Guide -- Provides information for configuringand administering a Domino installation.

�� LotusScript Language Reference -- Provides information about writingLotusScript programs. This is useful when using the LSX to writecustomized Activities.

�� Additional Domino Connector Documentation -- Lotus Software, IBMSoftware Group sells additional Lotus connectors for enterprise systemsincluding Enterprise Resource Planning (ERP) and TransactionProcessing Systems. Specific documentation about these connectors isincluded with the connector software and package. You may needdocumentation for the specific databases, ERP, and transactionprocessing systems that you are using.

• The DB2 product editions are supplied with a library of onlinedocumentation. This contains excellent information, especiallyintroductory, general terms, and error messaging descriptions. Thereare also many DB2 books available for download from IBM. The QuickBeginnings books are suggested reading for new users. For moreinformation about DB2, see the following Web site: http://www.ibm.com/software/data/db2/library

x Lotus Connectors and Connectivity Guide

Contact and Support InformationLotus Software, IBM Software Group provides extensive support for itsproducts.

Enterprise Integrator Web SiteTo obtain the latest information about LEI and DECS, visit the followingWeb site:

http://www.lotus.com/ei

Note Domino-related product updates for iSeries can be found atfollowing Web site: http://www-1.ibm.com/servers/eserver/iseries/domino/support/qmu.htm

Technical SupportTo contact Customer Support with suggestions or questions regarding yourLotus Connector or LEI/DECS application, call 1-800-346-6388.

Preface xi

Chapter 1DCTEST and CONTEST

This chapter provides information about DCTEST and CONTEST. Theseprograms test system and application connectivity to external data sources.

OverviewAfter installing LEI or DECS, you should test your external system clientconnectivity using DCTEST. Once you have confirmed that your externalsystem client connectivity is operational, you can begin the process ofcreating LEI or DECS Activities and Connections. However, before youexecute an LEI Activity that uses one or more of these connections, youshould test your connections using CONTEST. CONTEST tests that aspecific Lotus connection can actually access the external system. Forexample, when you create a named connection using an LEI ConnectionDocument, run CONTEST on that connection name before running anyActivity that uses it.

LEI and DECS are supplied with connectivity testing software. Both LEIand DECS supply the DCTEST utility, while LEI also supplies theCONTEST utility.

DCTEST is a client-specific test program. It tests system connectivity toexternal data sources. For example, you could use DCTEST to testconnectivity between your DB2 client and your DB2 server. CONTEST is aconnector testing program, for use with LEI only, that tests specific LEIconnections.

1

Supported Data SourcesDCTEST and CONTEST test system connectivity to the following supporteddata sources:

• DB2

• ODBC

• Oracle 7

• Oracle 8

• OLE DB

• Sybase

Testing Connectivity to External Data Sources with DCTESTDCTEST is a connectivity test that establishes whether the client data sourceaccess libraries are available and functional on the Domino server. DCTESTensures that the communications and client software required to access aspecific data source is available and properly configured. It does not test forspecific product functionality.

Before running DCTEST, you must install the appropriate external systemclient connectivity software (for example DB2, Sybase, and so on) onto theDomino server that hosts the LEI server and that also hosts the LEIAdministrator. If your LEI server and Domino server are on two differentmachines, you must install the external system client connectivity softwareonto both of those machines. You do not need to install the external systemclient connectivity software onto your Notes client.

On the iSeries, the appropriate connectivity software is automaticallyinstalled with LEI.

Use DCTEST to test that your external system client connectivity software isoperational. Once you have determined that it is working properly, useCONTEST (LEI only) to test specific Lotus connections prior to running LEIActivities that use them.

Note LEI uses server-side browsing, not client-side browsing from the LEIAdministrator. DECS uses server-side browsing, not client-side browsingfrom the DECS Administrator. Both LEI and DECS browse databases on theexternal system using client connectivity from the Domino server that hoststhe LEI or DECS Administrator, not from the Notes client.

2 Lotus Connectors and Connectivity Guide

SyntaxThe syntax for using DCTEST is as follows:

[n]dctest

Running DCTESTFollow the steps below to run DCTEST.

1. Locate the DCTEST program specific to your operating system platformin the Domino program directory. The DCTEST program has thefollowing names for each of the associated operating system platforms:

• Windows (Win32) platforms — ndctest.exe

• UNIX platforms — dctest

• iSeries platform — call Qnotes/dctest

Note When working with a case-sensitive OS such as UNIX, enter theDCTEST program name using lowercase characters.

Note When you use DCTEST on a UNIX or Linux platform, be surethat the shared library path points to the directory where the DCTESTutility resides. If you use the current directory as the shared librarypath, you will not be able to use DCTEST. Once you have completedyour test with DCTEST, revert to the original shared library pathsetting.

2. Invoke the dctest program. The DCTEST screen appears, as shownbelow.

Chapter 1: DCTEST and CONTEST 3

3. Enter the number of the test you want to run and press Enter.

4. Depending on the type of external system you are testing, for exampleDB2, you are prompted to enter additional information as required tolog in to the specified data source. After entering the external systemdatabase, user name, and password, the program attempts to connect tothe external system server.

For more information, refer to the chapter in this manual that discussesthe specific external system for which you want to test connectivity.

5. A message appears indicating whether the test was successful or not.

6. You can retry a connection by entering “Y” at theTry Again? [N]prompt. This provides the opportunity to reenter the requiredinformation.

Note Testing an ODBC connection with DCTEST can provide you withinformation regarding the minimum version and conformance levelrequired of ODBC drivers so that they work with LEI or DECS. To obtainthis information you must respond “Y” when DCTEST prompts you for afull report.

Testing LEI Connections with CONTESTCONTEST attempts to connect using LEI connections defined in the LEIAdministrator. It tests the ability to make a connection using theinformation found in the LEI Connection Document. CONTEST must berun with an active LEI server.

SyntaxThe syntax for using CONTEST is as follows:

[n]contest [Options] <connection1><connection2>...<connectionn>

[Options]

n denotes the optional parameter: -p. This parameter displays the connectorproperties.

... denotes actual connection names (use quotation marks if spaces exist inthe connection names).

Typing [n]contest with no input parameters results in Help informationbeing displayed.


Running CONTESTFollow the steps below to run CONTEST.

1. Open a Command Prompt/DOS window or a UNIX shell.

2. Locate the CONTEST program specific to your operating system in theDomino program directory. The CONTEST program has the followingnames for each of the associated operating system platforms:

• Windows (Win32) platforms — ncontest.exe

• UNIX platforms — contest

• iSeries platform — call Qnotes/contest

Note Because UNIX is case sensitive, be sure to enter the CONTESTprogram name using lower-case characters.

3. At the command line, type the command appropriate to your platformand press Enter.

Note CONTEST runs in a command window.

Note Information about the connection displays when you use theoptional parameter -p. When you enter [n]contest without the parameter,only information about the successfulness of making the connectiondisplays.

ExamplesExample 1 (Windows platform):

C:\Lotus\Domino>ncontest "NotesDb on MyOracle"

Sample Output:

Testing NotesDb on MyOracle

NotesDb on MyOracle Connect Successful

Example 2 (UNIX Platform):

C:lotus/domino>contest "Oracle on MyOracle" "Sybase 11 onMySQLServer"

Sample Output:

Testing Oracle on MyOracle

Oracle on MyOracle Connect Successful

Testing Sybase 11 on MySQLServer

Sybase 11 on MySQLServer Connect Successful

Chapter 1: DCTEST and CONTEST 5

Chapter 2Connectivity

This chapter provides instructions and information for setting up andtesting connectivity to the following database systems:

• DB2

• Notes

• ODBC

• Oracle 7

• Oracle 8

• OLE DB

• Sybase

Client libraries of the external systems to be accessed must be installed onthe LEI server and the Domino server. When running activities, if the LEIserver that you want the activity to run on and the Domino server wherethe LEI Administrator resides are on separate machines, the client librariesmust be installed on both machines.

Note Access to other iSeries DB2/400 servers is integrated into OS/400.No additional software installation is required when using the LotusConnector for DB2.

DB2 ConnectivityThis section lists supported platforms and configurations. It also listsspecific LEI activities supported by the Lotus Connector for DB2.

Supported ActivitiesThe Lotus Connector for DB2 supports the following LEI activities:

• Direct Transfer

• Source/destination connections

• Destination metadata creation ("Create Target Metadata")

• Command

• Archive

7

• Advanced RealTime (Virtual Documents and Virtual Agents), VirtualFields, and DECS Real Time

• Create, Open, Update, and Delete events

• Replication

• Master and Target connections

• Scripted

• Polling

• Java

Connectivity to DB2This section provides information about software required to connect toDB2. This information is provided to help you get started. You should referto the documentation for the specific software you are using for completeinstructions.

The following DB2 product editions contain the Administration client andthe Application Development client. These two items provide all theconnectivity software you need for successfully connecting to a DB2database server. The specific edition to use will depend on yourenvironment.

• DB2 Universal Database (UDB) Workgroup Edition

• DB2 Universal Database (UDB) Enterprise Edition

• DB2 Universal Database (UDB) Personal Edition

• DB2 Connect Enterprise Edition

• DB2 Connect Personal Edition

For details about these Editions, see the appropriate DB2 userdocumentation. For the UDB Editions, see the manual entitled Road Map toDB2 Programming, Appendix A, "About DB2 Universal Database."

See also the http://www-3.ibm.com/software/network/commserver forrelated information.

Note Only the administration client is necessary for successfulconnectivity to a DB2 database server.

On Solaris, due to similarities between the ODBC and DB2 applicationprogram interfaces, errors are seen when using concurrent connections toODBC and DB2 in DECS. To avoid these errors, use the ODBC DB2 driverfor DB2 connections rather than the DECS DB2 Connection.


Connectivity to DB2 on iSeriesThis section describes connectivity considerations between DB2 on aWindows workstation and DB2/400. None of the options described requirethe installation of software to the iSeries.

When connecting to a DB2/400 server remotely, you must use DB2 Connectin order to specify OS/400 as the target DB2 database. The UDB Editions donot allow you to specify the target database operating system.

DB2/400 is part of the base operating system on the iSeries and has supportto be both a requester and server of remote DB2 requests. DB2/400 can bethe target of DB2 connection requests from platforms such as NT, AIX, etc.It can also request DB2 connections to other DB2 databases in the network.DB2/400 supports both SNA and TCP/IP connections. See the "Connectingto Remote DB2 from iSeries" section for more details.

Because DB2/400 is part of the base operating system, if you are runningLEI native on the iSeries you do not need to install additional DB2 softwareon the iSeries. All DB2 databases being connected to, including the localDB2/400 database, must be registered in the Relational Database Directory(see WRKRDBDIRE).

You can also connect to DB2 on an iSeries or mainframe using DDCSgateway.

Connecting to a DB2 Data Source on iSeriesAll connections originating from the iSeries to DB2 databases (including thelocal DB2/400), require that the target DB2 database be registered in theRelational Database Directory on the requesting iSeries. Register DB2 datasources using the WRKRDBDIRE CL command. You can register yourremote connections as either *SNA or *IP. If using SNA, communicationconfiguration is required to connect to the remote database as described inthe appropriate iSeries documentation. If using *IP, provide the target IPaddress or remote location name and verify that the target database isactive on the designated port. The default IP port for *DRDA is 446.

If the target database is another DB2/400 using a *IP connection, make surethat the DDM server job on the target iSeries is listening for the connectionrequest. This occurs by entering a STRTCPSVR *DDM command on thetarget iSeries. The command starts the QRWTLSTN job on the iSeries inQSYSWRK subsystem. This job monitors the DRDA port.

Note If you are connecting to a remote DB2/400, the password in theConnection Document should be in uppercase characters.

Direct DB2/400 ConnectivityThis section describes direct DB2/400 connectivity considerations.

Chapter 2: Connectivity 9

One Server Connecting to DB2/400This configuration does not require the installation of software to theiSeries.

You can use an *IP connection. If you are using SNA as your connectionprotocol, bundled with Connect Personal Edition is an SNA server. Installthe SNA server with the SNA over APPC option. It must be over APPC;iSeries requires APPC for DB2 connectivity when using an SNA connection.Also, in this stand-alone environment, the SNA over APPC is self-sufficient;there is no general network need for APPC and SNA in the network.

Refer to the IBM DB2 Connect Personal Edition Quick Beginnings document(numbered S10J-8162-00) as a means to begin the installation. Use a username and password that exist also on the DB2/400. This will allow theinstallation to perform operations on the iSeries without intervention.

Multiple Servers Connecting to DB2/400This configuration does not require any software installed to the iSeries.

This will install a gateway to DB2/400. A gateway allows access to theDB2/400 data from multiple servers. This software is only necessary if youplan to have more than one server.

You can use an *IP connection. If using SNA as your connection protocol,the Connect Enterprise Edition does not come with bundled SNA software.You must install an SNA server, such as the Microsoft SNA server.

If the DB2 Connect Enterprise Edition is not installed on the machine, then aDB2 client such as DB2 Administration Client needs to be installed on themachine. This client is needed to perform the direct connection from theDomino server to DB2.

Server Connecting to DB2/400 with DDCSA Distributed Database Connection Services (DDCS) and SNA server arerequired.

This configuration does not require the installation of software to theiSeries.

This configuration is for customers with an existing DDCS installation. Thisoption only exists for customers who have DDCS already in house, becauseat this time only the latest DB2 Connect Versions 6.1 and 7.1 software isavailable for purchase.

DDCS Single User or Gateway can be used to connect to DB2/400. WithDDCS, there is also a requirement for an SNA server over APPC. Therefore,you need SNA software such as Microsoft SNA.


If DDCS is not installed on the server machine, a DB2 Client such as DB2Administration Client must be installed on the server machine. This client isneeded to perform the direct connection from the server to DB2/400.

ODBC DB2/400 ConnectivityODBC DB2/400 connectivity is facilitated through the DB2 client. This givesthe server the advantage of straight connectivity, speed, and data typeaccess without the ODBC layer. However, if you install products such asIBM's Client Access for iSeries, then the connectivity is through the ODBClink.

Be certain to verify the requirements of the individual packages; in mostcases an SNA server is still a requirement.

Note This option may require that additional software be installed on theiSeries.

Connection for DB2 CAE and DDCSLEI offers native connectivity to DB2. This provides a direct connection toDB2 on all DB2-supported platforms, and enhances the DB2 connectivitypreviously provided through ODBC. The native interface offersimprovements in speed and support for native data types not accessiblethrough ODBC. This section contains information on configuring nativeDB2 connectivity through Distributed Database Connection Services(DDCS).

Getting StartedNetwork communications programs must be installed to the server and theDB2 system to establish a network connection for data transfer. Dependingon the platform you are using to operate the server, and the operatingsystem used to store DB2, your requirements are either to install theAdministration Client or DDCS. These communications products areavailable from IBM. The Administration Client is also available on yourDB2 Edition CD-ROM. The machines must have connectivity through theAdministration Client or a DB2 run-time environment such as DB2 server.

For DDCS for Windows NT to access DRDA Application servers such asDB2 for MVS/ESA, the APPC protocol support must also be installed onyour system. The program required to do this is Microsoft SNA serverVersion 2.11 or later.

Before attempting to connect, verify connectivity through the DB2command line program (supplied with DB2) or the DCTEST connectivitytest program.


Sample Steps for DB2 Administration Client Configuration on NTThe following illustrates some sample steps you may wish to follow whenconfiguring your DB2 connectivity using the Administration Client on NT.For full details, refer to the DB2 manual Install/Use DB2 Clients for xxxwhere xxx is your operating system. The steps below assume you areinstalling the administration client for the server machine running onWindows NT and using TCP/IP.

1. Install the DB2 Administration Client software.

2. Using the DB2 Client Configuration Assistant, follow the steps toconfigure your client for connectivity to a DB2 server.

3. Verify connectivity to DB2 from Domino by running the ndctest.exeprogram found in the Domino program directory. This program willprompt you for the database name or database alias, userid, andpassword.

Sample Steps for DB2 Administration Client Configuration on UNIXThe following illustrates some sample steps you may wish to follow whenconfiguring your DB2 connectivity using the Administration Client onUNIX. For full details, refer to the DB2 manual Install/Use DB2 Clients forxxx where xxx is your UNIX operating system. The steps below assume youare installing the Administration Client for the server machine running onUNIX and using TCP/IP.

1. Install the DB2 Administration Client software.

2. Ensure the server machine can resolve the DB2 server TCP/IP hostaddress. For example, you should be able to ping the server. If it can't,either update the Domain Name server to include the DB2 server nameand address or add an entry to your server machine's /etc/hosts file.

3. Ensure the DB2 server has enabled the TCP/IP protocol through theDB2COMM environment variable. This variable may indicate multipleprotocols. Make certain it includes TCPIP. This variable must be set atthe time the DB2 server is started.

4. Ensure the services file on the DB2 server machine contains an entry forTCP/IP support for each database manager instance you plan onaccessing. db2inst1c 3700/tcp

# DB2 connection service port

db2inst1i 3701/tcp

# DB2 interrupt connection service port


In this example, db2inst1c is the value of the service_name parameterand db2inst1i is arbitrary. 3700 and 3701 are the port numbers for theconnection and interrupt port, and TCP is the protocol. The portnumber 3700 is arbitrary, but must be unique within the file. Thesecond port number must also be unique and be equal to the firstnumber plus one. These same numbers must be used when configuringthe services file on the server machine.

5. On the server machine, catalog the DB2 server and database. To catalogthe server, use the DB2 command line processor on the server machineand enter the command: CATALOG TCPIP NODE nodename REMOTE hostname SERVERservicename

In this example, nodename is a name you use to refer to thisconnection, hostname is the TCP/IP name of the DB2 server machine,and servicename is the instance name you entered in the services file(you only need to do this once using the first port even if you alsoentered an interrupt connection service port in the services file).

6. Catalog the database using the following command: CATALOG DATABASE databasename AS local_database_alias ATNODE nodename

In this example, databasename is the name of the database on the DB2server, local_database_alias is a name you choose when you wish toconnect to the database from the server machine, and nodename is thename you used in the previous CATALOG TCP/IP command.

7. Exit and restart the DB2 command line processor. Connect to the DB2database with the following command: CONNECT TO local_database_alias USER username USINGpassword

In this example, local_database_alias is the alias you cataloged andusername is a valid DB2 user name.

8. Verify connectivity to DB2 by running the DCTEST program found inthe Domino program directory. This program will prompt you for thedatabase name or database alias, userid, and password.

When to Use IBM Distributed Database Connection Services (DDCS)DDCS has been replaced by DB2 Connect Personal Edition and DB2Connect Enterprise Edition.

The following information is provided for environments which may not yethave acquired these connectivity packages.


When connecting to DB2 for MVS/ESA, DB2 for VSE and VM(SQL/DS), orDB2 for OS/400, you can use DDCS. DDCS can also be used to connect toany other DB2 server but it is more direct and efficient to connect from thelocal machine using the Administration Client directly to the DB2 server.

It does not matter where DDCS is installed as long as the Domino servermachine can connect to the DDCS machine through TCP/IP, SPX, or anyother DB2-supported protocol.

Refer to the DDCS Install/Configuration document for instructions andsoftware requirements. Connections to external systems may requireadditional communications software.

Sample Steps for Using DDCSThis example illustrates how DDCS works with the server. For thisexample, assume the following parameters:

• The server is running on a Windows NT machine named NP1.

• The NP1 machine has the DB2 Administration Client for Windows NTinstalled and will connect to the DDCS workstation using TCP/IP.

• DDCS is installed on an AIX machine named DB2GW. It has TCP/IPand the IBM Communications Server installed.

• Connectivity to a DB2 database on the MVS machine MVS1 is desiredand will be made through APPC.

1. The connectivity between DB2GW and MVS1 must be establishedthough DB2GWs IBM Communications Server and MVS1's VTAM. Thedetails of this configuration and configuration at the MVS host are notcovered here; refer to the DDCS Install/Configuration manual forinformation.

2. MVS1s node and database is cataloged at the DDCS machine. Thefollowing commands are issued to catalog the remote node anddatabase: CATALOG APPC NODE db2node REMOTE db2pic SECURITY PROGRAM

In this example, db2node is a name you pick to refer to this host, db2picis the Symbolic Destination Name you defined when you configuredMVS1 in the IBM Communications Server.CATALOG DATABASE db2db AS mydb AT NODE db2nodeAUTHENTICATION DCS

In this example, db2db is the MVS database name, mydb is thedatabase alias, and db2node is the node defined in the previouscommand.


3. The services file on the DDCS machine (DB2GW) is modified to includean entry for a database instance (inst1c) and an interrupt connection(inst1i). The following DB2 command must be used. It tells the databasemanager to listen for connections to the instance from remote clients tothe instance.UPDATE DATABASE MANAGER CONFIGURATION USING SVCENAMEinst1c

4. The environment variable DB2COMM is set to TCPIP. DDCS is startedwith the operating system command DB2START.

5. Connectivity from NP1 is established through the DB2 AdministrationClient by defining the target database:CATALOG TCPIP NODE gw1 REMOTE db2gw SERVER inst1c

CATALOG DATABASE mydb AS mvsdb2 AT NODE gw1

In this example, gw1 is the alias that will refer to the DDCS gatewayand will be used by the server, db2gw is the TCP/IP name of the DDCSGateway machine, and inst1c is the service name defined in step 3above. The mydb alias is defined in step 2 above; mvsdb2 is the aliasthat will be used by LEI.

DB2 Connectivity TestTo test for connectivity to DB2, complete the following steps:

1. Run the test program DCTEST, located in the Domino programdirectory, appropriate to your operating system.

2. Select DB2 from the program menu.

3. Enter the data source, user name, and password when the programprompts for them.

4. Choose (Y/N) whether or not you want detailed driver information.

5. You can produce a printed report for diagnostic purposes. When asked,you can choose to output to a file (Y) or not (N). If you do not chooseoutput to a file, the results appear on your monitor.

6. If you chose file output, supply a name for the file, then press Enter.The program then attempts to connect to the DB2 data source.

7. You can retry a connection by entering "Y" when prompted for anotherdata source.


ODBC ConnectivityThis section provides information about setting up connectivity to an ODBCdata source.

Requirements for ODBC ConnectivityConnectivity software requirements depend on the operating systemplatform and the ODBC version you are using. You must have:

• The ODBC driver appropriate to the operating system. Lotusrecommends DataDirect ODBC version 3.5.

• The driver must be 32-bit on Windows NT.

• The ODBC driver must be thread-safe.

• The ODBC Administrator must be present.

• The ODBC Administrator must contain correctly defined andconfigured ODBC data sources.

• All client software required to connect to the ODBC data sources mustbe installed and configured correctly.

ODBC Connectivity TestTo test for connectivity to ODBC, complete the following steps:


2. Select ODBC from the program menu.

3. Enter the data source, user name, and password when the programprompts for them.

4. Choose (Y/N) whether or not you want detailed driver information.

Note Testing an ODBC connection with DCTEST can provide youwith information regarding the minimum version and conformancelevel required of ODBC drivers so that they work with LEI, however, toget this information you must respond with Yes (Y) when DCTESTprompts you for this information.

5. You can produce a printed report for diagnostic purposes. When asked,you can choose to output to a file (Y) or not (N). If you do not chooseoutput to a file, the results appear on your monitor.

6. If you chose file output, supply a name for the file, then press Enter.The program then attempts to connect to the ODBC data source.

7. You can retry a connection by entering "Y" when prompted for anotherdata source.


Oracle 7 ConnectivityThis section provides information about setting up connectivity to an Oracle7 server.

Requirements for Oracle 7 ConnectivityConnectivity software requirements depend on the operating systemplatform and the Oracle 7 version you are using. You must have thefollowing:

• With a Windows NT-based server: Oracle 7 SQL*Net version 1 or 2.

• SQL*Net must be the same version as the SQL*Net installed on theOracle 7 data server. A network connection must exist between theserver machine and the Oracle 7 data server machine using SQL*Net.

• Native Oracle 7 connectivity support requires Oracle version 7.2 orlater.

• LEI links with Oracle 7.2 libraries, which use SQL*Net for thecommunications layer. If you are using Oracle 7 with LEI, you mustinstall Oracle 7 SQL*Net. You can use SQLNet Easy Config utility toconfigure SQL*Net.

Oracle 7 Connectivity TestTo test for connectivity to an Oracle 7 server, complete the following steps:


2. Select Oracle 7 server from the program menu.

3. When the program prompts for an Oracle 7 user name, password, andconnection string, enter a valid user name, password, and connectionstring.

• The connection string can be for either SQL*Net V1 or SQL*Net V2,depending on what software you have configured on your Oracle 7server and Domino server.

• The general format for a V1 string isnetwork_prefix:server_name:sid.

• The format for V2 consists of a single identifier, service_name.

• Refer to your Oracle 7 SQL*Net documentation for furtherinformation on the format of connection strings.

4. After entering a user name, password, and connection string, theprogram attempts to connect to the Oracle 7 server.


A message appears telling whether the test was successful or not. Youcan retry a connection by entering "Y" at the Try Again? [N] prompt.This provides the opportunity to reenter all of the required information,for example if you misspelled an entry or entered the wrong user name,password, or connection string.

Oracle 8 ConnectivityThis section provides information about setting up connectivity to an Oracle8 server.

Requirements for Oracle 8 ConnectivityConnectivity software requirements depend on the operating systemplatform and the Oracle 8 version you are using. You must have Oracleclient version 8.0.5 or 8i.

Oracle connectivity on Solaris relies on the Oracle 8i client library found inORACLE_HOME/lib. If you are using LEI and a pre-8i version of theOracle client, you must create a symbolic link in ORACLE_HOME/libusing the command "ln -s libclntsh.so.1.0 libclntsh.so.8.0'".

Note For best result, Lotus Software recommends matching your Oracleclient and server versions.

Oracle 8 Connectivity TestTo test for connectivity to an Oracle 8 server, complete the following steps.


2. Select Oracle 8 server from the program menu.

3. When the program prompts for an Oracle 8 user name, password, andservice name, enter a valid user name, password, and service name.

4. After entering a user name, password, and service name, the programattempts to connect to the Oracle 8 server.

A message appears telling whether the test was successful or not. Youcan retry a connection by entering "Y" at the Try Again? [N] prompt.This provides the opportunity to reenter all of the required information,for example if you misspelled an entry or entered the wrong user name,password or service name.


OLE DB ConnectivityThis section provides information about setting up connectivity to an OLEDB data source.

Requirements for OLE DB ConnectivityConnectivity software requirements depend on the operating systemplatform and the OLE DB version that you are using.

• Microsoft Data Access Components (MDAC) 2.0 or higher is required.MDAC 2.5 is recommended; the latest version is available for downloadfrom <http://www.microsoft.com/data>. MDAC 2.5 can be installedon Windows NT 4.0 and is included in Windows 2000.

• OLE DB supports connectivity to Microsoft SQL Server 7, SQL Server2000, and Microsoft Access 2000. SQLOLEDB, the Microsoft SQLServer OLE DB provider, is currently the only supported OLE DBprovider.

• The preferred Net-Library can be set by the SQL Server Client NetworkUtility. Alternatively, the Net-Library can be specified in the ProviderString when making a connection.

OLE DB Connectivity TestTo test for connectivity to OLE DB, complete the following steps:


2. Select OLE DB from the program menu.

3. Enter the provider name, data source, provider string, authenticationservice, user name and password as prompted.

The following is an example of the information that is returned when youhave a successful connection.


Sybase Connectivity This section provides information about setting up connectivity to a Sybaseserver.

Requirements for Sybase ConnectivityConnectivity software requirements depend on the operating systemplatform that you are using.

Sybase Adaptive Server 11.1.1Solaris and AIX

Sybase Adaptive Server 11.9.2Windows NT

Sybase VersionOperating System

A network connection between the Domino server and the Sybase SQLserver is required.

Note When DB2 and Sybase clients are installed on the same machine, theDB2 environment variable LC_ALL will adversely effect Sybaseconnectivity. To correct this problem, delete the environment variable.


Sybase Connectivity TestTo test for connectivity to a Sybase SQL server, complete the followingsteps:


2. Select Sybase from the program menu.

3. Enter the server name, user name, and password as prompted. The testprogram then attempts to connect to the Sybase Adaptive Servermachine.

4. A message appears telling whether the test was successful or not. Youcan retry a connection by entering "Y" at Try Again? [N]. This providesthe opportunity to reenter all of the required information, in case amistake was made in spelling or you gave the wrong user name,password or server name.

5. If problems persist, check to make sure that the client software isproperly installed.


Chapter 3Introduction to Lotus Connectors

This chapter provides introductory information about each of the suppliedLotus Connectors.

Connectors OverviewA connection is a document that defines how a Lotus Connector willinteract with a specific data source. The connection provides specific accessparameters, such as server names, user IDs and passwords. The“connected” databases are the databases that LEI or DECS can access.Because the forms used with each connection type are different, eachConnection Document is described separately.

Before creating connections, you should verify that the LEI server (orDomino server if you are using DECS) can communicate with your systemdatabases. Do this by running the data source-specific tests describedearlier in this manual or in the specific manual for the Lotus Connector thatyou intend to use.

After creating your connections, you should test them using the suppliedutilities described in the “DCTEST and CONTEST” chapter in this manual.

Connectors and Supported Data SourcesLEI and DECS provides the following standard Lotus Connectors for theassociated data sources:

• DB2

• Notes

• File System (not used with Virtual Documents or Virtual Agents Activities)

• ODBC

• Oracle 7

• Oracle 8

• OLE DB

• Sybase

• Text (not used with Advanced RealTime or DECS Activities)

23

Additional Lotus Connectors are available and can be purchasedseparately.

Client libraries of the external systems to be accessed must be installed onthe LEI server and the Domino server. When running activities, if the LEIserver that you want the activity to run on and the Domino server wherethe LEI Administrator resides are on separate machines, the client librariesmust be installed on both machines.

For more information about Lotus Connectors, visithttp://www.lotus.com/ei.

Using Multiple Connections of the Same TypeYou can use multiple connections for the same types of databases as well asfor the same databases.

You can create multiple connections to the same database by making copiesof a connection definition and then renaming the copies. You might do thisis to access the same database but to set various permission levels forspecific tables or to use a different username and password.

Any number of Activities can use the same connection.

Some connections are not supported by certain Activities. See the sectionentitled “Connections and Supported Activities” later in this chapter formore information.

LEI and Metaconnections: Specialized Intermediate ConnectionsMetaconnections are specialized connections that perform an intermediaryrole in LEI when used with an Activity. Metaconnections enable specificactions to be performed on data.

Supported Metaconnections include the following:

• Collapse/Expand

• Metering

• Order

• Trace

Note Metaconnections are not used with LEI Advanced RealTime orDECS. The Metaconnection functionality is transparently integrated intoLEI Advanced RealTime and DECS Activities.

Once a Metaconnector is created, the Metaconnection Document can befound in the Connections views.

You can use LEI browsing functionality within a Metaconnector. However,you must first select a metadata object (table, form, view, and/or


procedure) in every base Connector that is used with the Metaconnector. Ifbase Connectors referenced by the Metaconnector do not have metadataselected, a message appears at which time you can return to the baseconnector, select metadata, and then rebuild the Metaconnection Document.This is a requirement only if you intend to browse the Metaconnectors.

Processing RTF Fields Between Notes and RDBMSNotes is primarily a document management system, not a relationaldatabase management system (RDBMS). Because of this, Notes performsspecial handling for attachments stored in rich text fields.

Notes rich text fields are stored in a proprietary binary format. For example,Notes rich text data written to Oracle fields will result in the Oracle fieldscontaining data in that proprietary format. Non-Notes applications will beunable to process this data. Notes rich text data is not the same as Rich TextFormat data used for word processing documents.

In order to use BLOBs or RAWs, they must first originate in Notes, beinserted into the Oracle table, and then be read back into Notes. Otherwise,the BLOB or RAW data will not be in a format that Notes can recognize.This is also true for LEI and DECS when a Notes database is one of theconnected databases.

For all non-Notes Connectors, if you move data into a Notes rich text fieldand then read it as type binary, that binary data will then be in Notes richtext format.

Using a Notes Database as the Source Binary data transferred from a Notes source will act as shown in thefollowing tables.

will be stored as Textas text

will be stored in Notes Rich Text formatas binary

Notes DestinationBinary Data



Non-Notes DestinationBinary Data


Notes DestinationNon-binary Data


Non-Notes DestinationNon-binary Data

Chapter 3: Introduction to Lotus Connectors 25

Using a Non-Notes Database as the SourceBinary data transferred from a non-Notes source will act as shown in thefollowing tables.


will be stored as Notes Rich Text format (but source may or maynot be Notes Rich Text)

as binary

Notes DestinationBinary Data

will be stored as binary (in its original format)as binary

Non-Notes DestinationBinary Data


Notes DestinationNon-binary Data

will be stored as binary (in its original format)as binary

Non-Notes DestinationNon-binary Data

Transferring AttachmentsLotus Notes stores attachment data separately from rich text field data.Currently you can only transfer attachments from Notes to Notes; rich textfields with attachments do not store correctly in the target RDBMS such asDB2 and Oracle.

To work around this constraint, you can use the Extract File Attachmentsoption in the Lotus Connector for Notes to save attachments to files on disk.You can then use LotusScript to read the files, store their contents inLCFields, and save the LCFields to binary fields in a RDBMS. This level ofscripting requires LotusScript expertise.

Processing Empty and NULL Values in LEI and DECSIn DECS and in LEI, empty data in a Notes rich text or Text field is not setto NULL when it is transferred. It is transferred as “”. To set empty data toNULL requires that you write a LotusScript routine or a stored procedure.

For LEI (but not for Advanced RealTime or DECS) NULL is not equivalentto an empty string or to an empty value such as zero. LEI regards a NULLas an undefined value, one that cannot be compared to other values. This istrue for all LEI activities (except Advanced RealTime Activities), however,Replication is most sensitive to this issue. LEI Replication occurs wheneverLEI performs a comparison between Database A and Database B andencounters mismatches in the comparison fields. For example, a replicationwill occur if LEI finds a NULL in one database matching a correspondingempty value in another. This can occur frequently with date specifications;


for example, if Database A specifies a date and Database B has no dataspecification. When this occurs, LEI uses SQL syntax to convert NULLS tovalues that are equivalent across databases.

Supported Connector Characteristics - List of TermsThe following table defines the terms used in the “SupportedCharacteristics” section of each Connector chapter in this manual.

Refers to the Object types that this Connector can drop fromthe external system.

Drop types

Refers to the Object types that this Connector can create inthe external system.

Create types

Refers to the Catalog types that this Connector supports forbrowsing-type operations.

Catalog types

Refers to the Actions that this Connector is capable ofsupporting.

Actions supported

Refers to the capability of this Connector to transfer manyrecords at once. The benefit of transferring many records atonce is that only one network transaction is needed, ratherthan many, for a given set of records — the data has thesame number of bytes, but the transfer takes less time.Array transfers can be used for read or write operations,depending on the RDBMS and the Connector.

Array transfer

Refers to the type and format of the condition statementsthat this Connector accepts.

Condition syntax

Refers to the statement type and format that this Connectoraccepts.

Statement syntax

Indicates the database index, if any, required to enablewriteback support for a given metadata object. For example,some Connectors require that a unique index exist, whileothers do not.

Writeback index

Indicates whether the connection supports writeback resultsets.The term writeback is defined in RDBMS systems as anupdateable cursor, which means that, using the result set,the most recently fetched record can be directly updated ordeleted. A non-writeback update must first search the tableusing keys, however a writeback update can immediatelylocate the record to update. Writeback support saves timeand is therefore more efficient.

Writeback support

DefinitionTerm


Connection DocumentsA Lotus Connection Document enables you to define connections toexternal data sources. Connection Documents contain access informationfor specific databases and users. When you create an activity, you makeconnection choices from the existing set of defined connections.

The information required in a Connection Document may be different fordifferent database products, so while the Connection Documents providestandard connection name fields, there are sections and fields specific to theexternal system. Refer to the specific Connector chapters in this manual forinformation about the type of connection you are creating. If you are usinga premium Connector, refer to the documentation provided with theConnector.

The Lotus Connectors use a series of properties. When defining aconnection to LEI or DECS, values for these properties are specified in aConnection Document. When using a Lotus Connector with LSX classes,values for these properties are specified by setting properties of theLCConnection class.

Note that fields which are browseable are not editable. Most ConnectionDocument fields are browseable, enabling easy point and click access.

For more information about the LCConnection class properties, see theLotus Connector LotusScript Extensions Guide.

Note In order to connect to a supported data source, you must have therequired connectivity software for that data source installed on your server.Before attempting to create a Connection Document, you should verify thatall of your external system software is installed and current with allavailable maintenance releases and fix packs.

Connection PoolingFor optimum performance of a Connector, underlying connections to theexternal systems can be pooled. This pooling occurs in the Connector APIand is automatic with subsequent connections. LotusScript provides asimple programmatic interface to connection pooling.

The LCSession class exposes a property called “ConnectionPooling.” Settingthis property to True enables connection pooling. For more information, seethe “Connection Pooling” section in Chapter 1 of the Lotus ConnectorLotusScript Extensions Guide.


Creating a New Connection Document in LEITo create a new Connection Document in LEI, perform the following steps:

1. Open the LEI Administrator database, decsadm.nsf.

2. Click the Add Connection button on the LEI Administrator Action Bar.

3. Select a connection type from the resultant list.

4. Complete the Connection Document as needed.

5. Save and Close the Connection Document.

6. Test the connection as described in the companion document LotusConnectors and Connectivity Guide.

Viewing or Editing Connection Documents in LEIOnce you create a Connection Document, it is visible in the Connectionsview. To view or edit an existing Connection Document in LEI, do thefollowing steps.

1. Open the LEI Administrator database, decsadm.nsf.

2. Select Connections from the LEI Administrator’s Navigator panel.

3. Select the desired Connection from the view display on the LEIAdministrator.

Note You can also edit connections used by a particular Activity byopening that Activity Document and clicking the Edit Connection button.

Creating a New Connection in DECSTo create a new Connection Document in DECS, perform the followingsteps:

1. Click the Connection button on the DECS Administrator navigator.

2. Click the Add Connection button on the action bar.

3. Select the desired Connector type from the resultant display.

4. Enter the required information in the resultant Connection Document.

Viewing or Editing Connection Documents in DECSOnce you create a Connection Document, it is visible in the Connectionview. To view or edit an existing Connection Document in DECS, performthe following steps.

1. Select Connections from the Views area of the DECS Administrator.

2. Select the desired connection from the resultant display.


ConsiderationsThis section lists general considerations for using a Lotus ConnectionDocument.

• The “Rollback upon error” option, specified on a ConnectionDocument, will not be effective when a transaction within an Activitymust be closed to complete the next step of the operation. For example,a Direct Transfer Activity, with “Overwrite existing data enabled”,cannot restore the truncated data if the transfer portion fails.

• When specifying view names on a Connection Document, only listviews that will actually be used by all activities that use the ConnectionDocument. Specifying a view name that is not needed by the callingActivity may cause that activity to fail.

Features Common to All Connection DocumentsThe following sections describe the parts that are found in everyConnection Document. For information about the unique parts of eachConnection Document, refer to the appropriate Connector chapter.

Pop-up HelpDark blue text in the section headings in a Connection Document indicatesthat pop-up help is available. To display pop-up help, place the cursor onthe heading and press and hold the mouse button.

LEI Connection NameThis field provides a name that identifies the connection in LEI. Eachconnection requires a unique name. This feature is not part of DECS. Themaximum number of characters is 127.

Password Encryption (Not Available on All Connection Documents)Password encryption allows LEI users to encrypt password informationusing their own encryption keys. The LEI server is always able to read thepasswords. Password encryption in LEI pertains specifically to thepassword as stored in the Notes database and as seen on the screen, not forcommunicating to the external system database. When data is sent to theexternal system database, encryption is removed.

As the author of a Connection Document, you can encrypt passwords usingNotes encryption keys. All encryption keys used to encrypt connectionsmust be added to the LEI server’s Notes user ID.

Once you have created encryption keys, you can enable encryption for aConnection Document by clicking the Password not Encrypted button inthe Connection Document and then selecting the encryption key to use. Thisprocess is described below.


Creating and Using Password Encryption KeysThis process attaches an encryption key on the LEI server ID. Theencryption key is not for your Notes ID, it is for the Notes ID used by theLEI server.

1. Open a Connection Document.

2. Click File — Security — User Security from the Notes menu.

3. Enter your Notes password when prompted.

4. Click the Notes Data tab and then the Documents tab.

5. Click New Secret Key.

6. Enter a new encryption key in the resultant data entry field, forexample abx459. Optionally add comments in the data entry fieldprovided for comments.

7. Click OK.

8. The new encryption key, in this example abx459, appears in theEncryption keys field on the resultant User ID menu.

9. Click Export.

10. Specify a file name on the Domino server in which to store the newencryption key.

11. Shut down the Domino server where LEI is installed.

12. Select File — Tools — Switch ID and enter the Notes ID used on thatDomino server.

13. Click the Notes Data tab and then the Documents tab.

14. Click Other Options and then select “Import Secret Key.”

15. Select the encryption key created above, in this example abx459.

16. Restart the Domino server where LEI is installed.

Note See the Password Encryption section of the Notes online help formore information.

17. Create or open your Connection Document in Edit mode.

18. Click the Password Not Encrypted button on the Connection Document.

19. Click Yes in response to the password encryption prompt.

20. Click the key tab on the resultant Document property sheet.

21. Select the desired key, in this example abx459, from the SecreteEncryption keys field.

22. Save the Connection Document.

You are now ready to run an LEI Activity with the Connection Documentcontaining the encrypted key.


Common Connection Document FieldsThe tables below describe fields that are common to most Lotus ConnectionDocuments.

The number and title of these fields will vary depending on the externalsystem and type of connection you select. For more information, see thechapter that describes the Connector that is specific to the type of externalsystem you wish to connect to.

You can choose to connect to data in: �� Tables�� Views �� Procedures (stored procedures - see Note

below)Select the desired option.

Selection Type:

Click the password encryption icon to encryptyour password for this Connection Document.You can click it again to turn encryption off.

Password Encryption KeyIcon

Enter the password associated with the UserName specified above.

Password

Enter the user name required to access the selecteddata source specified above.

User Name

Enter the information required for the specificdata source for which you are defining aconnection. This information can vary accordingto the type of data source selected. Note Depending on the Connector, more thanone field may be exposed to capture all of therequired database information.

Database/Engine/DirectoryPath/Data Source/Host StringProvider StringAuthentication Service

Select Oracle version, enter the name of the SybaseSQL Server where the database is located, orrelational database engine to use, or programmaticID for OLE DB provider to use. Note This field is not available for all ConnectionDocuments.

Server/Provider/OracleVersion/SQL Server

DescriptionField

Note When you browse for a stored procedure in the ConnectionDocument, you are presented with dialog box listing all the storedprocedures in the external system database. When you choose a storedprocedure, the parameters of the chosen stored procedure are automaticallylisted in the Parameters field (see the table below). If you do not specify astored procedure in the Connection Document, you can select a storedprocedure and its associated parameters from the Virtual Field or Virtual


Activity document. In either case, the stored procedure is entered as thedefault stored procedure in the Events section of the activity document. Inmost cases returned values are handled by the external system database, inthe case of Oracle, the Oracle connector handles returned information. Thisis transparent to you, however the person responsible for writing Oraclestored procedures should be aware of it. See the Oracle example in Chapter7 for a full explanation.

Use the Table/View/Procedure/Subdirectory Selection section of thedocument to select the specific metadata that you want to access throughthis connection.

Enter text in this field that may be helpful to you inorganizing or keeping track of your ConnectionDocuments.

Comments

This field lists the column names and their associateddata types found in the selected table or view of theexternal data source. If you are working with stored procedures, this fielddisplays the stored procedure parameters. See “SelectionType” in the table above.If you are connecting to a file system, use this field to listfile attributes corresponding data types from the selectedsubdirectory.

Column(s)/Parameters/File Attributes

This field shows the name of the specific table or viewyou select from the data source. Click the down-arrowbutton to access a list of the tables or views from whichyou can choose.

Name

This field allows you to select from tables by ownername. The default value is <Any>, allowing you to selectfrom all tables in the database. Click the down-arrowbutton to see a list of existing owner names. This enablesyou to select only from tables belonging to the specifiedowner. You must enter a valid Owner name in this field.Note This field is not available for the Text ConnectionDocument.

Note For iSeries, the owner name corresponds to alibrary name or SQL collection in OS/400.

Owner

Use the Manual button to select a table that does notappear in the current list of tables. After you enter atable all of the associated columns are displayed. See thesection below, “Using the Manual Button,” for moreinformation.

Description Table/View/Procedure/Subdirectory Selection Field


Manual ButtonYou can use the Manual button to specify a table that is not included in thelist of tables or views shown when you select the down-arrow button nextto the Name field.

You must enter the owner name and the table name, except in the case ofthe Lotus Connector for File System. You must enter these items exactly asthey are named in the data source or DECS/LEI will not be able to locateyour table.

Below is an example of a completed Lotus Connection Document for aSybase database.


Creating Connection DocumentsThis example illustrates the process of creating a sample ConnectionDocument in LEI.

Note To create a Connection Document in DECS, see DECS User Guide(desdoc6.nsf).

In order to connect to a supported data source, you must have the requiredconnectivity software for that data source installed on your server. Verifythat all of your database software is installed and current with all availablemaintenance releases and fix packs before attempting to create ConnectionDocuments. For related requirements, see the first chapter of the LotusEnterprise Integrator for Domino (LEI) Installation Guide.

1. From the LEI Administrator, click the Add Connection icon.

2. A list of supported external data sources appears.

Note You can remove any of the supported data sources from the listthat you do not intend to use. Refer to the Notes Application Developer’sGuide for more information on how to remove a form from a menu.

3. Select the needed data source type from the resultant list and click OK.The appropriate Lotus Connection Document appears.


Below is an example of a Sybase Connection Document.

4. Enter the required information in the Connection Document.

The Connection Document is divided in three sections:

• User Assistant Help — This section of the Connection Documentprovides basic usage instructions. It only appears if you haveenabled the User Assistant.

• Connectivity — This section of the Connection Document specifiesthe database or data source and the connectivity informationrequired to access that data source.

• Table/View/Procedure/Subdirectory Selection — This section of theConnection Document enables you to select the specific metadatathat you want to access through this connection. The title of thissection varies depending on the type of data you want to access.


Calling External ProceduresProcedures in external systems may be used in a number of forms-basedActivities and from within LC LSX scripts. Some Connectors provideprocedure functionality as an alternate method of performing data selectionor modification operations, while for others it is the only method ofcommunicating with an external system. In all cases, there are variouscontexts and requirements regarding the behavior and handling ofparameters for procedures.

Instructions for using procedures within a given LEI Activity or DECSoperation can be found in the documentation for that Activity. Any specialconsiderations for calling procedures within a specific Connector can befound in the documentation for that Connector. In general, parameters willbe provided to procedures by name if named parameters are supported,otherwise by position. Output from procedures will be expected as returnedresult sets when supported, otherwise output parameters may be used.

A procedure is generally used within three general contexts:

• Perform a black box action

In this case, the caller is not concerned with the action being performed;inputs may be provided, but no specific behavior or output is expected.This context is generally used within an LC LSX script, as mostforms-based LEI Activities expect specific behavior from a storedprocedure. In this case, input parameters are provided as indicated inthe script, and parameters of the corresponding name and data typewill be supplied to the procedure. For Connectors that do not supportnamed parameters, the parameter position becomes relevant.

• Perform a modification

In this case, the stored procedure is being used to alter data in theexternal database. This context is used in many situations; both fromforms-based Activities and scripts. When called from a script, it istreated like the black box action described above. When used informs-based Activities, the input parameters provided and the behaviorexpected is defined by the normal Activity behavior. For example,when using a stored procedure as the destination of a Direct TransferActivity, the input parameters match the destination fields being stored,and the insertion of new data records is the expected behavior. TheActivity in question will specify what parameters are provided for agiven context. For example, a single Virtual Field Activity can performinserts, updates, and deletes through different stored procedures, andthe parameters provided are specific to the action being performed.


• Produce a result set

In this case, a procedure is being used to return information from anexternal system, either to simulate a standard selection operation or asthe only method of producing a result set, depending on the Connector.Input parameters may be provided, and a result set should be returned.The input parameters are supplied in the same manner as the otherprocedure contexts described above. The result set contents aregenerally determined by the procedure definition. In some systems, thefields being returned must be identified at the time of the procedurecall by the caller. In this case, the output fields will be identified by thecalling Activity, or manually within the script. An example of thisbehavior is Oracle procedures, which only return results in outputparameters that must be identified at the time of the call.

Connectors and Supported Data Management ActivitiesThere are three LEI Advanced RealTime Activities - Virtual Fields, VirtualDocuments, and Virtual Agents. All other Activities are referred to as DataManagement Activities.

For information regarding Connectors and supported Advanced RealTimeActivities see “Connectors and Supported RealTime Activities” later in thischapter.

The table below shows which Connectors work with each DataManagement Activity. For more details, see specific Connector chapters inthis manual.

N/ANoNoN/ANoYes (forOS)

NoNoConnector

YesYesYesYesYesYesYesOracle 8

YesYesYesYesYesYesYesOracle 7

YesYesYesNoYesYesYesOLE DB

YesYesYesYesYesNoYesFile

YesNoNoYesYesYesYesText

YesYesYesYesYesYesYesODBC

YesYesYesYesYesYesYesLotusNotes

YesYesYesYesYesYesYesSybase

YesYesYesYesYesYesYesDB2

ScriptedActivities

ReplicationPollingJavaDirectTransfer

CommandArchiveLotusConnector


Note The Command Activity is the only activity that does not require aconnection. In such a case, the Command Activity would be executing anoperating system command on the system on which the LEI server isrunning.

Connectors and Supported RealTime ActivitiesConnectors that work with LEI Advanced RealTime Activities and DECSare listed below.

For information regarding Connectors and supported Data ManagementActivities see “Connectors and Supported Data Management Activities”earlier in this chapter.

Note A Virtual Fields Activity was previously known as a RealTime NotesActivity in LEI and DECS.

Supported Connections in DECSThe table below shows which Connectors work with a DECS Virtual FieldsActivity.

YesOracle 8

YesOracle 7

YesOLE DB

YesFile

NoText

YesODBC

NoLotus Notes

YesSybase

YesDB2

DECS Virtual Fields Lotus Connector


Supported Connections in LEI Advanced RealTimeThe table below shows which Connectors work with each AdvancedRealTime LEI Activity.

YesYesYesOracle 8

YesYesYesOracle 7

YesYesYesOLE DB

NoNoYesFile

NoNoNoText

YesYesYesODBC

NoNoNoLotus Notes

YesYesYesSybase

YesYesYesDB2

Virtual AgentsVirtual Documents++Virtual Fields++Lotus Connector

++Virtual Attachments and Integrated Credentials are options for theseActivities.

Connector Data Type Conversion TablesThis section describes how LEI handles data type conversions. It isprovided as background information. This information may be particularlyhelpful if you are scripting with the LC LSX Classes.

At the end of each Connector chapter is a section that includesdocumentation tables that define data type conversions for the specific datasource defined by the Connector. These documentation tables arrange LEIor DECS actions into four sections — Execute, Fetch, Insert/Update, andCreate.

During activity execution, data is transferred from its native data type intoan LEI or DECS field object, which is a component of a Fieldlist object. AFieldlist is a collection of named fields which is temporarily stored (inmemory only; not on disk) on the LEI server or Domino server in the case ofDECS. The data is then transferred, replicated, copied, and so on, to thedestination in the most compatible data type that LEI or DECS candetermine. Data can undergo two changes — first into an LEI or DECS fieldand second into the compatible target format.

Conversions such as character set are done at the last minute, and directlyfrom source to target to avoid extra or unnecessary conversions.


The figure below illustrates the conversion process of data types. Note thatthis is meant to show how data types might be converted during an LEIActivity. DECS has a similar conversion process, but it is limited toconversion between a data source and Domino. For information about thespecific conversions of data types for specific data sources, refer to the datatype conversion tables in the specific Connector chapters of this manual.

The information below provides details on the data type conversions.

• Execute operations against a LEI or DECS connection produce a resultset from the data source and a corresponding metadata structure calleda Fieldlist in LEI or DECS. The Execute table defines what type of LEIor DECS field will be added to a Fieldlist based on the type of the fieldin the result set. In general, each data source type maps to a single LEIor DECS type. Any multiple choices indicate that certain attributes ofthe source data type can alter the LEI or DECS type used.

• Fetch operations define what data transformations are valid in fetchesfrom a data source result set into an LEI or DECS Fieldlist. In a DirectTransfer and most forms-based Activities, the Fieldlist produced by aConnector in Fetch is sent back to that Connector for Fetch, but from anLEI or DECS script there is no such restriction. For each LEI or DECSdata type, the table indicates which data source columns may befetched into that field. Multiple choices indicate that various datasource types will be converted to the indicated LEI or DECS type. Foran LEI or DECS binary field, the different formats allow for differenttype checking restrictions. For example, an LEI or DECS number listallows numbers to be fetched from Notes, but an LEI or DECS datetimelist does not.


• Insert/Update operations are the opposite of a Fetch operation, and foreach LEI or DECS data type the table defines the valid data target typeswhich can be stored. Multiple values indicate that a single LEI or DECStype can map to multiple target types. Additional formattinginformation in a middle column has the same usage as for the Fetchoperation above.

• Create operations create metadata in the data target from an LEI orDECS Fieldlist. The table defines which data target type is createdbased on the LEI or DECS data type. Multiple values indicate thatformatting information from the LEI or DECS field affects the choice.This is especially relevant for Create operations since LEI or DECSfields can hold additional formatting information specifically to refinecreations. This is most apparent during an operation like DirectTransfer, but much of this is invisible to the LEI or DECS user exceptwhen using advanced scripts. Execute operations store additionalformatting information in the LEI or DECS Fieldlist metadata, which isthen used during creation to exactly reproduce (as best supported bythe data target) the source. For example, a 2-byte unsigned integer in adata source will be represented by the LEI or DECS generic INT type.But the original information is still stored in LEI or DECS, and for adata target which supports such a type, this information will be usedduring Create operations.

To summarize, the Execute and Create tables define the default mappingperformed by LEI or DECS when creating LEI metadata from a data source,or data target metadata from an LEI or DECS Fieldlist. The Fetch andInsert/Update tables define valid data type mapping between LEI or DECSand the data source/target.


Chapter 4Lotus Connector for Notes

This chapter provides information about the Lotus Connector for Notes,including descriptions of the fields in the Connection Document.

Introduction to the Lotus Connector for NotesThis chapter provides information about the Lotus Connector for Notes.The Lotus Connector for Notes can be used with IBM Lotus EnterpriseIntegrator for Domino (LEI) and Lotus Connector LotusScript Extensions(LC LSX).

The Lotus Connector for Notes allows you to define a connection to a LotusNotes database.

Notes Connection Documents are not available for DECS, nor are theyavailable for Advanced RealTime Activities.

Refer to Chapter 2, “Connectivity” for information about configuring andtesting connectivity.

Refer to Chapter 3, “Introduction to Lotus Connectors” for generalinformation about Lotus Connectors.

TerminologyThe table below lists LEI terms and the corresponding terms in Notes.

DocumentRecord

Field/ItemField

ViewIndex

FormMetadata

DatabaseDatabase

ServerServer

Notes/DominoLEI

43

Supported CharacteristicsThis section lists the supported characteristics of the Lotus Connector forNotes.

For a definition of the terms used in this section, see “Supported ConnectorCharacteristics — List of Terms” in Chapter 3 of this manual. If you areaccessing the Connector using LotusScript, see the Lotus ConnectorLotusScript Extensions Guide for more information.

• Writeback support — Full

• Writeback index — When an OrderList is provided, it uses an exitingview, creates a temporary or permanent view LEIIndexViewXXX,where XXX is the first available number. Lotus Connector for Notesproperties are used to control view creation.

• Statement syntax — Notes formula language. Excludes datamodification statements but includes “execute <agent name>” where<agent name> is a Notes agent that is not run on a view.

• Condition syntax — Valid when placed in the following Notes formula:SELECT <condition> ...

• Array transfer — None (Bulk Insert)

• Actions supported — Clear, Reset, Truncate

• Catalog types — Server, Database (no connection required), Metadata,Index, Field

• Create types — Database (cannot be connected), Metadata, Index

• Drop types — Database (cannot be connected), Metadata, Index

All connections have a set of properties with values that can be assignedand retrieved. See the Lotus Connector LotusScript Extensions Guide for a listof supported properties for each Connector. Also see sections “CommonConnector Properties” and “LCConnection Properties” in the LCConnectionClass chapter of that same manual.

Notes Connection Document for LEIThe Notes Connection Document defines a Connection to a Notes databaseand specifies the Domino server on which the database can be found.

Note The Notes Connection Document is not available for DECS or for LEIAdvanced RealTime Activities.

To create a new Notes Connection Document in LEI:

1. Open the LEI Administrator.


2. Click the Add Connection button in the Action bar.

3. Select Notes.

To open an existing Notes Connection Document, select it from theConnection view on the LEI Administrator.

Common FeaturesEach LEI Connection Document contains the following common features.

User Assistant HelpYou can enable the User Assistant in order to open a Connection Documentwith explanatory text at the top of the document. To turn the User Assistanton or off, use the option in the Help portion of the LEI Administrator’sNavigator panel.


Chapter 4: Lotus Connector for Notes 45

NameThis field provides a name that identifies the connection. Each connectionrequires a unique name. The maximum number of characters is 255. Thecomma character is not allowed.

Password EncryptionThis option enables the author of a Connection Document to encryptpasswords using Notes encryption keys. See the “Introduction toConnectors” chapter for details.

CommentThe Comment field provides space for you to annotate the ConnectionDocument with meaningful descriptive text.

Fields in the Connection DocumentSee the following tables for descriptions of the Connection Document fields.


ConnectivityThe Connectivity options are described below.

Specifies the file path and filename (*.nsf) of the Notes databaseidentified by this connection, relative to the Notes data directory.For example, to access C:\notes\data\orders.nsf, enter orders.nsfin this field.

Notes Database

Specifies the name of the server where the Notes databaseidentified by this Connection is located. Leave this field blank ifthe database is to be accessed locally.

Domino Server

Specifies a unique name that identifies this Connection. Themaximum number of characters allowed is 255. Commas are notallowed.

Name

DescriptionField

Connection OptionsThese advanced options extend the capabilities of LEI to take advantage ofspecific Notes data structures and design elements. The options let youspecify, for example, view-based selection criteria that manage thehierarchical structure of Notes. Connection Options also permit you todefine data translation and manipulation. The options are divided into thefollowing groups:

• General Options

• Document Selection

• Field Selection

• Data Transformation

• Data Creation

The fields in each of these sections are described below.

General OptionsWhen you select the General Options tab, the following options appear.These options can apply to the source or destination database, dependingon whether the connection is used by the Activity as the source or targetconnection.


To support computed subforms, list all of thesubforms to include here. All fields in these subformswill be considered to be part of the form and appearin the mapping dialog box in the activity.This field is disabled if anything other than “Do NotEnforce Form Design” is selected. For informationabout how to use computed subforms and enableform design, see the “Considerations” section later inthis chapter.

Use Computed Subforms

Specifies the directory where file attachments arestored if the option “Extract File Attachments isselected” (see below). If no path is specified here, fileattachments are copied to the current directory.

File Path for FileAttachments

Specifies the name of the port to use when dialing aserver remotely.

Server Port

Calculates all Notes field-related formulas (defaultvalue, input translation, and computed field), andinvokes all Notes field validation formulas whichensure that the data is within the parameters for thefield in the Notes form. Any field validation errors arerecorded in the Activity log.

Binding Options:Enforce Form Design andPerform Validation

Calculates all field-related formulas (default value,input translation, and computed field) as part of theActivity. This option may cause slower data transferas a result of formula calculations. This option doesnot execute @ function names that begin with Db. Itdoes enable field flags.

Binding Options:Enforce Form Design

Specifies that the Activity set all field flags as definedin the form but not execute any formulas. As a result,special types, such as reader and author fields, areassigned in new documents as indicated in the form.This option avoids the overhead of computing fieldformulas.

Binding Options:Enforce Field Flags Only

Specifies that the Activity not execute any Notes formand field-related formulas. Computed fields, such asthe current date, are not computed.

Binding Options:Do Not Enforce FormDesign

DescriptionField

Note Only Notes language formulas are executed by the above options.The above options do not execute LotusScript formulas.

Document SelectionWhen you select the Document Selection tab, the following options appear.The Document Selection section is used to configure the document leveloptions used by the Activity. These are used to limit the documents that theActivity selects from the source. Several options can be combined, but the


filtering is cumulative. A document must satisfy all options to be selected.These options can apply to the source or destination database, dependingon whether the connection is used by the Activity as the source or targetconnection, and apply to the creation of a result set.

continued

This option ensures that response documents retain theirhierarchical relations to the parent document. This optioncannot be used with the option “Include View Responses.”To use this option from an Activity with manual fieldmapping, add a field LCXHIER to both field lists (this is notnecessary for automatic field mapping by name or position).

Document Options:Copy ResponseHierarchies (Notesto Notes only)

Includes response documents of any parent document thatis used in a view. This option cannot be used along with theoption “Copy Response Hierarchies”.When used in a Notes to Notes transfer, the result in thedestination database is not hierarchical and all documentsare copied at the same level.

Document Options:Include ViewResponses

Enables you to select a form from the database specified inthe “Notes Database” field in the Connectivity section of theConnection Document.Fields To Use From Form — Once you select a form, thefields contained on that form are displayed. Check the fieldnames that you wish to use. Note Any field selection here is ignored when thisconnection is used in a Replication Activity. To tailor fieldselection for replication, explicitly map the fields in theMapping section of the Replication Activity Document.

Form To Use

DescriptionField


The full text query that you enter here is executed againstthe current result set and only the resulting documents(those that contain the searched text) are used by theActivity. The query is executed on the result set producedby either the command statement in the Activity or theView to Use for Selection entry, plus any defined agent toexecute. The database selected in the Connection Document must beindexed and a view must be selected in “View to Use forSelection” to support this option.This option only affects document selection through anexplicit Notes formula, such as a Direct Transfer Activity orthe LC LSX Connection.Execute method. It does not affectgeneric selection such as those done by ReplicationActivities.

Full Text Search Query to Execute

Makes view searches case-insensitive (they arecase-sensitive by default). An example of where to use thisis in timestamp replication with the case-insensitive stringcomparison option, where case-insensitive searches areneeded in Notes.

Document Options:Case-insensitiveView Searches

This option applies only when a Notes database is thesource. Deletes documents from the source Notes databasebefore transfer. As a result, the documents don’t show upon the destination database and are deleted from the source.To delete the source result set after a transfer, follow aregular transfer Activity with an Activity that deletes theresult set. Identify the second Activity as a dependentActivity of the first.This option only affects document selection through anexplicit Notes formula, such as a Direct Transfer Activity orthe LC LSX Connection.Execute method. It does not affectgeneric selection such as done by Replication activities.This option applies only when a Notes database is thesource. It has no effect when the connection document isused to connect to a destination.

Document Options:Delete Result Set

By default, the documents in a result set are restricted tothose associated with the source form identified as themetadata in the Activity Document. Use this option toinclude documents of all forms in the result set, filteringthem through the source form. Note If the option “Fetch View Column Data” is used forselection, this option is required and will be automaticallyselected.

Document Options:Include Documentsof Other Forms

DescriptionField


Field SelectionWhen you select the Field Selection tab, the following options appear. TheField Selection section is used to limit the document fields (or viewcolumns) used by the Activity to create the result set.


The following table describes the Field Selection options.

continued

Appends a virtual field named UNID to the result set. This fieldwill fetch the Universal Note ID for each document.

Special FieldsOptions:Load DocumentUniversal ID(UNID)

Enables you to choose an agent name from a resultant list. The agent specified will further refine the documents selected.The agent is executed on the result set produced by thecommand (or selection) statement in either a Direct TransferActivity or a Command Activity. Note This option is only valid if the connection will be used ina Direct Transfer or Command Activity.

Agent toExecute

If the name of a Notes view is entered, the documents appearingin that view will be selected by the Activity. This option replacesand ignores any command statement specified in the Activity.By default, only top-level documents are included, althoughother options allow the view contents to be altered. Documentsnot in the view are ignored. When used with ordering ortimestamps in Replication Activities, this field indicates thename of the view to use for these operations. When performingprimary key replication, supplying a view name can improveperformance by not requiring the database to be re-indexed withevery Activity run. When no view is specified, a temporary viewis still created and an event is logged suggesting use of apermanent view name. When the view is the wrong format or doesn’t exist, checking theAllow View Creation/Modification option (see below) allowsthe activity to create or overwrite that view in its own format.This option overwrites the view when modifying an existingview.Allow View Creation/Overwrite — Checking this option allowsthe activity to modify or create the view if it doesn’t already existor doesn’t have the proper formatting. This option is requiredfor timestamp replication when a view is specified. If the option “case insensitive view searches” is selected, then theview columns will be set to sort case-insensitive.Note When you use a permanent view to support keyedsearches, such as those used by Replication Activities, and anexisting view needs to be altered (as is always true fortimestamp replication), that view will be deleted and a new viewwill be created.

View to Use ForSelection

DescriptionField


continued

Transfers the contents of multivalue types Text List, NumberList, and Datetime List as Text. This is useful when thedestination database cannot accept a multivalue’s default binarytype.

Other Options:TranslateMultivalueTypes to Text

Specifies how fetching is to be performed. Choose one of thefollowing options.�� Fetch Document Items — Gets the field names from the form

designated as source metadata. �� Fetch View Column Data — Gets data from the view

designated at “View to Use for Selection.” The fields areautomatically named column1, column2, and so on. Thedestination metadata must contain fields of this name, or usemap by position or user defined mapping to prevent fieldmapping failures. Selecting this option automatically checksthe option “Include Documents of Other Forms.”

Note The Fetch View Column Data option retrieves text dataonly.

Fetch Selections

Appends a virtual field named FILE to the result set. FILEcontains file names of all attachments in a document and extractsfiles to disk. The directory for file extraction is the currentdirectory or the one specified in the “File Path for FileAttachments” field in the General Options section of the NotesConnection document. While this option copies file attachmentson a Notes to Notes transfer, the “Copy File Attachments”option is more efficient for this purpose because it does not writeto files.

Special FieldsOptions:Extract FileAttachments(FILE)

Appends a field “@Modified” to the result set, which containsthe Notes implicit document timestamp. Select this option on therelevant Notes Connection and specify it as a Timestamp in theReplication Activity to use Notes implicit timestamps inreplication. This prevents having to use additional NotesTimestamp fields.

Special FieldsOptions:Load LastModifiedTimestamp(@Modified)

Appends a virtual field named REF to the result set. This fieldwill fetch each document’s parent Universal Note ID, which isused by Notes to maintain response hierarchies.

Special FieldsOptions:Load ParentUniversal ID(REF)

Appends a virtual field named NOTEID to the result set. Thisfield will fetch the Note ID for each document.

Special FieldsOptions:Load DocumentNotes ID(NOTEID)

DescriptionField


Signals LEI to use this length as the maximum for Text typefields. This option is often used when a metadata is beingcreated in a relational database and text lengths and types areimportant. The default text length is slightly under 64KB.If the “Truncate Data When Necessary” option is set in theActivity Document, LEI truncates the text field to the maximumlength indicated here before transfer. If the Truncate Data optionis not checked, any record with one or more fields greater thanthis limit is not transferred, and LEI logs the error “Dataoverflow.”

Other Options:MaximumLength for TextData

Copies any composite support fields associated with transferreddocuments. This includes the fields, links, and fonts to returnfull fidelity of composed data.To use this option from an Activity with manual field mapping,add a field LCXCOMP to both field lists (this is not necessary forautomatic field mapping by name or position).

Other Options:Copy SpecialCompositeFields (Notes toNotes only)

Copies any file attachments associated with transferreddocuments. If this option is not selected, transferred fileattachments will appear as icons only in the target.To use this option from an Activity with manual field mapping,add a field LCXFILE to both field lists (this is not necessary forautomatic field mapping by name or position).

Other Options:Copy FileAttachments(Notes to Notesonly)

DescriptionField

Understanding Destination Column Data TypesTo use any of these options with transfers to a database other than Notes,you must already have columns available in the destination metadata. Thecolumns are added as the last columns in the metadata (one for each of thefields in the order listed below).

Some Notes Connection options add a special field to the result set. Thisfield is automatically handled by a Notes target, but must be explicitlydefined in a non-Notes target. When using LEI Replication between twoNotes databases, these options must be selected in parallel, for both thesource and target connections, to properly map within the ReplicationActivity.

The destination database column types must reflect the following Notesdata types:

DATETIME or TIMESTAMP equivalent@Modified

VARCHAR or BLOBFILE

CHAR (32)REF

INTNOTEID

CHAR (32)UNID

Data TypeDatabase Column Type


Note Since UNID, NOTEID, and REF are concepts found in Notesdatabases, but not in relational databases and other targets, pay specialattention when you use these options and properties. When moving datafrom Notes to a non-Notes target, always check these options in theConnection Document (or in scripting, set these properties) when yourequire UNID, NOTEID, and/or REF to be transferred. Remember thatthese columns must be explicitly defined in a non-Notes external source.Transferring the UNID, NOTEID and REF data from a non-Notes externalsource back to Notes will not flow back to the UNID, NOTEID, and REFfields through a normal transfer. You must use scripting to do this kind oftransfer.

Data TransformationWhen you select the Data Transformation tab, the following options appear.The Data Transformation section provides options for executing formulas totransform data.

The following table describes the Data Transformation options.

Enter the Notes formula that will execute before the datain the designated target is updated. The transformationwill take place as part of the update operation. Thisapplies when the connector is used to connect to the targetdatabase.

Formula to ExecutePrior to Update

Enter the Notes formula that will execute just before theselected data is inserted into the target. The data ischanged as part of the insert operation. This applies whenthe connector is used to connect to the target database.

Formula to ExecutePrior to Insert

Enter the Notes formula that will execute just after thedata is fetched. The data is altered as part of thefetch/select operation. This applies when the connector isused to connect to the source database.

Formula to ExecuteDuring Select

DescriptionField

Transformation formulas should be prefixed with “select @all;”. Forexample, to assign a field value, enter the formula <select @all; FIELDNewField := “New Value”;>.


Data CreationWhen you select the Data Creation tab, the following options appear. TheData Creation section provides options for managing data creation with theNotes database during processing of any Activities associated with theConnection.

The following table describes the Data Creation options.

continued

This option commits each change to the Notes databaseimmediately. The default behavior is to commit allchanges at database close. This option can slow downperformance.

Notification Options:Commit ChangesImmediately

Embeds the form in documents sent as a result of using the“Send New Documents as Mail” option. Use this optionwhen the recipients of the mail will not have the relevantform in their mail database.

Notification Options:Embed Form inMailed Documents

Sends inserted documents as mail rather than saving to aNotes database. The transferred records must contain afield named SendTo containing a valid address. Forsources that support SQL, this field can be selected as partof the SQL SELECT clause in the statement of the ActivityDocument. Example syntax is shown below:select column1, column2 from table whereSendTo=“[email protected]”

Notification Options:Send NewDocuments as Mail

DescriptionField


The file path of the Notes .ntf template file to be used tocreate the destination database.

Database TemplateFile Name

The Domino server containing the template file to be usedto create the destination database.

Database TemplateServer

Creates a destination Notes database to receive the data ifa database does not exist. For database creation, you canoptionally enter a template server and template file path. This option should not be selected when the targetDomino server is part of a Domino cluster because thedatabase may be created in an inconsistent state. When thetarget is a Domino cluster, create the database using aNotes client prior to running the LEI activity.

Creation:Create Database (if itdoesn’t exist)

Deletes the database specified in the Activity uponconnection. This is used together with Creation (below) todelete and then recreate the database prior to population.

Deletion:Delete Databaseupon Connection

Specifies how encryption should occur.Encrypt Enabled Fields — Encrypts all enabled fields inthe form of the target document. Private Encyption Key(s) — To use private encryptionkeys (the default is to use the public key), provide one ormore private encryption key names, separated by commasor semicolons in this field. These keys must be available onthe LEI server. For more information on encryption, see Domino DesignerHelp.

Encryption

Use this option to clear all deletion stubs from the Notesdatabase when disconnecting. It is strongly recommendedthat this only be used with the option to “Refresh Views asDatabase is Closed”, since once the stubs are deleted, theywill not be properly removed from views. Selecting the“Refresh Views” option will remove them before purging.This option cannot be used on a Notes database with theNotes replication setting to “Delete documents notmodified in the last N days.” Doing so will skip thepurging and generate an error indicating the conflict. To use this option successfully, the LEI Notes ID musthave sufficient access to the database to enablemodification of Notes replication settings.

Notification Options:Purge Deletion Stubsas Database isClosed

Reflects the database changes in the databases views at theend of the transfer or replication process when thedestination database is being closed. This option causesview refresh to occur as part of the transfer rather than tooccur when the user next opens the view.

Notification Options:Refresh Views asDatabase is Closed

DescriptionField


Considerations when Working with the Lotus Connector for NotesThis section addresses important issues in using a Notes Connection.

Activity Command StatementsAside from standard selection formulas using the Notes formula language,statements executed against Notes may also be of the following format:

"execute agent name"

where “agent name” is the name of a Notes agent.

This functionality can be used to modify data through a post-statementPolling Activity, where normally an update statement would be executed.By using this syntax, an agent that updates documents may be run. This isan LEI-specific formula language enhancement to account for the fact thatnon-selection formulas cannot be used as LEI statements.

The “execute <agent>” statement syntax requires a sufficient access level toperform the desired actions and access the agent.

The agent must satisfy the following requirements:

• Uses a shared agent

• Is run manually from actions menu or manually from agent list

• Is run on all documents in database or run once

• Does not use simple actions

• Cannot be view-based, that is, specified as “run on selected documentsin view” or “run on all documents in view”

LEI Replication of NotesWhen you make modifications to a client for Timestamp Replication, thereis no way to obtain the server current datetime. Because of this, timedifferences between the Notes client and server are relevant. If the client islater than the server, then some changes may not be picked up until thenext replication. If the client is earlier than the server, then some changesmay be missed. If synchronization of time is not possible between client andserver, then making the Domino server slightly earlier than the clients willprevent documents from being missed.

When specifying a view to use (View property of Notes ConnectionOptions), that view must be of a particular LEI format, and the keysindicated in the view are irrelevant (they are taken from the Activity viewkeys, regardless of the Activity). If the view is not of the correct format, thenit will be modified by LEI, using the AlterView property of the NotesConnection Options. When a view is specified and the view is not of the


correct format, then it will be recreated for the proper result set. For thisreason, do not use a view which is used for other purposes because it willbe overwritten. When no view is specified, a temporary view is created forthe duration of that Activity and a message is written to the logrecommending that a permanent view be used. When using a view namewith Timestamp Replication, the same view name is used betweenreplications, but the view is still altered each time since it is categorizedbased on the last replication timestamp.

Notes Form CreationNotes form and field attributes, such as field formulas, help text, andformatting, will be set as defaults when LEI creates a new Notes form.

Caution When you use the ’Create Target Metadata’ option on DirectTransfer, Archive, and Replication Activities to create a new form within aNotes target database, do not have the Notes target database open while theactivity is running. The new form is not available until the database isclosed and re-opened. Errors will result if you try to access the newlycreated records before the database has been closed and re-opened.

Notes @FunctionsThe following @commands cannot be used in any Notes formula specifiedin an Activity. They are not supported except through the Notes interface:

• @DbLookup

• @DbColumn

• @Command

• @MailSend

• @Prompt

• @DDEInitiate

• @DDETerminate

• @DDEExecute

• @DDEPoke

Depositor Level AccessWhen the LEI Server connects with Depositor level access, documents in thedatabase are not visible. Any selection results in no documents. One effectis that overwriting or truncating data will not find any documents andtherefore not remove them.


Moving Text List Data over Different PlatformsNotes databases store data in canonical format (byte ordering), which isplatform-independent. LEI automatically converts data to the hostplatform’s byte ordering when read from Notes, and to canonical formatwhen written to Notes. (Composite data is an exception: It is always left incanonical format.) As a result, all Notes-format data outside of Notes isconsidered to be in platform byte ordering native to the host format,allowing users to ignore the implications of canonical byte ordering.

Moving data between Domino servers and Notes and other databases doesnot usually pose a problem. However, in the case where data is moved fromone Domino server to another Domino server through another database,and using LEI server platforms with different host formats, list types (textlist, number list, and datetime list) become corrupted. For example, you usea Windows NT LEI server to move a text list from Notes to DB2. If the datais moved from DB2 back to Notes through another NT server, there is noproblem. But if the other LEI server is a UNIX server, then the data iscorrupted.

Notes Data TypesThe following tables show the correspondences of Notes to LEI data typesfor various types of Activities. The following notes apply to the tablesbelow:

(p) — Indicates that if Allow Precision Loss is not enabled, then an errorwill be generated on the type match. Allowing precision loss is the default.

(o) — Indicates that overflow checking will be performed when data isbeing transferred. If an overflow occurs and Truncate Data When Necessaryis enabled, then the data is truncated; if not an error is generated.

Text, Number, or Time indicates single-value unless otherwise specified.

The Notes Connection Option “Maximum Length for Text Data” alters thedefault boundary of 64996 for LEI text.

The Notes Connection Option “Translate Multivalue Types to Text” makesmultiple-value Text, Data, and Time look like single-value Text.

LEI evaluates the absence of a field in a Notes database as a NULL.

Note For more information on the organization of these tables, see thesection entitled “Note on Connection Data Type Conversion Tables” inChapter 3.


Execute

Binary (composite format, variable length,unbounded)

Rich Text

Binary (text list format, variable length,bound = 64996)

Allow multiple values

Text (variable length, bound = 64996)Single-valueText

Text (variable length, bound = 64996)ReaderNames

Text (variable length, bound = 64996)AuthorNames

Text (variable length, bound = 64996)Names

Text (variable length, bound = 64996)Keywords

Binary (datetime list format, variablelength, bound = 64996)


DatetimeSingle-valueTime

Binary (number list format, variable length,bound = 64996)


FloatSingle-value — NotesNumber field containsa single value

Number

LEINotes

Fetch

Texttext list

Time, Text (single-value)datetime list

Number, Text (single-value)number list

Text (single-value), Rich Textcomposite

Text, Number allow multi-values, Time allowmulti-values, Rich Text, Formula

BLOBBinary (o)

Text, Rich Text, FormulaText (o)

TimeDatetime

Number (p, o)Numeric

Number (p, o)Currency

NumberFloat

Number (p, o)Int

NotesLEI


Insert/Update

Text (o)text list

Time (o), Text (single-value) (o)datetime list

Number (o), Text (single-value) (o)number list

Text (single-value) (o), Rich TextcompositeDate from NotesRich Text field

Text (o), Number (allow multiple values) (o),Time (allow multiple values) (o), Rich Text,Formula (o)

BLOBBinary

Text, Rich Text, FormulaText

TimeDatetime

Number (p)Numeric

Number (p)Currency

NumberFloat

NumberInt

NotesLEI

Create

Text (allow multiple values)text list

Time (allow multiple values)datetime list

Number (allow multiple values)number list

Rich Textcomposite

Text (single-value)BLOBBinary

Rich Textunbounded

Text (single-value)boundedText

Time (single-value)Datetime

Number (single-value)Numeric

Number (single-value)Currency

Number (single-value)Float

Number (single-value)Int

NotesLEI


Virtual FieldsThe following virtual fields are supported by the Lotus Connector forNotes. For more information, see the “Field Virtual Codes in the LCFieldClass” section of the Lotus Connector LotusScript Extensions Guide.




Rich Textcomposite

Text (single-value)BLOBBinary

Rich Textunbounded

Text (single-value)boundedText

Time (single-value)Datetime

Number (single-value)Numeric

Number (single-value)Currency

Number (single-value)Float

Number (single-value)Int

NotesLEI

Lotus Connector for Notes PropertiesSee the Lotus Connector LotusScript Extensions Guide for a list of propertiesfor the Lotus Connector for Notes.


Chapter 5Lotus Connector for DB2

This chapter provides information about the Lotus Connector for DB2,including descriptions of the fields in the Connection Document.

Introduction to the Lotus Connector for DB2The Lotus Connector for DB2 delivers connectivity to IBM’s DB2 UniversalDatabase (UDB), enabling LEI, DECS, and Domino applications written inLotusScript to access DB2 using the standard Lotus Connector API. TheLotus Connector for DB2 does not give access to all features of the DB2UDB.

The Lotus Connector for DB2 uses the DB2 Client Level Interface (CLI) toperform actions between the Lotus Connector API and DB2.



After creating your DB2 connections, you should test each of them using theConnection Document test utility provided with LEI.

Obtaining Updated DB2 InformationCurrent information about DB2 can be found at the following Web site:

http://www-4.ibm.com/software/data/db2/

65

TerminologyThe table below lists LEI terms and the corresponding terms in DB2.

Stored ProcedureProcedure

RowRecord

ColumnField

IndexIndex

TableMetadata

DatabaseDatabase

N/AServer

DB2 Term LEI Term

Identity ColumnsWith identity column support, DB2 version 7 can automatically generateunique values for new rows in a table, including primary keys, for DB2 datatypes INT, BIGINT, SMALLINT, and DECIMAL. In order to maintain aunique sequence of key values for a given table, DB2 generates identitycolumn values upon Insert. For example, inserting a record with a NULLkey (defined as an identity column) will yield a new row with the nextunique and sequential key.

The Lotus Connector for DB2 supports the use of DB2’s identity columnswith the following limitation:

When an activity’s key field is mapped to a DB2 Identity column, and theActivity or Create event uses a NULL value for its key field, the Activity orevent will complete successfully. However, the key field value generated byDB2 is not returned to the source document or Advanced RealTime VirtualFields key field. To obtain the newly generated key field values forsubsequent operations or for Open, Update, and Delete events, the keydocuments must be replicated from the DB2 table or view or initializedagain in LEI or DECS. A stored procedure can also be used to return thenew identity column value as an output parameter.

Note DB2/400 support of identity columns is being introduced with V5R2.


Supported CharacteristicsThis section describes LotusScript functionality available for the LotusConnector for DB2.

For a definition of the terms used in this section, see “Supported ConnectorCharacteristics — List of Terms” in Chapter 3 of this manual. If you areaccessing the Connector using LotusScript, see the Lotus ConnectorLotusScript Extensions Guide for a detailed description of the LotusScriptproperties and methods supported by the Lotus Connector for DB2.

Note The Lotus Connector for DB2 provides the standard set of LotusConnector methods, or function calls, to control interaction with a DB2connection. All methods are supported. However, certain methods onlysupport a subset of functions. Unsupported functions will return thefollowing error message:

“Requested functionality is not available.”

• Connection properties — Database, UserID, and Password

• Standard functionality — Full

• Writeback support — Full except when the result set is ordered. In thiscase, writeback functionality is not available and is simulated withkeyed operations. Make sure that the proper key settings and values areprovided even when performing writeback update and removeoperations.

• Writeback index — Index strongly advised, but not required. Use thecommand “create index <indexname> on <tablename> (<column1>,<column2>, ..., <columnN>)”. (Simulated by keyed operations whencursors are not supported.)

• Statement syntax — Full DB2 SQL Syntax, including UDFs (UserDefined Functions)

• Condition syntax — Valid when placed in the following DB2 statement:SELECT ... WHERE <condition> ORDER BY ...

• Array transfer — Insert

• Actions supported — Clear, Reset, Truncate, Commit, Rollback

• Catalog types — Database (no connection required), Metadata, Field,Procedure, Parameter

• Create types — Metadata, Index

• Drop types — Metadata, Index

All connections have a set of properties with values that can be assignedand retrieved. See the Lotus Connector LotusScript Extensions Guide for a list

Chapter 5: Lotus Connector for DB2 67

of supported properties for this Connector. Also see sections “CommonConnector Properties” and “LCConnection Properties” in the LCConnectionClass chapter of that same manual.

DB2 Connection Document for LEIThe Connection Document for DB2 defines a connection to a DB2 database.Connection Documents enable you to define your system connections. Theycontain access information for specific databases and users. When youcreate an Activity, you make connection choices from your set of definedconnections.

To create a new DB2 Connection Document in LEI:



3. Select DB2.

To open an existing DB2 Connection Document, select it from theConnection view on the LEI Administrator.






Password EncryptionThis option enables the author of a Connection Document to encryptpasswords using Notes encryption keys. See the “Introduction to LotusConnectors” chapter for details.

Options TabsConnection Document options are classified and displayed by logical tabnaming and grouping. The Table Creation Options and Logging Optionsare common to all Connection Documents.

Comment The Comment field provides space for you to annotate the ConnectionDocument with meaningful descriptive text.

Fields in the LEI Connection DocumentSee the following tables for descriptions of the Connection Document fields.



NoJournal propertySpecifies whether or not journalling is enabled. Select this option to enable support for SQL queries againstnon-SQL data external to DB2. When the target is anon-journalled data source, SQL queries are not supportedunless this option is selected.If your database does not have journalling enabled, set this tooff. If your database has journalling enabled, set this to on.This option sets the access mode to read-only (transactionisolation level of uncommitted read), which enables SQLqueries. The default access level is read-write (transactionisolation level committed read). The requirement for thisoption is most common when connecting to DB2/400 tables. Itappears as a <table> in <library> not valid for operation”error message. For non-DB2/400 users, this option disables all data insertand modification operations through this connection.

Data Journalling

Password propertySpecifies the password associated with the user name. Thismatches the DB2 Password property and displays as hiddentext.Password encryption is described in the “Introduction toLotus Connectors” chapter.

Password

Username propertySpecifies the user name required to log in to the DB2database. This matches the DB2 Username property.

User Name

Database propertySpecifies the name of the DB2 database.

Database

Specifies a unique name that identifies this connection. Themaximum number of characters allowed is 255.

Name

DescriptionField

Connection OptionsThe Connection Options section of the DB2 Connection Document providesoptions for adjusting the performance and actions of the connection.


Transaction OptionsWhen you select the Transaction Options tab, the following options appear.The Transaction Options apply to operations that create, modify, or deletedata. These settings have no effect on Advanced RealTime Activities.

This is used with the option Commit Every N Operationsto specify how many actions must occur before thechanges are committed.

Commit Frequency

CommitFrequency propertySpecifies how commit actions should occur. The choicesare as follows:�� Commit At Disconnect: Enable this option to commit

changes to the database as the database is beingdisconnected at the end of the operation. This is thedefault Commit option.

�� Commit Every N Operations: Commits changesperiodically after a specified number of changes aremade. This number is specified as the CommitFrequency below.

�� Commit After Every Option: When enabled, thisoption causes immediate commits for each change tothe database. Note that this option reducesperformance.

Commit Options

RollbackOnError propertySpecifies what to do if an error happens during datatransfer, specifically how Rollback actions should occur.When Rollback is enabled, and an Activity terminates inan error state, all changes in the current DB2Connection’s transaction are rolled back at disconnecttime.

Rollback Rollback upon Error

DescriptionField


Table Creation OptionsWhen you select the Table Creation Options tab, the following optionsappear.

CreateMaxLogged propertyEnables you to specify the data size past which columnsare created without logging (DB2 syntax is “NOTLOGGED COMPACT”).When LEI or DECS creates a DB2 table, all columns arecreated with logging by default.Columns larger than 1GB cannot be logged by DB2.Specifying a value in this field allows for successful tablecreation with columns of this size.Text or Binary columns of unlimited length are alwayscreated using this option.

Size Cutoff for CreateNOT LOGGEDCOMPACT

DescriptionField

Logging OptionsWhen you select the Logging Options tab, the following options appear.The Logging Options section provides a feature for including SQLstatements in the Activity log.

TraceSQL propertySpecifies that all SQL statements submitted to the externaldatabase and generated during the Activity be included inthe Activity log.Note Selecting this option slows down performance. Useit only for troubleshooting.

Output SQLStatements to Log

DescriptionField


Selection TypeRegardless of which Options tab you select, the following option isavailable.

Enables you to specify the metadata type for aconnection.�� Select Table to connect to a DB2 table.�� Select View to connect to a DB2 view.�� Select Procedure to connect to a DB2 stored

procedure.Spaces in a table or column name are not permitted.

Selection Type

DescriptionField

Table SelectionThese settings display a current list of tables and allow you to specify whichtables will be accessed. You can also specify a table name not shown in thelist by selecting the Manual button.

Lists the columns or parameters (stored procedure)defined for the specified Name.Spaces in a table or column name are not permitted.

Column(s)

Lists the available table, view, or procedure namesdefined for the specified Owner.A selection list displays all DB2 tables, views, orprocedures for the selected Owner. Choose the table,view, or procedure to connect to.If an owner is not specified, all names are listed for thespecified Selection Type.Spaces in a table or column name are not permitted.

Name

Lists the available owner names for the above table,view, or procedure selection type in the specifiedDatabase. On iSeries, this lists libraries by library name.A selection list displays all DB2 owners. Choose theowner of the table, view, or procedure being connectedto from the list (Optional).

Owner

DescriptionField


DB2 Connection Document for DECSThe Connection Document for DB2 defines a connection to a DB2 database.Connection Documents enable you to define your system connections. Theycontain access information for specific databases and users. When youcreate an Activity, you make connection choices from your set of definedconnections.

To create a DB2 Connection Document in DECS:

1. Click Connections in the Navigator.


3. Choose DB2 from the dialog box.

4. Click OK.

To open an existing DB2 Connection Document, select the ConnectionDocument you want from those displayed in the Connections View.

Note You can optionally use the Connection Document Assistant to assistyou in completing the Connection Document. If you use the Assistant, theConnection Document opens with explanatory text at the top of thedocument. To toggle the Assistant on or off, click the “Enable/DisableAssistant” text at the bottom of the DECS Administrator Navigator panel.

Common FeaturesEach DECS Connection Document contains the following common features.

User Assistant HelpYou can optionally use the User Assistant to assist you in creating theConnection Document. If you enable the User Assistant, the ConnectionDocument opens with explanatory text at the top of the document. Totoggle the Assistant on or off, click the “Enable/Disable Assistant” text atthe bottom of the DECS Administrator Navigator panel.





Fields in the DECS Connection DocumentThe DECS Connection Document provides values for Connectivity andTable Selections options. The fields in the DECS Connection Document aredescribed below.

continued

Specifies the metadata type for a connection.�� Select Table to connect to a DB2 table.�� Select View to connect to a DB2 view.�� Select Procedure to connect to a DB2 stored procedure.Spaces in a table or column name are not permitted.

Selection Type

NoJournal propertyEnables support for SQL queries against non-SQL dataexternal to DB2. When the target is a non-journalled datasource SQL queries are not supported unless you enablethis option.If your database does not have journalling enabled, setthis to off. If your database has journalling enabled, setthis to on.This option sets the access mode to read-only (transactionisolation level of uncommitted read), which enables SQLqueries. The default access level is read-write (transactionisolation level committed read). The requirement for thisoption is most common when connecting to DB2/400tables. For non-DB2/400 users, this option disables all datainsert and modification operations through thisconnection.

Data JournallingJournalled/Non-Journalled Data

Password propertySpecifies the password associated with the user name.This matches the DB2 Password property and displays ashidden text.

Password

Username propertySpecifies the user name required to log in to the DB2database. This matches the DB2 Username property.

Userid

Database propertySpecifies the name of the DB2 database.

Database

DescriptionField


Enables you to add comments to the ConnectionDocument that help describe its intent or usage. This is arich text field. You can paste doclinks, as well as normaltext characters here.

Comment

Lists the columns or parameters (stored procedure)defined for the specified Name.Spaces in a table or column name are not permitted.

Column(s)

Lists the available table, view, or procedure namesdefined for the specified Owner.A selection list displays all DB2 tables, views, orprocedures for the selected Owner. Choose the table,view, or procedure to connect to.If an owner is not specified, all names are listed for thespecified Selection Type.Spaces in a table or column name are not permitted.

Name

Lists the available owner names for the above table, view,or procedure selection type in the specified Database. OniSeries, this lists libraries by library name.A selection list displays all DB2 owners. Choose theowner of the table, view, or procedure being connected tofrom the list (Optional).

Owner

DescriptionField

Stored ProceduresA DB2 stored procedure may be used wherever procedures are allowed,such as the destination of a Direct Transfer, within an LSX script, or in anAdvanced RealTime Activity such as Virtual Agents or Virtual Documents.The stored procedure being called must have its parameters set up correctlyfor the call.

Input and output values are provided to DB2 procedures as namedparameters. This requires that the parameters in DB2 use the same names asthe fields being provided as the parameters unless explicitly mapped in theactivity. The parameters being provided should include key values whenbeing used in the context of a keyed operation (selection, update, or deletecontexts), and data values when relevant (insert or update contexts). TheDB2 parameter data types should be selected as the closest match to thedata type in the LC API. See the “DB2 Data Types” section, later in thischapter, for more information.

Note When using a stored procedure with the Delete event in LEI orDECS, the stored procedure need only declare the fields specified under“Key(s):” in the Activity. Since a Delete event will not return any output


parameters in any case, the Activity will only pass the key fields to thestored procedure. Furthermore, an Activity connecting to a StoredProcedure cannot support only the Delete event.

Any result set output from a DB2 stored procedure must be returnedthrough a DB2 cursor left open in the stored procedure. The result setproduced by the stored procedure will be retrieved with this cursor.

The Lotus Connector for DB2 supports the return of output parametersfrom stored procedures. The following scenarios describe what is returnedfrom a stored procedure call:

• If the stored procedure returns a result set only, the Connector willreturn that result set fieldlist.

• If the stored procedure returns multiple result sets, the Connector willreturn the first result set fieldlist only.

• If the stored procedure returns output parameters only, the Connectorwill return a fieldlist of those output parameters.

• If the stored procedure returns output parameters and a result set, theConnector will return a fieldlist of the output parameters only.

• If the stored procedure returns output parameters and multiple resultsets, the Connector will return a fieldlist of the output parameters only.

The Lotus Connector for DB2 will not return multiple fieldlists in anyscenario and a fieldlist of output parameters will always have returnprecedence.

Considerations when Using Stored ProceduresDB2/400 does not support stored procedure result sets from remote datasources.

When using DB2 stored procedures and the Call method in LotusScript, the“Fieldnames” property must be set. The “Fieldnames” property mustcontain all of the parameters declared OUT or INOUT in the DB2 storedprocedure.

Stored procedure return values are not supported with the Lotus Connectorfor DB2.

Stored procedures in DB2 can be written in Java, C, and C++. DB2Universal Database version 6.1 and 7.1 provide a Stored Procedure Builderwith which to create procedures more easily. The version 7.1 StoredProcedure Builder also allows stored procedures in SQL.


Example: DB2 Stored Procedure in CThe following is an example of a DB2 stored procedure written in C for theDB2 CLI preprocessor. This is the format that would be required for theOpen event of an Advanced RealTime Virtual Fields Activity assuming thatthe key field is called NUMBER1 and the data fields are called NUMBER2,TEXT1, and TEXT2. In this context, the key field is the input parameter, andthe result set is expected to include the data fields followed by the key field.Note that the input parameter data type is checked and handled for bothinteger and float types.

SQL_API_RC SQL_API_FN sf_proc (void *reserved1,

void *reserved2,

struct sqlda *inout_sqlda,

struct sqlca *ca)

{

/* Declare a local SQLCA */

EXEC SQL INCLUDE SQLCA;

/* Declare Host Variables */

EXEC SQL BEGIN DECLARE SECTION;

char *select_stmt = “SELECT NUMBER2, TEXT1, TEXT2,NUMBER1 FROM TALBENAME WHERE NUMBER1 = ?”;

long int number1;

EXEC SQL END DECLARE SECTION;

if (inout_sqlda)

{

if ((inout_sqlda->sqlvar[0].sqltype == SQL_TYP_INTEGER) ||

(inout_sqlda->sqlvar[0].sqltype == SQL_TYP_NINTEGER))

number1 = *((long int *)(inout_sqlda->sqlvar[0].sqldata));

else if ((inout_sqlda->sqlvar[0].sqltype == SQL_TYP_FLOAT)||

(inout_sqlda->sqlvar[0].sqltype ==SQL_TYP_NFLOAT))


number1 = (long int) *((double *)(inout_sqlda->sqlvar[0].sqldata));

else

number1 = 0;

EXEC SQL WHENEVER SQLERROR GOTO err;

EXEC SQL PREPARE stmt FROM :select_stmt;

EXEC SQL DECLARE curs CURSOR FOR stmt;

EXEC SQL OPEN curs using :number1;

}

err:

memcpy(ca, &sqlca, sizeof (struct sqlca));

if (inout_sqlda)

*(inout_sqlda->sqlvar[0].sqlind) = -128;

return(SQLZ_DISCONNECT_PROC);

}

Example: DB2 Stored Procedure in SQLThe following is an example of a simple SQL stored procedure.

CREATE PROCEDURE DB2ADMIN.NEW_SALES_ORDER ( IN CUSTIDint,

IN ITEMIDint,

IN QTY int,

OUT SONUMbigint)

LANGUAGE SQL

P1: BEGIN

DECLARE CUSTVAR int;

DECLARE ITEMVAR int;

DECLARE QTYVAR int;

DECLARE ITEMCOSTVAR dec(7,2);


DECLARE AMTVAR dec(9,2);

DECLARE STAMP timestamp;

DECLARE cursor1 CURSOR FOR

SELECT ITEMCOST FROM DB2ADMIN.ITEMS

WHERE ITEMID = ITEMVAR;

DECLARE cursor2 CURSOR FOR

SELECT SONUM FROM DB2ADMIN.SALES_ORDERS

WHERE DTEORD = STAMP;

SET CUSTVAR = CUSTID;

SET ITEMVAR = ITEMID;

SET QTYVAR = QTY;

SET STAMP = CURRENT TIMESTAMP;

OPEN cursor1;

FETCH FROM cursor1 INTO ITEMCOSTVAR;

CLOSE cursor1;

SET AMTVAR = QTY * ITEMCOSTVAR;

INSERT INTO DB2ADMIN.SALES_ORDERS (CUSTID, ITEMID,QTY, AMT, DTEORD)

VALUES (CUSTVAR, ITEMVAR, QTYVAR, AMTVAR, STAMP);

OPEN cursor2;

FETCH FROM cursor2 INTO SONUM;

CLOSE cursor2;

END P1

Example: Sample LC LSX Agent to Call a DB2 Stored ProcedureThis example uses the SQL stored procedure shown in the previousexample.

Sample LS:

[Options]

Option Public

Option Explicit

Uselsx “*lsxlc”


[Initialize]

Sub Initialize

Dim sess As New LCSession

Dim conn As New LCConnection (“db2”)

’set the connection parameters...

conn.Database = “databaseName”

conn.UserId = “userId”

conn.Password = “passWord”

’connect to the database...

conn.Connect

’set the stored procedure owner and stored procedurename...

conn.Owner = “DB2ADMIN”

conn.Procedure = “NEW_SALES_ORDER”

’set Fieldnames property with any output parametersdeclared in

the stored procedure...

conn.Fieldnames = “SONUM”

’declare any fields and fieldlists for input/outputdata...

Dim input_fieldlist As New LCFieldList

Dim output_parms As New LCFieldlist

Dim in_field As New LCField (1, LCTYPE_INT)

Dim sonum As New LCField (1, LCTYPE_NUMERIC)

Dim out As Double

’set the input parameters of the stored procedure...

Set in_field = input_fieldlist.Append (“CUSTID”,LCTYPE_INT)

in_field.Value = 2146


Set in_field = input_fieldlist.Append (“ITEMID”,LCTYPE_INT)


Set in_field = input_fieldlist.Append (“QTY”,LCTYPE_INT)


’with the input parameters set, call the storedprocedure...

’the declared output_parms fieldlist will hold the outputparameters

of the stored procedure...

out = conn.Call (input_fieldlist, 1, output_parms)

’fetch parameter(s) into the output_parms fieldlist...

out = conn.Fetch (output_parms)

’retrieve the parameter(s) from the output_parmsfieldlist...

Set sonum = output_parms.GetField (1)

’use the output parameter value(s) in your script...

Print “Your new sales order number is ” & sonum.Value(0)

conn.Disconnect

End Sub

DB2 Data TypesThe following tables show the correspondences of DB2 to LotusScript datatypes.


In DB2, the data type pairs DOUBLE and FLOAT and NUMERIC andDECIMAL are synonymous, and only the first of each type synonym(DOUBLE and NUMERIC) is indicated in these tables.

• (p) — Indicates that if Allow Precision Loss is not enabled, then an errorwill be generated on the type match. Allowing precision loss is thedefault.

• (o) — Indicates that overflow checking will be performed when data isbeing transferred. If an overflow occurs and Truncate Data WhenNecessary is enabled, then the data is truncated; if not, an error isgenerated.

Note For more information on the organization of these tables, see thesection entitled “Note on Connection Data Type Conversion Tables” inChapter 3. These conversion tables may have changed since this printing.For the latest information about IBM’s DB2 data types, see the IBM Web sitehttp://www-4.ibm.com/software/data/db2.

Data Type ConsiderationsThe following considerations pertain to use of DB2 data types.

• When you use the DB2 BIGINT data type as a keyfield on a ConnectionDocument, a precision loss error occurs when you initialize keys. Theerror also occurs if you select “Leave all/Leave selected RealTime fieldsin Documents” and one of the field values is a BIGINT. To avoid thiserror, use a different data type in these instances.

• The DB2 data type DATALINK and the Data Links Manager are notcurrently supported.

• The DB2 column used as the timestamp field in timestamp replicationor timestamp polling must be of type TIMESTAMP, not DATE.

• DB2 allows the storage of the time value 12:00:00 AM as both 00:00:00and 24:00:00. When transferring 24:00:00 from DB2, DECS and LEIconsider this time to be invalid. If 12:00:00 AM times are insertedthrough DB2, and not through DECS or LEI, use 00:00:00 for 12:00:00AM, not 24:00:00.


ExecuteThis table describes how the Execute method converts data types betweenLotusScript Connector Extensions and DB2.

Binary (BLOB format) (variable length,bound <= 2GB)

BLOB

Text (variable length, bound <= 2GB)DBCLOB

Text (variable length, bound <= 32700)LONGVARGRAPHIC

Text (variable length, bound <= 16383)VARGRAPHIC

Text (fixed length, bound <= 16383)GRAPHIC

Text (variable length, bound <= 2GB)CLOB

Text (variable length, bound <= 32740)Binary (BLOB format) (variable length,bound <= 32740)

(default)FOR BIT DATA

LONG VARCHAR

Text (variable length, bound <= 32740)Binary (BLOB format) (variable length,bound <= 32740)


VARCHAR

Text (fixed length, bound <= 32766)Binary (BLOB format) (fixed length, bound<= 32766)


CHAR

DatetimeTIMESTAMP

DatetimeTIME

Numericprecision =7REAL

DatetimeDATE

NumericotherNUMERIC

Currencyprec-scale<=19,scale<=4

NUMERIC

Intprec-scale<=9,scale<=0

NUMERIC

Floatprecision =15DOUBLE

IntINTEGER

IntSMALLINT

NumericBIGINT

Lotus Connector (LC) Data TypeAttributeDB2 Data Type


FetchThis table describes how the Fetch method converts data types betweenLotusScript Connector Extensions and DB2.

Invalidnon-BLOB

CHAR [FOR BIT DATA], VARCHAR [FORBIT DATA], LONG VARCHAR [FOR BITDATA], CLOB, GRAPHIC, VARGRAPHIC,LONG VARGRAPHIC, DBCLOB, BLOB

BLOBBinary (o)

CHAR [FOR BIT DATA], VARCHAR [FORBIT DATA], LONG VARCHAR [FOR BITDATA], CLOB, GRAPHIC, VARGRAPHIC,LONG VARGRAPHIC, DBCLOB, BLOB

Text (o)

TIMESTAMP (p), DATE, TIMEDatetime

INTEGER (p), BIGINT, SMALLINT (p),DOUBLE (p), NUMERIC (p)

Numeric

INTEGER, SMALLINT, DOUBLE (p),NUMERIC (p)

Currency

INTEGER, SMALLINT, DOUBLE,NUMERIC (p)

Float

INTEGER, SMALLINT, DOUBLE (p),NUMERIC (p)

Int

DB2 Data TypeAttributeLotus Connector (LC) Data Type

Insert/UpdateThis table describes how the Insert and Update methods convert data typesbetween LotusScript Connector Extensions and DB2.

continued

TIMESTAMP, DATE (p), TIME (p)Datetime

INTEGER (p), BIGINT, SMALLINT (p),DOUBLE (p), NUMERIC (p)

Numeric

INTEGER (p), SMALLINT (p), DOUBLE (p),NUMERIC (p)

Currency

INTEGER (p), SMALLINT (p), DOUBLE,NUMERIC (p)

Float

INTEGER, SMALLINT (p), DOUBLE,NUMERIC (p)

Int



TIMESTAMP, DATE (p), TIME (p)datetime list

INTEGER (p), BIGINT, SMALLINT (p),DOUBLE, NUMERIC (p)

number list

CHAR [FOR BIT DATA] (o), VARCHAR[FOR BIT DATA] (o), LONG VARCHAR[FOR BIT DATA] (o), CLOB (o), GRAPHIC(o), VARGRAPHIC (o), LONGVARGRAPHIC (o), DBCLOB (o), BLOB (o)

anyBinary

CHAR [FOR BIT DATA] (o), VARCHAR[FOR BIT DATA] (o), LONG VARCHAR[FOR BIT DATA] (o), CLOB (o), GRAPHIC(o), VARGRAPHIC (o), LONGVARGRAPHIC (o), DBCLOB (o), BLOB (o)

Text


CreateThis table describes how the Create method converts data types betweenLotusScript Connector Extensions and DB2.

continued

TIMESTAMPdatetimelist

DOUBLEnumber list

CHAR (fixed,len<=254), VARCHAR(254<len<=4000), LONG VARCHAR(4000<len<=32700), or CLOB (length > 32700)

composite

CHAR FOR BIT DATA (fixed,len<=254),VARCHAR FOR BIT DATA (254<len<=4000),LONG VARCHAR FOR BIT DATA(4000<len<=32700), or BLOB (length > 32700)

BLOBBinary


Text

TIMESTAMP, DATE, or TIMEDatetime

NUMERIC (prec, scale), BIGINTNumeric

NUMERIC (19, 4)Currency

DOUBLE or NUMERIC (prec, scale)Float

INT, SMALLINT, or NUMERIC (prec, 0)Int

DB2 Data TypeAttributeLotus Connector (LC)Data Type



text list

DB2 Data TypeAttributeLotus Connector (LC)Data Type

XML Data TypesYou can install DB2’s XML Extender in addition to other DB2 EnterpriseEdition version 7.1 products. The XML Extender provides three XML datatypes - XMLVARCHAR, XMLCLOB, and XMLFILE. The Lotus Connectorfor DB2 supports the XMLVARCHAR and XMLCLOB types. It does notsupport the XMLFILE type.

When using LotusScript, XML data types should be stored in LCFields oftype LCTYPE_TEXT.

Understanding Notes Data Type Transfer ConversionsWhen using LEI or DECS and transferring data to and from DB2 databases,the following considerations are useful.

• Although several DB2 data types support 15 or more digits, forexample DB2’s BIGINT supports 19 digits, Notes truncates and roundsvalues of 16 or more digits. For best results, use 15 digits or less whenNotes is the source or target of transfers.

• When using LotusScript, LCFields that are defined to store a DB2BIGINT should be of type LCTYPE_NUMERIC.

• When creating metadata in Notes from a DB2 source, all DB2 numbertypes will create a Notes Number, all DB2 date or time types will createthe Notes DateTime, and all other DB2 data types will create Notes Text.

• When creating metadata in DB2 from a Notes source, the NotesNumber will create a DB2 DOUBLE, Notes DateTime will create a DB2TIMESTAMP, and all other Notes data types will create a DB2 CLOB.

• DB2 Universal Database forces column-specific code pages in tablesusing the GRAPHIC data types. The Lotus Connector for DB2 ONLYsupports the translation of data to a single code page. On UNIXplatforms, this is the code page of the operating system. On Win32, thisis the code page specified by the environment variable DB2CODEPAGEor the operating system code page if this variable is not set. The LotusConnector for DB2 does not support the translation of multiple codepages per table, as seen with DB2 GRAPHIC data types. Thisconsideration is most applicable to Japanese, traditional Chinese, andUNICODE code page usage. For more information, see the NationalLanguage Support (NLS) material in your DB2 user documentation.


Error Logging and Problem DeterminationError logging and problem determination features exist to aid the user introubleshooting events.

Error LoggingIf a Connector operation produces an error, the Connector retrieves theerror from DB2 and returns it to the appropriate log or message area.

Problem DeterminationWhen programming with LotusScript, you can use the Lotus Connector forDB2’s trace facility to aid with problem determination during theprogrammed task. You can enable tracing of all SQL statements by settingTraceSql to True (1).

In LEI, you can also use the Trace Metaconnector.

Accessing DB2 on an iSeries System Using the Lotus Connector for DB2You can access DB2 on an iSeries system using the Lotus Connector forDB2. The procedure varies slightly depending on whether or not the DB2database resides on the same iSeries system as the Domino server.

DB2 Database on Same iSeries System as Domino ServerUse the following procedure to access a DB2 database that resides on thesame iSeries system as the Domino server.

1. Add a relational database entry in DB2/400. An example is shownbelow:ADDRDBDIRE RDB(database name) RMTLOCALNAME(*LOCAL)

2. Create a DB2 Connection document using the relational database namein the above statement for the database name entry.

3. Enter the user name and password for iSeries.

This user name and password should have authority to access the givendatabase.

4. If the table on the iSeries system is not journalled, select the“Non-Journalled Data” option in the Connection Properties section ofthe DB2 Connection document.


DB2 Database on a Different iSeries System than Domino ServerUse the following procedure to access a DB2 database that resides on adifferent iSeries system than the Domino server.

1. Add a relational database entry in DB2/400. An example is shownbelow: ADDRDBDIRE RDB(database name) RTMLOCNAME(IPaddress)

2. Start the DDM server job on the remote iSeries by using the followingcommand:STRTCPSRV *DDM.

You can verify that the job QRWLSNN in subsystem QSYSWRK isactive by using the WRKACTJOB command.

3. Create a DB2 Connection Document using the relational database namein the above statement for the database name entry.

4. Enter the user name and password for iSeries.

This user name and password should have authority to access the givendatabase.

5. If the table on the iSeries system is not journalled, select the“Non-Journalled Data” option in the Connection Properties section ofthe DB2 Connection Document.

6. To use interactive SQL to verify that the connection to the remoteiSeries is set up correctly, run the STRSQL command from your localiSeries system and then issue the following SQL command: Connect to remote server name

You must have 5722-ST1 installed to use STRSQL.

7. You can also test connectivity using DCTEST from the OS/400command line: Call Qnotes/dctest

Note If this is the first time that you have used SQL to connect to aremote iSeries system, an error message (SQLPKG not found) mayappear. You can run the following agent to create *SQLPKG on theremote iSeries system:Option Public

Uselsx “*lsxodbc”

Sub Initialize

Dim con As New ODBCConnection

con.AutoCommit=False


If (con.ConnectTo(“databasename”,“userid”, “pwd”)) Then

Call con.Disconnect

End If

Print “Test Create SQL Pkg”

End Sub


Chapter 6Lotus Connector for File System

This chapter provides information about the Lotus Connector for FileSystem, including descriptions of the fields in the Connection Document.

Introduction to the Lotus Connector for File SystemThe Lotus Connector for File System allows you to connect to the filesystem on the server on which LEI is installed.

The Lotus Connector for File System cannot be used with LEI VirtualDocuments or Virtual Agents Activities.



TerminologyThe table below lists LEI terms and the corresponding terms used by theLotus Connector for File System.

File specificationRecord

N/AField

N/AIndex

SubdirectoryMetadata

Directory pathDatabase

N/AServer

FileLEI

91

Supported CharacteristicsThe following list captures supported characteristics of the Lotus Connectorfor File System.

For a definition of the terms used in this section, see “Supported ConnectorCharacteristics - List of Terms” in Chapter 3 of this manual. If you areaccessing the Connector programmatically, see the Lotus ConnectorLotusScript Extensions Guide for more information.


• Writeback index — N/A

• Statement syntax — File specification with optional wild cards

• Condition syntax — File specification with optional wild cards

• Array transfer — None


• Catalog types — Database, Metadata, Field

• Create types — Database, Metadata

• Drop types — Database, Metadata

All connections have a set of properties with values that can be assignedand retrieved. See the Lotus Connector LotusScript Extensions Guide for a listof supported properties for each Connector. Also see the “CommonConnector Properties” and “LCConnection Properties” sections in theLCConnection Class chapter of that same manual.

Note Since the only key supported by the Lotus Connector for File Systemis the Filename field, the Replication Activities must use this as the keyfield.

File System Connection Document for LEIThe File System Connection Document defines a connection to an externalfile. Connection Documents enable you to define your system connections.They contain access information for specific databases and users. When youcreate an Activity, you make connection choices from your set of definedconnections.

Note The Lotus Connector for File System cannot be used with LEI VirtualDocuments or Virtual Agents Activities. However, it can be used withVirtual Fields Activities.


To create a new File System Connection Document in LEI:



3. Select File System.

To open an existing File System Connection Document, select it from theConnection view on the LEI Administrator.

Chapter 6: Lotus Connector for File System 93






Options TabsConnection Document options are classified and displayed by logical tabnaming and grouping. The same Table Creation Options and LoggingOptions are common to all Connection Documents.



Note The Lotus Connector for File System cannot be used with LEI VirtualDocuments or Virtual Agents activities.


Connection PropertiesThe Connection Properties section of the document provides fields andoptions that establish the basic connectivity for this connection definition.

Enter the directory path containing the subdirectory to be usedas metadata. This path must indicate the parent directory of thesubdirectory containing the needed file(s) - not the directory inwhich the file(s) reside.The specified path must be accessible from the server where theLEI Administrator is installed. For example, on Win32 this pathmay be a network accessible drive such at\\SystemName\temp or it may be a local drive such asc:\temp. Note When enabling metadata selection on an ActivityDocument that uses this connection, be sure to change to thesubdirectory in which the metadata actually resides, not theparent subdirectory.Note This option was configured to specify the parentsubdirectory specifically so that the connection could be used bymore than one activity concurrently.

Directory Path

Specifies a unique name that identifies this Connection. Themaximum number of characters allowed is 255.

Name

DescriptionField

File Connection OptionsThe File Connection Options enable you to specify the type of contents inthe files and their sort order. File Connection Options are Activity-specific.

Note These settings have no effect on Advanced RealTime Activities.

Specifies one of the following three file sorting methods.�� Sort File names as Binary�� Sort File names with Case Sensitivity�� Sort File names without Case Sensitivity

Sort Order

Specifies the text (international) format of the file. The default isNATIVE, meaning use the native format of the machine that isexecuting the Activity.

Contents TextFormat

Specifies whether to treat file contents as text or binary.�� Binary: Select this option to have file contents treated as

binary (BLOB) data.�� Text: Select this option to have file contents treated as text.

File Contents

DescriptionField


Subdirectory SelectionThe Selection field definitions are listed below.

Lists the file attributes and corresponding data types of thesubdirectories listed.

File Attributes

Specifies the name of the subdirectory name to search in. Oncespecified, all associated file attributes display.

Name

DescriptionField

File System Connection Document for DECS The File System Connection Document defines a connection to an externalfile. Connection Documents enable you to define your system connections.They contain access information for specific databases and users. When youcreate an Activity, you make connection choices from your set of definedconnections.

To create a File System Connection Document in DECS:



3. Choose File System from the dialog box.

4. Click OK.

To open an existing File System Connection Document, select theConnection Document you want from those displayed in the ConnectionsView.

The File System Connection Document for DECS is shown and describedbelow.

Note You can optionally use the Connection Document Assistant to assistyou in completing the Connection Document. If you use the Assistant, theConnection Document opens with explanatory text at the top of thedocument. To toggle the Assistant on or off, click the “Enable/DisableAssistant” text at the bottom of the DECS Administrator’s Navigator panel.








Fields in the DECS Connection Document The Connection Document provides values for Connectivity andSubdirectory Selection options. The fields in the DECS ConnectionDocument are described below.

Enables you to add comments to the Connection Document thathelp describe its intent or usage. This is a rich text field. You canpaste doclinks, as well as normal text characters here.

Comment

Specifies the file attributes and their corresponding data typefrom the selected subdirectory. Typically this is:�� Contents (Text)�� Filename (Text)�� Size (Int)�� Timestamp (Date Time)

File Attribute(s)

Specifies the name of the subdirectory name to search in. Oncespecified, all associated file attributes display.

Name

Enter the directory path containing the subdirectory to be usedas metadata. This path must indicate the parent directory of thesubdirectory containing the needed file(s) - not the directory inwhich the file(s) reside.The specified path must be accessible from the server where theDECS Administrator is installed. For example, on Win32 thispath may be a network accessible drive such at\\SystemName\temp or it may be a local drive such as c:\temp.Note When enabling metadata selection on an ActivityDocument that uses this connection, be sure to change to thesubdirectory in which the metadata actually resides, not theparent subdirectory.Note This option was configured to specify the parentsubdirectory specifically so that the connection could be used bymore than one activity concurrently.

Directory Path

DescriptionField

Considerations When Working with the Lotus Connector for File SystemConsider the following information when using the Lotus Connector forFile System.

• The Directory Path field in the File System Connection Documentcorresponds to the Database field in other Connection Documents. TheSubdirectory field in an Activity Document corresponds to the Table orForm name. In the Selection statement, you can use a file specificationthat includes wild cards such as “*.txt”.


For Win32 users, the following example identifies all .txt files beginningwith the letters “nab” in the directory path D:\files\somefiles\myfiles.

nab*.txtSelect Statement

Equivalent to Table or Form inother Connections

MYFILESSubdirectory (inActivityDocument)

Equivalent to Database in otherConnections

D:\FILES\SOMEFILESDirectory Path (inConnectionDocument)

NoteValueField

• Timestamps on the Win32 FAT file system are precise to two secondsonly and are always even. This may cause replication mismatches withmore precise systems.

• The metadata returned from the Lotus Connector for File System is filename, timestamp, size, and contents.

• Any file name, timestamp, or size can be used as a key, and can be usedin combination. Contents cannot be used as a key.

• Results can be ordered by file name, timestamp, or size, although onlyone order field is permitted, resulting in only one key field forreplication.

• The Select Metadata action button gives a list of subdirectories in thedirectory path.

• If the Source or Target Connection of a Direct Transfer is a FileConnection and Automatic Field Mapping by Position is selected, thepositional order of the File’s fields is as follows:

Filename

Contents

Timestamp

Size

• If the Source Connection of a Direct Transfer is a File Connection, youcan leave the select statement blank. The activity will proceed withoutan error as though the select statement had read as follows:select *.*

• For any Activity in which you use the Field Mapping by Positionoption, the field display and the internal field order are not identical forthis Connector. The fields listed for the Text Connector connectionappear onscreen in alphabetical order. However, internally, LEI/DECSreads the fields in the following order and then maps them, in thatorder, to the external system.


Filename (VARCHAR)

Contents (BLOB or TEXT)

Timestamp (TIMESTAMP)

Size (INTEGER)

File System MetadataThe metadata for a File record is significantly different from many otherLEI/DECS Connections. There is a single record description (metadata)with set fields of set types. These fields are shown in the following table.

This is an LEI/DECS INT field containing the size of the filecontents, in bytes. This field is ignored on write operations; thesize is obtained from the Contents field. This field matches anyLEI/DECS number field (INT, FLOAT, CURRENCY, orNUMERIC), although any type other than INT will cause aprecision loss error if Allow Precision Loss is disabled.Note LEI/DECS removes trailing spaces. If Contents is typeTEXT and its value includes trailing spaces, then there may be adifference between the value of the Size field and the length ofthe Contents field.

*Size

This is an LEI/DECS DATETIME containing the lastmodification date and time for the file. This field maps to aLEI/DECS DATETIME field.

Timestamp

This field is only available if you specify that the “Contents” fieldtype is TEXT. The “ContentsFormat” property enables you tospecify the format of the text as a specific character set. Thecharacter set specified is applied to the “Contents” field. Validcharacter set names are the same as the ones used for setting the“NativeText” property in the notes.ini file and the sorting characterset in the Order MetaConnector. The default setting is “NATIVE.”

ContentsFormat

This is an LEI/DECS TEXT (NATIVE format) or BINARY (BLOBformat) field with no maximum length. This field contains thefile contents as a stream, and matches any LEI/DECS TEXT orBINARY field. The default type is TEXT, but the BINARY typeallows files to be handled as binary BLOBs.

Contents

This is an LEI/DECS TEXT field with a maximum lengthdependent on the maximum file path length (varies by operatingsystem). The file name is specified without the directory, sincethat is defined by the DATABASE property. This field matchesany LEI TEXT or BINARY field. Required for Insert operations asthe file name to insert. This field is returned as case-insensitive for Win32 operatingsystems. However, UNIX is case-sensitive and for iSeries, thefilename may be case-sensitive.

Filename

DescriptionField


Note Some databases and data sources have reserved words that cannotbe used. Refer to the documentation for the product itself for informationabout reserved words. For example, “Size” is an invalid column name inOracle, so activities involving a file system connection and an Oracleconnection may encounter errors if “Create Metadata” is selected to createOracle metadata with the same field names.

Understanding Text Connector Field Mapping by PositionFor any Activity in which you use the Field Mapping by Position option,you must understand that field display and internal field order are notidentical for this Connector. The fields listed for the Text Connectorconnection appear onscreen in alphabetical order. However, internally,LEI/DECS reads the fields in the following order and then maps them, inthat order, to the external system.

Filename (VARCHAR)

Contents (BLOB or TEXT)

Timestamp (TIMESTAMP)

Size (INTEGER)


Chapter 7Lotus Connector for ODBC

This chapter provides information about the Lotus Connector for ODBC,including descriptions of the fields in the Connection Document.

Introduction to the Lotus Connector for ODBCThis chapter provides information about the Lotus Connector for ODBC.The Lotus Connector for ODBC can be used with IBM Lotus EnterpriseIntegrator for Domino (LEI), Domino Enterprise Connection Services(DECS), and Lotus Connector LotusScript Extensions (LC LSX).

Use an Lotus Connector for ODBC to connect LEI to an ODBC-compliantdatabase such as Lotus Approach. Lotus Software recommends using theLotus ODBC drivers. See the Lotus ODBC Driver documentation forcomplete information.

Note LEI does not provide client software; you must have alreadyinstalled client software. For example, if you are connecting to DB2 throughODBC, the system running LEI must have ODBC and the DB2 Clientinstalled.



TerminologyThe table below lists LEI terms and the corresponding terms in ODBC.

RowRecord

ColumnField

IndexIndex

TableMetadata

Not ApplicableDatabase

Data SourceServer

ODBCLEI

103

Supported CharacteristicsThis section lists the supported characteristics of the Lotus Connector forODBC.

For a definition of the terms used in this section, see “Supported ConnectorCharacteristics - List of Terms” in Chapter 3 of this manual. If you areaccessing the Connector using LotusScript, see the Lotus ConnectorsLotusScript Extensions Guide for more information.

• Writeback support — Full except when the driver doesn’t supportordered updatable cursors. In this case, writeback functionality is notavailable and is simulated with keyed operations. Make sure that theproper key settings and values are provided even when performingwriteback update and remove operations.

• Writeback index — Index strongly advised, but not required. Use thecommand “create index <indexname> on <tablename> (<column1>,<column2>, ..., <columnN>)”, or use the native system syntax if this isnot supported. This is simulated by keyed operations for drivers whichdo not support cursors.

• Statement syntax — Level 1 ODBC SQL Syntax

• Condition syntax — Valid when placed in the following ODBCstatement: SELECT ... WHERE <condition> ORDER BY ...



• Catalog types — Server (no connection required) Metadata, Field,Procedure, Parameter

• Create types — Metadata

• Drop types — Metadata

All connections have a set of properties with values that can be assignedand retrieved. See the Lotus Connectors LotusScript Extensions Guide for a listof supported properties for each Connector. Also see sections “CommonConnector Properties” and “LCConnection Properties” in the LCConnectionClass chapter of that same manual.

ODBC Connection Document for LEIThe ODBC Connection Document, shown below, defines a Connection to anODBC database. Connection Documents enable you to define your systemconnections. They contain access information for specific databases andusers. When you create an Activity, you make connection choices fromyour set of defined connections.


To create a new ODBC Connection Document in LEI:



3. Select ODBC.

To open an existing ODBC Connection Document, select it from theConnection view on the LEI Administrator.

Chapter 7: Lotus Connector for ODBC 105










ConnectivityThe Connectivity options are shown and described below.

Specifies threading.Enable this option to notify the LEI server that the ODBC driverbeing used is single-threaded and that it does not support amulti-threaded operation.

DriverThreading:SingleThreading

Specifies the password associated with the user name above.This displays as hidden text. Password encryption is described in the “Introduction to LotusConnectors” chapter.

Password

Specifies the user name required to log in to the ODBC datasource.

User Name

Specifies the name of the ODBC data source as listed in theODBC Administrator. To indicate this property generically fromthe LC LSX or a Metaconnector, use the Server property.

Data Source


Name

DescriptionField

Connection OptionsThe Connection Options section provides options for managing datatransactions, creating tables, and logging SQL commands. These settingshave no effect on a DECS Virtual Fields Activity or in an LEI AdvancedRealTime Virtual Fields Activity document.


Transaction OptionsWhen you select the Transaction Options tab, the following options appear.The Transaction Options apply to operations that create, modify, or deletedata.

Select this option if you want all changes in the currentODBC Connection’s transaction rolled back at disconnecttime when the Activity terminates in an error state.

Rollback: RollbackUpon Error

Specifies whether ODBC cursors are to be used. Enable thisoption to disable ODBC cursors and use keyed operationsinstead.Note LEI automatically checks whether or not the datasource supports ODBC cursors. Disabling cursors may be required when the ODBC driverdoes not properly report support for ordered updateablecursors, causing an error for writeback operations (oftenfrom Scripted or Replication Activities).

Cursor Options:Disable ODBCCursors

This is used with the option Commit Every N Operations tospecify how many actions must occur before the changes arecommitted.

Commit Frequency

Specifies how commit actions should occur. The choices areas follows.�� Commit At Disconnect: Enable this option to commit


�� Commit Every N Operations: Commits changesperiodically after a specified number of changes are made.This number is specified as the Commit Frequency below.

�� Commit Every Operation: When enabled, this optioncauses immediate commits for each change to thedatabase. Note that this option reduces performance.

Commit Options

DescriptionField


Logging OptionsWhen you select the Logging Options tab, the following options appear.The Logging Options section provides a feature for including SQLstatements in the Activity log.

Select this option to include in the Activity log all SQLstatements generated during processing of the Activity. Note Selecting this option slows down performance. Use itonly for troubleshooting.

Output SQLStatements to Log

DescriptionField


Enables you to specify the metadata type for a connection.�� Select Table to connect to an ODBC table.�� Select View to connect to an ODBC view.�� Select Procedure to connect to an ODBC stored


Selection Type

DescriptionField

Table OptionsThese settings display a current list of tables and allow you to specify whichtables will be accessed and how. You can also specify a table name notshown in the list by selecting the Manual button.


Lists the columns or parameters (stored procedure) defined for thespecified Name.Spaces in a table or column name are not permitted.

Column

Lists the available table, view, or procedure names defined for thespecified Owner.Click the down-arrow button to select from the list of available tables,views, or procedures.A selection list displays all ODBC tables, views, or procedures for theselected Owner. Choose the table, view, or procedure to connect to.If an owner is not specified, all names are listed for the specifiedSelection Type.Spaces in a table or column name are not permitted.

Name

Lists the available owner names for the above table, view, orprocedure selection type in the specified Database. On iSeries, this listslibraries by library name.A selection list displays all ODBC owners. Choose the owner of thetable, view, or procedure being connected to from the list (Optional).

Owner

DescriptionField

ODBC Connection Document for DECSThe Connection Document for ODBC defines a connection to a ODBCdatabase. Connection Documents enable you to define your systemconnections. They contain access information for specific databases andusers. When you create an Activity, you make connection choices fromyour set of defined connections.

To create a ODBC Connection Document in DECS:



3. Choose ODBC from the dialog box.

4. Click OK.

To open an existing ODBC Connection Document, select the ConnectionDocument you want from those displayed in the Connections View.

The ODBC Connection Document for DECS is shown and described below.









Fields in the DECS Connection DocumentThe DECS Connection Document provides values for Connectivity andTable Selection options. The fields in the DECS Connection Document aredescribed below.

Enables you to add comments to the Connection Document that help describe its intent or usage. This is a rich text field.You can paste doclinks, as well as normal text characters here.

Comment

Lists the columns defined for the specified Name.Spaces in a table or column name are not permitted.

Column(s)

Lists the available table or view defined for the specifiedOwner.A selection list displays all table or view names for the selectedOwner. Choose the table or view to connect to.If an owner is not specified, all names are listed for thespecified Selection Type.Spaces in a table or column name are not permitted.

Name

Lists the available owner names for the above table or view inthe specified Datasource. On iSeries, this lists libraries bylibrary name.A selection list displays all owners. Choose the owner of thetable or view being connected to from the list (Optional).

Owner

Specifies the metadata type for the connection.�� Select Table to connect to a database table.�� Select View to connect to a database view.Spaces in a table or column name are not permitted.

Selection Type

Specifies whether single or multiple threading will be used forthis connection.Select the single threading box if your ODBC driver does notsupport multi-threading.

Driver Threading

Specifies the password associated with the User Name. Password

Specifies the user name required to log in to the specifiedDatasource.

User Name

Specifies the name of the source ODBC database as listed inthe ODBC Administrator.

Datasource

DescriptionField


ODBC Data TypesThe following tables show the correspondences of ODBC to LEI data typesfor various types of Activities.

• (p) — Indicates that if Allow Precision Loss Only is not enabled, then anerror will be generated on the type match. Allowing precision loss is thedefault.


For more information on the organization of these tables, see the section“Notes on Connector Data Type Conversion Tables” in Chapter 3.

Note When using the IBM Client Access ODBC driver to insert data intothe DB2/400 multi-byte data types ETYPE and JTYPE, DBCS data may needto be the exact length of the external type. When storing double-bytecharacter set data to columns of these types, if the error “SQL0406 —Conversion error on assignment to column” is incorrectly generated, thenthe data being written should first be padded to the exact length of theDB2/400 column.

Note Only listed data types are supported.

ExecuteSince ODBC data sources may not support all ODBC data types in a table,the Lotus Connector for ODBC will begin with the most likely type from therelevant row in the table below and continue until it finds a type supportedin the current data source.

continued

Intprec-scale<=9, scale<=0DECIMAL

FloatDOUBLE

FloatFLOAT

FloatREAL

IntBIGINT

IntINTEGER

IntSMALLINT

IntTINYINT

IntBIT

Lotus Connector APIODBC


Binary (variable length,unbounded)

LONGVARBINARY

Binary (variable length, bound <=255)

VARBINARY

Binary (fixed length, bound <=255)

BINARY

Text (variable length,unbounded)

LONGVARCHAR

Text (variable length, bound <=254)

VARCHAR

Text (fixed length, bound <= 254)CHAR

DatetimeTIMESTAMP

DatetimeTIME

DatetimeDATE

NumericotherNUMERIC

Floatprec <= 15NUMERIC

Intprec-scale<=9, scale<=0NUMERIC

NumericOtherDECIMAL

Floatprec <= 15DECIMAL

Lotus Connector APIODBC

FetchNote that since ODBC data sources may not support all ODBC data types ina table, the Lotus Connector for ODBC will begin with the most likely typefrom the relevant row in the table below and continue until it finds a typesupported in the current data source.

continued

BIT, TINYINT, SMALLINT, INTEGER, BIGINT (p,o), REAL (o), FLOAT (o), DOUBLE (o), DECIMAL(p, o), NUMERIC (p, o)

Currency

BIT, TINYINT, SMALLINT, INTEGER, BIGINT (p),REAL, FLOAT, DOUBLE, DECIMAL (p, o),NUMERIC (p, o)

Float

BIT, TINYINT, SMALLINT, INTEGER, BIGINT (o),REAL (o), FLOAT (p, o), DOUBLE (p, o), DECIMAL(p, o), NUMERIC (p, o)

Int

ODBCLotus ConnectorAPI


Invalidnon-BLOB

CHAR, VARCHAR, LONGVARCHAR, BINARY,VARBINARY, LONGVARBINARY

BLOBBinary (o)

CHAR, VARCHAR, LONGVARCHAR, BINARY,VARBINARY, LONGVARBINARY

Text (o)

DATE, TIME, TIMESTAMPDatetime

BIT, TINYINT (p, o), SMALLINT (p, o), INTEGER(p, o), BIGINT (p, o), REAL (p, o), FLOAT (p, o),DOUBLE (p, o), DECIMAL (p, o), NUMERIC (p, o)

Numeric


Insert/UpdateNote that since ODBC data sources may not support all ODBC data types ina table, the Lotus Connector for ODBC will begin with the most likely typefrom the relevant row in the table below and continue until it finds a typesupported in the current data source.

continued

CHAR (o), VARCHAR (o), LONGVARCHAR,BINARY (o), VARBINARY (o),LONGVARBINARY

anyBinary

CHAR (o), VARCHAR (o), LONGVARCHAR,BINARY (o), VARBINARY (o),LONGVARBINARY

Text

DATE (p), TIME (o), TIMESTAMP. ForInsert/Update into a TIME col, an overflow checkis performed, not a precision check.

Datetime

BIT, TINYINT (p, o), SMALLINT (p, o), INTEGER(p, o), BIGINT (p, o), REAL (p), FLOAT (p),DOUBLE (p), DECIMAL (p, o), NUMERIC (p, o)

Numeric

BIT (p), TINYINT (p, o), SMALLINT (p, o),INTEGER(p, o), BIGINT (p, o), REAL (p), FLOAT(p, o), DOUBLE (p, o), DECIMAL (p), NUMERIC(p)

Currency

BIT (p), TINYINT (p, o), SMALLINT (p, o),INTEGER(p, o), BIGINT (p, o), REAL (p, o),FLOAT, DOUBLE, DECIMAL (p), NUMERIC (p)

Float

BIT (p), TINYINT (p, o), SMALLINT (p, o),INTEGER, BIGINT, REAL (p), FLOAT, DOUBLE,DECIMAL (p), NUMERIC (p)

Int



DATE (p), TIME (p), TIMESTAMPdatetimelist

BIT (p), TINYINT (p, o), SMALLINT (p, o),INTEGER(p, o), BIGINT (p, o), REAL (p, o),FLOAT, DOUBLE, DECIMAL (p), NUMERIC (p)

number list


CreateSince ODBC data sources may not support all ODBC data types in a table,the Lotus Connector for ODBC will begin with the most likely type from therelevant row in the table below and continue until it finds a type supportedin the current data source.

CHAR (fixed, len<=254), VARCHAR (variable,len<=254), or LONGVARCHAR (len>254)

text list

TIMESTAMP, DATE, or TIMEdatetime list

FLOAT, DOUBLE, REAL, DECIMAL, NUMERIC,or INTEGER

number list


composite

BINARY(fixed, len<=255), VARBINARY (variable,len<=255), or LONGVARBINARY (len>255)

BLOBBinary


Text

TIMESTAMP, DATE, or TIMEDatetime

NUMERIC, DECIMAL, FLOAT, DOUBLE, orINTEGER

Numeric

NUMERIC, DECIMAL, FLOAT, DOUBLE, orINTEGER

Currency

FLOAT, DOUBLE, REAL, DECIMAL, NUMERIC,or INTEGER

Float

INTEGER, SMALLINT, TINYINT, BIGINT,DECIMAL, or NUMERIC

Int



Considerations When Working with the Lotus Connector for ODBCConsider the following facts when using the Lotus Connector for ODBC.

• When using an Archive Activity, you cannot use an LEI ODBCConnection Document if you are accessing a SQL Server 7 database. Toaccess the SQL Server 7 database, use an LEI OLE DB ConnectionDocument instead.

• In order to use a Direct Transfer Activity to create metadata thatcontains more than one column of type LONG VARCHAR (ODBC typethat maps to Oracle’s LONG) you must use the Oracle 7 Connectordirectly, instead of through ODBC. Oracle does not support more thanone column of type LONG in a table or in an SQL statement.

• When using the DataDirect (formerly Merant) ODBC drivers with LEIon Solaris, connections to DB2 cannot be used in conjunction withconnections to ODBC. When this scenario is needed, the LotusConnector for ODBC must be used to connect to DB2, rather than theLotus Connector for DB2.

• The Lotus Connector for ODBC does not support the Microsoft ODBCdrivers. It does support the Lotus-branded DataDirect (formerlyMerant) 3.5 ODBC driver and the native ODBC drivers supplied withyour external system software, such as DB2 and Oracle.

• If you are using the Key Table option in a Virtual Documents activity,and connecting to ODBC using the DataDirect 3.5 drivers, you need afull version of the DataDirect drivers. Because the Key Table optionrequires two connections, a single-user license of DataDirect driverswill not be enough.

Lotus Connector for ODBC PropertiesSee the Lotus Connector LotusScript Extensions Guide for a list of propertiesfor the Lotus Connector for ODBC.



This chapter provides information about the Lotus Connector for Oracle 7,including descriptions of the fields in the Connection Document.

Introduction to the Lotus Connector for Oracle 7The Lotus Connector for Oracle 7 allows you to connect to an Oracledatabase. This chapter provides information about the Lotus Connector forOracle 7. The Lotus Connector for Oracle 7 can be used with IBM LotusEnterprise Integrator for Domino (LEI), Domino Enterprise ConnectionServices (DECS), and Lotus Connector LotusScript Extensions (LC LSX).

Regarding text formats, set the notes.ini variable “EIOracle7NativeText” toa valid Oracle code page to force the translation of all transferred Oracledata to that code page. This variable must be set with a character set nameunderstood by Oracle. Examples of values for this variable are“WE8ISO8859P1” or “JA16SJIS” or “RU8BESTA”. See the NationalLanguage Support(NLS) section in your Oracle Documentation for a list ofthe available character set names.



119

TerminologyThe table below lists LEI terms and the corresponding terms in Oracle 7.


RowRecord

ColumnField

IndexIndex

TableMetadata


Host StringServer

Oracle 7LEI

Supported CharacteristicsThe following list captures supported characteristics of the Lotus Connectorfor Oracle 7.



• Writeback index — Index strongly advised, but not required. Use thecommand “create index <indexname> on <tablename> (<column1>,<column2>, ..., <columnN>)”

• Statement syntax — Full PL/SQL syntax. To execute stored procedures,use the following syntax: “BEGIN <stored procedure> (<parm1>,<parm2>, ..., <parmN>) ; END ; ;”. Note the extra semicolon required atthe end of the statement.

• Condition syntax — Valid when placed in the following Oracle 7statement: SELECT ... WHERE <condition> ORDER BY ...

• Array transfer — Fetch, Insert


• Catalog types — Metadata, Index, Field, Procedure, Parameter




All connections have a set of properties with values that can be assignedand retrieved. See the Lotus Connector LotusScript Extensions Guide for a listof supported properties for each Connector. Also see sections “CommonConnector Properties” and “LCConnection Properties” in the LCConnectionClass chapter of that same manual.

Note In Oracle 7, a commit during a writeback operation and following anupdate unlocks the result set. Therefore, when a writeback result set isactive, the Commit Frequency property (see Transaction Options sectionlater in this chapter) is ignored and commits do not occur.

Oracle 7 Connection Document for LEIThe Oracle 7 Connection Document defines a connection to an Oracle 7database.Connection Documents enable you to define your systemconnections. They contain access information for specific databases andusers. When you create an Activity, you make connection choices from yourset of defined connections.

To create a new Oracle 7 Connection Document in LEI:



3. Select Oracle.

4. On the Oracle Connection Document, click Oracle Version and selectOracle 7.

To open an existing Oracle 7 Connection Document, select it from theConnection view on the LEI Administrator.

Chapter 8: Lotus Connector for Oracle 7 121












Specifies the password associated with the user name above.This displays as hidden text.Password encryption is described in the “Introduction to LotusConnectors” chapter.

Password

Specifies the user name required to login to the Oracledatabase.

User Name

Identifies the Oracle 7 database server. The Host String can befor either SQL*Net V1 or SQL*Net V2 depending on whatsoftware you have configured for your Oracle 7 server and LEIserver.The general format for a V1 string is:network_prefix:server_name:sid.The format for V2 consists of a single identifier: service_name.

Host String

Specifies either an Oracle 7 or Oracle 8 connection type.Oracle Version


Name

DescriptionField

Connection OptionsThe Connection Options section provides options for managing datatransactions, creating tables, and logging SQL commands. These settingshave no effect on Advanced RealTime Activities.



This is used with the option Commit Every N Operations tospecify how many actions must occur before the changes arecommitted.

Commit Frequency



�� Commit Every N Operations: Commits changesperiodically after a specified number of changes are made.This number is specified as the Commit Frequency below.


Commit Options

Select this option if you want all transactions rolled back atdisconnect time when an Activity using this connectionterminates in an error state.

Rollback uponError

DescriptionField

Table Creation Options When you select the Table Creation Options tab, the following optionsappear. The Table Creation Options section provide selections for managingtable creation.

Although Oracle 7 supplies two LONG datatypes (LONG VARCHAR2 andLONG RAW), only one LONG column per table is supported. TheConnector, rather than create all text or binary fields with no maximum sizeor with a maximum size > 2000 (VARCHAR2) for text or max size > 255 forbinary (RAW) to be LONG, it uses the following settings to specify whichcolumn will be the long column, if any, during table creation. For more information,see the section entitled, “Oracle 7 Data Types.”


Specifies that when creating metadata (tables orviews in the Oracle database), no column should becreated as a LONG type. The application insteaduses RAW or VARCHAR2 for all fields that wouldhave been created as LONG.

No Long Column

Allows you to enter the name of the column thatshould be created as LONG. All other columns willbe created as LONG will be made RAW (binary) orVARCHAR2 (text).

User Selected Column forLong Datatype

Specifies that the first LONG column will remainLONG and subsequent LONG columns will be madeeither RAW (binary) or VARCHAR2 (text).

Database Selected Columnfor Long Datatype

DescriptionField

Logging OptionsThe Logging Options section provides a feature for including SQLstatements in the Activity log.

Select this option to include in the Activity log allSQL statements generated during processing of theActivity. Note Selecting this option slows downperformance. Use it only for troubleshooting.

Output SQL Statements toLog

DescriptionField


Enables you to specify the metadata type for aconnection.�� Select Table to connect to an Oracle 7 table.�� Select View to connect to an Oracle 7 view.�� Select Procedure to connect to an Oracle 7 stored


Selection Type

DescriptionField




Column

Lists the available table, view, or procedure names defined for thespecified Owner.A selection list displays all Oracle 7 tables, views, or procedures for theselected Owner. Choose the table, view, or procedure to connect to.If an owner is not specified, all names are listed for the specifiedSelection Type.Spaces in a table or column name are not permitted.

Name

Lists the available owner names for the above table, view, or procedureselection type in the specified Database. A selection list displays all Oracle 7 owners. Choose the owner of thetable, view, or procedure being connected to from the list (Optional).

Owner

DescriptionField

Oracle 7 Connection Document for DECSThe Connection Document for Oracle 7 defines a connection to an Oracle 7database. Connection Documents enable you to define your systemconnections. They contain access information for specific databases andusers. When you create an Activity, you make connection choices fromyour set of defined connections.

To create an Oracle 7 Connection Document in DECS:



3. Choose Oracle from the dialog box.

4. Click OK.


To open an existing Oracle 7 Connection Document, select the ConnectionDocument you want from those displayed in the Connections View.


The Oracle 7 Connection Document for DECS is shown and describedbelow.









continued

Lists the available owner names for the above table, view, orprocedure selection type in the specified database. This option enables you to narrow the selection of data sourcesto a specific owner level.A selection list displays all Oracle owners. Choose the owner ofthe table, view, or procedure being connected to from the list(Optional).

Owner

Specifies the metadata type for a connection.�� Select Table to connect to an Oracle table.�� Select View to connect to an Oracle view.�� Select Procedure to connect to an Oracle stored procedure.Spaces in a table or column name are not permitted.

Selection Type

Specifies the password associated with the User Name. Thisdisplays as hidden text.

Password

Specifies the user name required to log in to the Oracle database.User Name

Specifies the service name as defined in your local tnsnames.orafile. Service names are simple names commonly used to specifythe location of database services on a network.

Host String

Specifies the version of the Oracle client to use with thisConnector.Note If you have an existing Oracle 7 Connection Documentand you change the “Oracle Version” to Oracle 8 you may getinconsistent and unexpected results.

Oracle Version

DescriptionField



Comment

Lists the columns or parameters (stored procedure) defined forthe specified Name.Spaces in a table or column name are not permitted.

Column(s)

Lists the available table, view, or procedure names defined forthe specified Owner.A selection list displays all Oracle tables, views, or proceduresfor the selected Owner. Choose the table, view, or procedure toconnect to.If an owner is not specified, all names are listed for the specifiedSelection Type.Spaces in a table or column name are not permitted.

Name

DescriptionField

Character Data Types and Key FieldsWhen you use data of type CHAR in a key field, the functionality of theOracle Connector in two scenarios must be addressed: trimming spaces andcreating an entry.

The CHAR data type in Oracle requires a fixed number of spaces for it to beidentified by the external system. Without the correct number of spaces,external records will not be found. In an LEI or DECS Virtual FieldsActivity, space trimming and padding can be problematic. Certain events(such as updating and deleting) may not be available after a CREATE eventhas been executed. When Oracle creates a field it adds space padding togive the field a fixed length. However, Notes does not add additional spacepadding to the field during the CREATE event. This prevents Notes fromlocating the record on the Oracle side.

As a result, if fixed length text fields aren’t necessary, Lotus suggests usingVARCHAR2 data types instead of CHAR data types. If you must use textfields of fixed length, use a formula filter to pad the specific field to thecorrect length. A code example for padding a field to the correct length isgiven below. This code can be used on the Notes form at the specific fieldunder “Input Translation,” in a DECS RealTime Activity document under“Options: When intercepting the creation of a document...”, or in an LEIRealTime Notes Activity document under “Intercept Document Creation.”

FIELD fieldName := fieldName;

@SetField (“fieldName”; fieldName + @Repeat (“ ”;Oracle_Column_Length — @Length(fieldName)))


For example, if the Notes field name is “CharField” and the length of theOracle CHAR column is 32, the formula would read:

FIELD CharField := CharField;

@SetField (“CharField”; CharField + @Repeat (“ ”; 32 —@Length(CharField)))

When monitoring Document Create Events, the following options areavailable:

This option executes a stored procedure in the external datasource to store data that has been entered in the document.The Virtual Fields key(s) and field(s) are supplied to thestored procedure as input parameters.To see the fields that will be passed to the stored procedure,type the stored procedure name in this field and then pressF9. The fields that will be passed to the stored procedureare displayed next to the stored procedure name.Note LEI supports stored procedure browsing.

Stored Procedure

A Notes formula language statement to execute on the newNotes document prior to the creation of a new record in theexternal database. For example:FIELD LASTNAME:=@if(LASTNAME =

““;“NA“;LASTNAME);””

Note If you are connecting to an Oracle external systemand you must use text fields of fixed length, use a formulafilter to pad the specific field to the correct length. See theOracle 7 or Oracle 8 Connector documentation for moreinformation.

Pre-Create Formula

DescriptionOption

Calling Oracle 7 Stored ProceduresWherever procedures are allowed in LEI or DECS, an Oracle 7 storedprocedure may be used. This includes DECS Virtual Fields Activities andLEI Advanced RealTime Virtual Fields Activities, as the destination of aDirect Transfer, or within an LSX script. The stored procedure being calledmust have its parameters set up correctly for the call.

Input values are provided to Oracle 7 procedures as named parameters.This requires that the parameters in Oracle 7 use the same names as theLEI/DECS fields being provided as input values. The inputs beingprovided should include key values when being used in the context of akeyed operation (selection, update, or delete context), and data values whenrelevant (insert or delete context). The input value data types provided by


the Lotus Connector for Oracle 7 are selected as the closest match to thedatatype in the LEI system, and will be converted by Oracle 7 to theprocedure parameter defined data types, as long as the conversion issupported by Oracle 7.

The Lotus Connector for Oracle 7 and Output ParametersOracle 7 differs from other RDBMS Connectors in that there is no way toreturn a result set from a procedure. Therefore, the Lotus Connector forOracle 7 supports output parameters as a way of returning results from astored procedure. This requires additional information to be available at thetime the procedure is called, specifically the context of the call and theoutput parameter names. This information will be automatically providedby LEI/DECS Activities, but must be manually specified when callingOracle 7 procedures from an LSX script. The context indicates whether theprocedure should expect and specify output parameters, and the parameternames are provided as a property of the procedure call request to the LotusConnector for Oracle 7. The output parameters must be standard datatypes; row sets may not be returned. This restricts the result set from anOracle 7 procedure to a single row. Any parameters that are indicated asinput parameters and which are also in the output parameter list will beprovided as input/output parameters.

ExampleThe following is an example of an Oracle 7 stored procedure body. This isthe format that would be required for the Open event of a Virtual FieldsActivity assuming that the key field is called NUMBER1 and the data fieldsare called NUMBER2, TEXT1, and TEXT2. In this context, the key field isthe input parameter, and the result set is expected to include the data fieldsand the key field. To accommodate the fact that one of the outputparameter names is the same as a key value in the select statement, theparameter keys should be copied to local variables to avoid scopingproblems in the procedure.

(NUMBER2 out tablename.number2%TYPE,

TEXT1 out tablename.text1%TYPE,


NUMBER1 in out tablename.number1%TYPE)

IS

BEGIN

DECLARE number1_request tablename.number1%TYPE := number1;

BEGIN


SELECT t.NUMBER2, t.TEXT1, t.TEXT2, t.NUMBER1

INTO number2, text1, text2, number1

FROM tablename t

WHERE t.NUMBER1 = number1_request;

END;

END;

Oracle 7 Data TypesThe following tables show the correspondences of Oracle 7 to LEI datatypes for various types of Activities.


• (o) — Indicates that overflow checking will be performed when data isbeing transferred. If an overflow occurs and Truncate Data WhenNecessary is enabled, then the data is truncated; if not an error isgenerated.


ExecuteThe Execute data types are listed below.

continued

Binary (variable length, unbounded)LONG RAW

Binary (variable length, bound <= 256 bytes)RAW

Text (variable length, unbounded)LONG

Text (variable length, bound <= 2000)VARCHAR2


DatetimeDATE

FloatFLOAT

NumericOther

Floatprec-scale<=15


NUMBER

Lotus Connector API Oracle 7


Binary (BLOB format) (fixed length, bound<= 255)

MLSLABEL

Binary (BLOB format) (fixed length, bound<= 255)

ROWID

Lotus Connector API Oracle 7

Note When creating or accessing any of the LEI Advanced RealTimeActivities and using the Oracle CHAR data type, do not use the AdvancedRealTime Activity option “Trim spaces on all fields.” The Oracle CHARdata type requires a fixed number of spaces in order to be correctlyidentified by the external system database. Without these spaces, theconnection to the external system database will be lost. When using aCHAR data type as a key field, you should commonly use the defaultsetting of “Trim spaces on non-key fields.”

Note Although Oracle 7 supplies two LONG datatypes (LONGVARCHAR2 and LONG RAW), only one LONG column per table issupported.

Binary data cannot start in Oracle and go to Notes. Currently, the only fieldthat can hold binary data is the rich text field, but it doesn’t understanddata that didn’t originate from Notes. RAW and LONGRAW are binarydata types. To use binary data types, the data must be inserted into theOracle table from Notes first. This technique enables the data to obtain thenecessary Notes formatting.

Note Because RAW and LONGRAW are binary data types, they must bespecified in a rich text field in the source Notes database.

FetchThe Fetch data types are listed below.

Invalidnon-BLOB

CHAR, VARCHAR2, LONG, RAW, LONGRAW, ROWID, MLSLABEL

BLOBBinary (o)

CHAR, VARCHAR2, LONG, RAW, LONGRAW, ROWID, MLSLABEL

Text (o)

DATEDatetime

FLOAT (p, o), NUMBER (p, o)Numeric

FLOAT (p, o), NUMBER (p, o)Currency

FLOAT (p), NUMBER (p)Float

FLOAT (p, o), NUMBER (p, o)Int

Oracle 7Lotus Connector API


Insert/UpdateThe Insert/Update data types are listed below.

DATE (p)datetime list

NUMBER (p), FLOAT (p)number list

CHAR (o), VARCHAR2 (o), LONG, RAW (o), LONG RAW (o), ROWID (o), MLSLABEL (o)

anyBinary

CHAR (o), VARCHAR2 (o), LONG, RAW (o), LONG RAW (o), ROWID (o), MLSLABEL (o)

Text

DATE (p)Datetime

NUMBER (p), FLOAT (p)Numeric

NUMBER (p), FLOAT (p)Currency

NUMBER (p), FLOAT (p)Float

NUMBER, FLOATInt


CreateThe Create data types are listed below.

CHAR (fixed,len<=255), VARCHAR2(255<len<=2000), or LONG (len>2000)

text list

DATEdatetime list

FLOAT (prec)number list


composite

RAW (fixed,len<=255) or LONG RAW(len>255)

BLOBBinary


Text

DATEDatetime

NUMBER (prec, scale)Numeric

NUMBER (19, 4)Currency

FLOAT (prec) or NUMBER (prec, scale)Float

NUMBER (prec,0)Int



Oracle 7 Field Mapping and NULL EntriesThe Oracle 7 CHAR/VARCHAR value has three variations. They are string(length>0), empty string, and NULL. Other Oracle 7 types can have onlytwo variations - value or NULL.

Note LEI/DECS regards a NULL as an undefined value, one that cannotbe compared to other values. NULL is thus not equivalent to an emptystring or to an empty value such as zero. For example, a replication willoccur if LEI/DECS finds a NULL in one database matching an empty valuein a replica. When this occurs, LEI/DECS uses SQL syntax to convertNULLS to values that are equivalent across databases.

For related information, see the section entitled “Processing Empty andNULL Values in LEI and DECS” in the Introduction to Connectors chapterof the guide.

Transferring Data From Oracle 7 to NotesThe following statements pertain to Oracle 7 CHAR/VARCHAR data typesand transferring data from Oracle 7 to Notes using LEI/DECS:

• If CHAR/VARCHAR contains some string (length > 0), the string willbe transferred to Notes.

• If CHAR/VARCHAR field value is an empty string, LEI/DECS willtransfer an empty value.

Transferring Data From Notes to Oracle 7The following statements pertain to the Notes text field and transferringdata from Notes to Oracle 7 using LEI/DECS:

• If the Notes text field contains a string (length > 0), the string will betransferred to Oracle 7.

• If the Notes text field is empty, an empty string will be inserted in theOracle 7 field.

• If the Notes field value exists, the value will be transferred to Oracle 7.

• If the Notes field exists but is empty, NULL will be inserted in Oracle 7.

Since the Notes client user interface does not allow you to remove a field,LEI/DECS assumes empty Notes fields to be NULL.


Transferring Data Between Oracle and NotesThe following table is helpful when transferring data between Oracle andNotes.

value (such as 12345)field does not exist

correspondingtype

value (such as12345)NULL

other types

string (such as ‘ABC’)empty string, fieldexistsfield does not exist

TEXTstring (such as‘ABC’)empty string (‘’)NULL

CHAR,VARCHAR

field valuefield typefield valuefield type

NotesOracle 7

Lotus Connector for Oracle 7 PropertiesSee the Lotus Connector LotusScript Extensions Guide for a list of propertiesfor the Lotus Connector for Oracle 7.



This chapter provides information about the Lotus Connector for Oracle 8,including descriptions of the fields in the Connection Document.

Introduction to the Lotus Connector for Oracle 8The Lotus Connector for Oracle 8 allows you to connect to an Oracle 8database. The Lotus Connector for Oracle 8 can be used with IBM LotusEnterprise Integrator for Domino (LEI), Domino Enterprise ConnectionServices (DECS), and Lotus Connector LotusScript Extensions (LC LSX).

When working with multiple text languages and text formats, set thenotes.ini variable “EIOracle8NativeText” to a valid Oracle code page toforce the translation of all transferred Oracle data to that code page. Thisvariable must be set with a character set name understood by Oracle.Examples of values for this variable are “WE8ISO8859P1” or “JA16SJIS” or“RU8BESTA”. See the National Language Support (NLS) section in yourOracle Documentation for a list of the available character set names.



TerminologyThe table below lists LEI terms and the corresponding terms in Oracle.


ViewAlt Metadata

RowRecord

ColumnField

IndexIndex

TableMetadata


Host StringServer

OracleLEI/DECS

139

Supported CharacteristicsThe following list captures supported characteristics of the Lotus Connectorfor Oracle 8.


• Writeback support — Full writeback support. The connection supportsupdatable cursors (update and remove)

• Writeback index — Index strongly advised, but not required. Use thecommand “create index <indexname> on <tablename> (<column1>,<column2>, ..., <columnN>)”

• Statement syntax — Full PL/SQL syntax. To execute stored procedures,use the following syntax: “BEGIN <stored procedure> (<parm1>,<parm2>, ..., <parmN>) ; END ;”

• Condition syntax — Valid when placed in the following Oraclestatement: SELECT ... WHERE <condition> ORDER BY ...


• Catalog types — Metadata, Index, Field, Procedure, Parameter



All connections have a set of properties with values that can be assignedand retrieved. See the Lotus Connector LotusScript Extensions Guide for a listof supported properties for each Connector. Also see the “CommonConnector Properties” and “LCConnection Properties” sections in theLCConnection Class of that same manual.

Note In Oracle 8, a commit during a cursored (writeback) operationfollowing an update unlocks the result set. Therefore, when a writebackresult set is active, the commit frequency property is ignored (commits donot occur).

Oracle 8 Connection Document for LEIThe Oracle 8 Connection Document defines a connection to an Oracle 8database. Connection Documents enable you to define your systemconnections. They contain access information for specific databases andusers. When you create an Activity, you make connection choices from yourset of defined connections.


To create a new Oracle 8 Connection Document in LEI:



3. Select Oracle.


To open an existing Oracle 8 Connection Document, select it from theConnection view on the LEI Administrator.












Enables you to override the existing text translationformat with an alternative default.Use this option to enter an alternative default Oracle textformat if the standard default results in impropertranslation. The text format must be supported by Oracle.

Alternate Default TestTranslation Format

Specifies the password associated with the user nameabove. This displays as hidden text.Password encryption is described in the “Introduction toLotus Connectors” chapter.

Password

Specifies the user name required to login to the Oracledatabase.

User Name

Specifies the Service Name as defined in your localtnsnames.ora file. Service names are simple namescommonly used to specify the location of databaseservices on a network.

Host String

Specifies the version of the Oracle Client that you want touse with this connection.Note If you have an existing Oracle 7 ConnectionDocument and you change the “Oracle Version” to Oracle8 you may get inconsistent and unexpected results.

Oracle Version

Specifies a unique name that identifies this connection.The maximum number of characters allowed is 255.

Name

DescriptionField


Connection Options The Connection Options section provides options for managing datatransactions, creating tables, and logging SQL commands. These settingshave no effect on Advanced RealTime Activities.


This is used with the option Commit Every N Operationsto specify how many actions must occur before the changesare committed.

Commit Frequency



�� Commit Every N Operations: Commits changesperiodically after a specified number of changes aremade. This number is specified as the CommitFrequency below.


Commit Options

Select this option if you want all transactions rolled back atdisconnect time when an Activity using this connectionterminates in an error state.

Rollback upon Error

DescriptionField


Logging OptionsThe Logging Options provide a feature for including any SQL statementsgenerated during an Activity to be included in the Activity log.

This option causes warnings generated during theActivity execution to be included in the Activity’slog.

Warning Reporting Option

Select this option to include in the Activity log allSQL statements generated during processing of theActivity.Note Selecting this option slows downperformance. Use it only for troubleshooting.


DescriptionField


Enables you to specify the metadata type for aconnection.�� Select Table to connect to an Oracle 8 table.�� Select View to connect to an Oracle 8 view.�� Select Procedure to connect to an Oracle 8 stored


Selection Type

DescriptionField




Column(s)

Lists the available table, view, or procedure names defined for thespecified Owner.A selection list displays all Oracle 8 tables, views, or procedures for theselected Owner. Choose the table, view, or procedure to connect to.If an owner is not specified, all names are listed for the specifiedSelection Type.Spaces in a table or column name are not permitted.

Name

Lists the available owner names for the above table, view, orprocedure selection type in the specified Database. A selection list displays all Oracle 8 owners. Choose the owner of thetable, view, or procedure being connected to from the list (Optional).

Owner

DescriptionField

Oracle 8 Connection Document for DECSThe DECS Connection Document for Oracle 8 defines a connection to anOracle 8 database. Connection Documents enable you to define yoursystem connections. They contain access information for specific databasesand users. When you create an Activity, you make connection choices fromyour set of defined connections.

To create an Oracle 8 Connection Document in DECS:



3. Choose Oracle from the dialog box.

4. Click OK.



To open an existing Oracle 8 Connection Document, select the ConnectionDocument you want from those displayed in the Connections View.

The Oracle 8 Connection Document for DECS is shown and describedbelow.







Fields in the DECS Connection DocumentThe fields in the DECS Connection Document are described below.

Specifies the metadata type for a connection.�� Select Table to connect to an Oracle table.�� Select View to connect to an Oracle view.�� Select Procedure to connect to an Oracle stored procedure.Spaces in a table or column name are not permitted.

Selection Type

Use this option to enter an alternative default Oracle text formatif the standard default results in improper translation. The textformat must be supported by Oracle.

AlternateDefault TextTranslation

Specifies the password associated with the User Name. Thisdisplays as hidden text.

Password

Specifies the user name required to login to the Oracle database.User Name

Service Name as defined in your local tnsnames.ora file. Servicenames are simple names commonly used to specify the locationof database services on a network.

Host String

Select the version of the Oracle client to use with this Connector.Note If you have an existing Oracle 7 connection documentand you change the “Oracle Version” to Oracle 8 you may getinconsistent and unexpected results.

Oracle Version

DescriptionField


Table/View/Procedure Selection The Table/View/Procedure section is described below.

Enables you to add comments to the Connection Document that help describe its intent or usage. This is a rich text field.You can paste doclinks, as well as normal text charactershere.

Comment

Lists the columns or parameters (stored procedure) definedfor the specified Name.This automatically lists the procedures or columns andcorresponding data types of the selected parameter, table, orview.Spaces in a table or column name are not permitted.

Column/Parameter

Lists the available table, view, or procedure names definedfor the specified Owner.A selection list displays all Oracle tables, views, orprocedures for the selected Owner. Choose the table, view, orprocedure to connect to.If an owner is not specified, all names are listed for thespecified Selection Type.Spaces in a table or column name are not permitted.

Name

Lists the available owner names for the above table, view, orprocedure selection type in the specified database. This option enables you to narrow the selection of datasources to a specific owner level. A selection list displays all Oracle owners. Choose the ownerof the table, view, or procedure being connected to from thelist (Optional).

Owner

DescriptionField

Character Data Types and Key FieldsWhen you use data of type CHAR in a key field, the functionality of theOracle Connector in two scenarios must be addressed: trimming spaces andcreating an entry.

The CHAR data type in Oracle requires a fixed number of spaces for it to beidentified by the external system. Without the correct number of spaces,external records will not be found. In an LEI or DECS Virtual FieldsActivity, space trimming and padding can be problematic. Certain events(such as updating and deleting) may not be available after a CREATE eventhas been executed. When Oracle creates a field it adds space padding togive the field a fixed length. However, Notes does not add additional space


padding to the field during the CREATE event. This prevents Notes fromlocating the record on the Oracle side.

As a result, if fixed length text fields aren’t necessary, Lotus suggests usingVARCHAR2 data types instead of CHAR data types. If you must use textfields of fixed length, use a formula filter to pad the specific field to thecorrect length. A code example for padding a field to the correct length isgiven below. This code can be used on the Notes form at the specific fieldunder “Input Translation,” in an DECS Virtual Fields Activity documentunder “Options: When intercepting the creation of a document...”, or in anLEI Advanced RealTime Virtual Fields Activity Document under “InterceptDocument Creation.”

FIELD fieldName := fieldName;

@SetField (“fieldName”; fieldName + @Repeat (“ ”;Oracle_Column_Length —@Length(fieldName)))

For example, if the Notes field name is “CharField” and the length of theOracle CHAR column is 32, the formula would read as follows:

FIELD CharField := CharField;

@SetField (“CharField”; CharField + @Repeat (“ ”; 32—@Length(CharField)))

Stored ProceduresWherever procedures are allowed in LEI or DECS, an Oracle storedprocedure may be used such as the destination of a Direct Transfer orwithin an LSX script. The stored procedure being called must have itsparameters set up correctly for the call.

Input values are provided to Oracle procedures as named parameters. Thisrequires that the parameters in Oracle use the same names as the LEI/DECSfields being provided as input values. The inputs being provided shouldinclude key values when being used in the context of a keyed operation(selection, update, or delete context), and data values when relevant (insertor delete context). The input value data types provided by the Oracleconnector are selected as the closest match to the data type in theLEI/DECS system, and will be converted by Oracle to the procedureparameter defined data types, as long as the conversion is supported byOracle.

Note Oracle 8 limits LONG data types to 32K for stored procedures.

Note The Lotus Connector for Oracle 8 does not support LOB data typesfor stored procedures.


Note Calling an Oracle stored procedure in a Command Activity requiresthe following syntax:BEGIN PROCNAME(); END;

The Lotus Connector for Oracle 8 and Output ParametersThe Oracle Connector supports output parameters as the way of returningresults from a stored procedure. This requires additional information to beavailable at the time the procedure is called, specifically the context of thecall and the output parameter names. This information is automaticallyprovided by LEI/DECS activities, but must be manually specified whencalling Oracle procedures from an LSX script. The context indicates whetherthe procedure should expect and specify output parameters, and theparameter names are provided as a property of the procedure call requestto the Oracle connector. The output parameters must be standard datatypes; row sets may not be returned. This restricts the result set from anOracle procedure to a single row. Any parameters that are indicated asinput parameters and which are also in the output parameter list will beprovided as input/output parameters.

Example: Oracle Stored ProcedureThe following is an example of an Oracle stored procedure body. This is theformat that would be required for the Open event of a Virtual FieldsActivity assuming that the key field is called NUMBER1 and the data fieldsare called NUMBER2, TEXT1, and TEXT2. In this context, the key field isthe input parameter, and the result set is expected to include the data fieldsand the key field. To accommodate the fact that one of the outputparameter names is the same as a key value in the select statement, theparameter keys should be copied to local variables to avoid scopingproblems in the procedure.

(NUMBER2 out tablename.number2%TYPE,



NUMBER1 in out tablename.number1%TYPE)

IS

BEGIN

DECLARE number1_request tablename.number1%TYPE := number1;

BEGIN

SELECT t.NUMBER2, t.TEXT1, t.TEXT2, t.NUMBER1

INTO number2, text1, text2, number1


FROM tablename t

WHERE t.NUMBER1 = number1_request;

END;

END;

Example: Sample LC LSX Agent to Call an Oracle Stored ProcedureThis example shows how to call an Oracle stored procedure using the LCLSX.

[Options]

Option Public

Option Explicit

Uselsx “*lsxlc”

[Initialize]

Sub Initialize

Dim sess As New LCSession

Dim conn As New LCConnection (“oracle8”)

’set the connection parameters...

conn.Server = “servername”

conn.UserId = “userid”

conn.Password = “password”

’connect to the database...

conn.Connect

’set the stored procedure owner and stored procedurename...

conn.Owner = “OWNER”

conn.Procedure = “PARM_PROC”

’set Fieldnames property with any output parametersdeclared in

the stored procedure...


conn.Fieldnames = “OUT1, OUT2”

’declare any fields and fieldlists for input/outputdata...

Dim input_fieldlist As New LCFieldList

Dim output_parms As New LCFieldlist

Dim in_field_int As New LCField (1, LCTYPE_INT)

Dim in_field_text As New LCField (1, LCTYPE_TEXT)

Dim out1 As New LCField (1, LCTYPE_INT)

Dim out2 As New LCField (1, LCTYPE_TEXT)

Dim out As Double

’set the input parameters of the stored procedure...

Set in_field_int = input_fieldlist.Append (“IN1”,LCTYPE_INT)

in_field_int.Value = 123

Set in_field_text = input_fieldlist.Append (“IN2”,LCTYPE_TEXT)

in_field_text.Text = “input”

’with the input parameters set, call the storedprocedure...

’the declared output_parms fieldlist will hold the outputparameters

of the stored procedure...

out = conn.Call (input_fieldlist, 1, output_parms)

’fetch parameter(s) into the output_parms fieldlist...

out = conn.Fetch (output_parms)

’retrieve the parameter(s) from the output_parmsfieldlist...

Set out1 = output_parms.GetField (1)

Set out2 = output_parms.GetField (2)


’use the output parameter value(s) in your script...

Print “Output parameter 1 is ” & out1.Value(0)

Print “Output parameter 2 is ” & out2.Text(0)

conn.Disconnect

End Sub

Oracle 8 Data TypesThe following tables show the correspondences of Oracle to LEI/DECS datatypes for various types of Activities.



You can specify only one LONG for each column/statement.

If you want to use BLOBs or RAWs they must originate in Notes, then beinserted into the Oracle table, and then be read back into Notes, otherwisethey will not be in a format that Notes can recognize. This is also true forLEI/DECS when a Notes database is one of the connected databases.

In Oracle 8.0.5 and earlier, CLOBs did not support multibyte varying-widthcharacter sets. However, Oracle 8i does support multibyte varying-widthcharacter sets. If you are using Oracle 8.0.5 or earlier, you can use LONG orVARCHAR2 data types instead of CLOB.



Binary (BLOB format) — variable length,unbounded

BLOB

Binary (BLOB format) — variable length,unbounded

LONG RAW

Binary (BLOB format) (variable length, bound<= 2000)

RAW

Text (variable length, unbounded)CLOB

Text (variable length, unbounded)LONG

Text (variable length, bound <= 4000)VARCHAR2


DatetimeDATE

FloatFLOAT

NumericOther

Floatprec-scale<=15


NUMBER

Lotus Connector API Oracle


BLOB/compositeBinary (o)CHAR, VARCHAR2, LONG,RAW, LONG RAW, CLOB, BLOB

Text (o)CHAR, VARCHAR2, LONG,RAW, LONG RAW, CLOB, BLOB

DatetimeDATE

NumericFLOAT (p, o), NUMBER (p, o)

CurrencyFLOAT (p, o), NUMBER (p, o)

FloatFLOAT (p), NUMBER (p)

IntFLOAT (p, o), NUMBER (p, o)

Lotus Connector API Oracle



DATE (p)datetime list

NUMBER (p), FLOAT (p)number list

CHAR (o), VARCHAR2 (o), LONG, RAW(o), LONG RAW, ROWID (o), CLOB, BLOB

anyBinary

CHAR (o), VARCHAR2 (o), LONG, RAW(o), LONG RAW, ROWID (o), CLOB, BLOB

Text

DATE (p)Datetime

NUMBER (p), FLOAT (p)Numeric

NUMBER (p), FLOAT (p)Currency

NUMBER (p), FLOAT (p)Float

NUMBER, FLOATInt

OracleLotus Connector API


CHAR (fixed, len<=2000), VARCHAR2(2000<len<=4000), or CLOB (len>4000)

text list

DATEdatetime list

FLOAT (prec)number list

CHAR (fixed, len<=2000), VARCHAR2(2000<len<=4000), or CLOB (len>4000)

composite

RAW (fixed, len<=2000) or BLOB (len>2000)BLOBBinary

CHAR (fixed, len<=2000), VARCHAR2(2000<len<=4000), or CLOB (len>=4000)

Text

DATEDatetime

NUMBER (prec, scale)Numeric

NUMBER (19, 4)Currency

FLOAT (prec) or NUMBER (prec, scale)Float

NUMBER (prec,0)Int

OracleLotus Connector API

Lotus Connector for Oracle 8 PropertiesSee the Lotus Connectors LotusScript Extensions Guide for a list of propertiesfor the Lotus Connector for Oracle 8.


Chapter 10Lotus Connector for OLE DB

This chapter provides information about the Lotus Connector for OLE DB,including descriptions of the fields in the Connection Document.

Introduction to the Lotus Connector for OLE DBThis chapter provides information about the Lotus Connector for OLE DB.It contains information about creating Microsoft SQL Server Connections.The Lotus Connector for OLE DB can be used with IBM Lotus EnterpriseIntegrator for Domino (LEI), Domino Enterprise Connection Services(DECS), and Lotus Connector LotusScript Extensions (LSX).

Use the Lotus Connector for OLE DB to connect to a Microsoft SQL serverdatabase. Since Microsoft only provides the OLE DB technology onWindows platforms, use the ODBC Connector to connect to SQL serverdatabases when LEI is installed on non-Windows platforms.

The OLE DB connector can be used with SQL Server 7/2000 and Access2000.



TerminologyThe table below lists LEI terms and the corresponding terms in OLE DB.

Record/RowRecord

Field/ColumnField

IndexIndex

Table/ViewMetadata

Database/CatalogDatabase

ProviderServer

OLE DBLEI

157

Supported CharacteristicsThe following table captures supported characteristics of the LotusConnector for OLE DB.


• Writeback support — Depending on the OLE DB provider, writebacksupport is not always available. If it is not available, it will be simulatedby the Lotus Connector for OLE DB using keyed operations. Make surethat the proper key settings and values are provided even whenperforming writeback update and remove operations.

• Writeback index — Index required for SQL server. Use the command“create index <indexname> on <tablename> (<column1>, <column2>,..., <columnN>)”.

• Statement syntax — Dependent on the OLE DB Provider. For MicrosoftSQL server Full Transact-SQL syntax is supported, including storedprocedures.

• Condition syntax — Valid when placed in the following SQL statement:SELECT ... WHERE <condition> ORDER BY



• Catalog types — Database, Metadata, Index, Field, Procedure,Parameter



Note The Database Catalog type requires a valid connection. If youattempt to use this data type without a valid connection, you will receive anerror message.



OLE DB Connection Document for LEIThe LEI Connection Document for OLE DB defines a connection to a SQLserver.

Connection Documents enable you to define your system connections. Theycontain access information for specific databases and users. When youcreate an Activity, you make connection choices from your set of definedconnections.

To create a new OLE DB Connection Document in LEI:



3. Select OLE DB.

To open an existing OLE DB Connection Document, select it from theConnection view on the LEI Administrator.

Chapter 10: Lotus Connector for OLE DB 159








Fields in the LEI Connection DocumentSee the following tables for descriptions of the LEI Connection Documentfields.



continued

Specifies the name of the SQL Server 7/2000 database that youwant to connect to. This field in not used with Access 2000providers. See the “Lotus Connector for OLE DB OperationalConsiderations” section for details.

Catalog

Specifies the network name of the server running SQL Server7/2000 or the path to the Access 2000 database (for example,“F:\Access\database.mdb”) depending on which is specifiedin the Provider field. See the “Lotus Connector for OLE DBOperational Considerations” section for details.

Data Source

Specifies the programmatic ID. For this release, the choices areAccess 2000 and SQL Server 7/2000.

Provider


Name

DescriptionField


Specifies the password associated with the user name above.Leave blank if using Windows NT Authentication. Password encryption is described in the “Introduction to LotusConnectors” chapter.

Password

Specifies the user name required to log in to the Access 2000 orSQL Server 7/2000 server. Leave blank if using Windows NTAuthentication.

User Name

Specifies user access to the database. The choices are asfollows. �� Read Only �� Read/Write �� Exclusive Read �� Only Exclusive Read/Write

Access Privileges(available only ifconnecting toAccess 2000 )

If this property is set to “SSPI”, SQLOLEDB uses Windows NTAuthentication Mode to authorize user access to the SQLserver database. If it is not set, Access 2000 or SQL Server 7/2000 server securityis used. The Access 2000 or SQL Server 7/2000 server loginand password are specified in the User Name and Passwordproperties.

AuthenticationService

Specifies any required provider string values. SQLOLEDBrecognizes an ODBC-like syntax in provider string propertyvalues. Within the string, elements are delimited by using asemicolon. The final element in the string must be terminatedwith a semicolon. Each element consists of a keyword, an equalsign character, and the value passed on initialization, forexample:Server=Gumby;UID=george;You may need to set ‘network’ to the name of the Net-Library(DLL) used to communicate with the SQL server. The nameshould not include the path or the .dll file name extension. Forexample, to use the TCP/IP network library, add thefollowing:Network=DBMSSOCN;

Alternatively, the default Net-Library can be set by the SQLServer Client Network Utility.

Provider String

DescriptionField

Connection OptionsThe Connection Options section provides options for managing datatransactions, creating tables, and logging SQL commands. These settingshave no effect on Advanced RealTime Activities.



Determines the extent that outside actions can affect a transaction.The options are as follows:�� Read Uncommitted: A transaction operating at the Read

Uncommitted level can see uncommitted changes made by othertransactions. At this level of isolation, dirty reads,non-repeatable reads, and phantoms are all possible.

�� Read Committed: A transaction operating at the ReadCommitted level cannot see changes made by other transactionsuntil those transactions are committed. At this level of isolation,dirty reads are not possible but non-repeatable reads andphantoms are possible.

�� Repeatable Read: A transaction operating at the Repeatable Readlevel is guaranteed not to see any changes made by othertransactions in values it has already read. At this level ofisolation, dirty reads and nonrepeatable reads are not possiblebut phantoms are possible.

�� Serializable: A transaction operating at the Serializable levelguarantees that all concurrent transactions interact only in waysthat produce the same effect: as if each transaction were entirelyexecuted one after the other. At this isolation level, dirty reads,nonrepeatable reads, and phantoms are not possible.

Isolationlevel

Indicates how often to commit a transaction. If set to 1, all actionsare immediately committed. If set to 0 (zero), actions are committedat disconnect. Set this option to 1 for Replication Activities.

CommitFrequency

DescriptionField


Logging Options When you select the Logging Options tab, the following options appear.The Logging Options section provides a feature for including SQLstatements in the Activity log.



DescriptionField


Enables you to specify the metadata type for aconnection.�� Select Table to connect to an OLE DB table.�� Select View to connect to an OLE DB view.�� Select Procedure to connect to an OLE DB stored


Selection Type

DescriptionField




Column

Lists the available table, view, or procedure names defined for thespecified Owner.Click the down-arrow button to select from the list of available tables,views, or procedures.A selection list displays all OLE DB tables, views, or procedures for theselected Owner. Choose the table, view, or procedure to connect to.If an owner is not specified, all names are listed for the specifiedSelection Type.Spaces in a table or column name are not permitted.

Name

Lists the available owner names for the above table, view, or procedureselection type in the specified Database. A selection list displays all OLE DB owners. Choose the owner of thetable, view, or procedure being connected to from the list (Optional).

Owner

DescriptionField

OLE DB Connection Document for DECSThe DECS Connection Document for OLE DB defines a connection to a OLEDB database. Connection Documents enable you to define your systemconnections. They contain access information for specific databases andusers. When you create an Activity, you make connection choices fromyour set of defined connections.

To create a OLE DB Connection Document in DECS:



3. Choose OLE DB from the dialog box.

4. Click OK.

To open an existing OLE DB Connection Document, select the ConnectionDocument you want from those displayed in the Connections View.

The OLE DB Connection Document for DECS is shown and describedbelow.

Note You can optionally use the User Assistant to assist you in creatingthe Connection Document. If you enable the User Assistant, the ConnectionDocument opens with explanatory text at the top of the document. Totoggle the Assistant on or off, click the “Enable/Disable Assistant” text atthe bottom of the DECS Administrator Navigator panel.



User Assistant HelpYou can optionally use the Connection Document User Assistant to assistyou in creating the Connection Document. If you enable the User Assistant,the Connection Document opens with explanatory text at the top of thedocument. To toggle the Assistant on or off, click the “Enable/DisableAssistant” text at the bottom of the DECS Administrator Navigator panel.





Fields in the DECS Connection DocumentSee the following tables for descriptions of the DECS Connection Documentfields.

Connectivity Options The Connectivity options are described below.

continued

Specifies any required provider string values. SQLOLEDBrecognizes an ODBC-like syntax in provider string propertyvalues. Within the string, elements are delimited by using asemicolon. The final element in the string must be terminatedwith a semicolon. Each element consists of a keyword, an equalsign character, and the value passed on initialization, forexample:Server=Gumby;UID=george;You may need to set ‘network’ to the name of the Net-Library(DLL) used to communicate with the SQL server. The nameshould not include the path or the .dll file name extension. Forexample, to use the TCP/IP network library, add thefollowing:Network=DBMSSOCN;Alternatively, the default Net-Library can be set by the SQLServer Client Network Utility.

Provider String

Specifies the name of the SQL Server 7/2000 database that youwant to connect to. This field in not used with Access 2000providers. See the “Lotus Connector for OLE DB OperationalConsiderations” section for details.

Catalog

Specifies the network name of the server running SQL Server7/2000 or the path to the Access 2000 database (for example,“F:\Access\database.mdb”) depending on which is specifiedin the Provider field. See the “Lotus Connector for OLE DBOperational Considerations” section for details.

Data Source

Specifies the programmatic ID. For this release, the choices areAccess 2000 and SQL Server 7/2000.

Provider

DescriptionField


Select Table/View to choose from a table or a SQL view for thetype of metadata you want.Select Procedure to choose from among stored procedures.Spaces in a table or column name are not permitted.

Selection Type

Specifies the password associated with the user name above.Password

Specifies the user name required to log in to the Access 2000 orSQL Server 7/2000 server. Leave blank if using Windows NTAuthentication.

User Name

Specifies user access to the database. The choices are asfollows. �� Read Only�� Read/Write�� Exclusive Read Only�� Exclusive Read/Write

Access Privileges(visible only ifconnecting toAccess 2000)

If this property is set to ’SSPI’, SQLOLEDB uses Windows NTAuthentication Mode to authorize user access to the SQLserver database specified by the Init Datasource and InitCatalog properties. If it is not set, Access 2000 or SQL Server 7/2000 server securityis used. The Access 2000 or SQL Server 7/2000 server loginand password are specified in the User Name and Passwordproperties.

AuthenticationService

DescriptionField

Table/View Selection or Procedure SelectionThe title of this set of options and the options themselves are dependent onwhat choice you made in “Selection Type.” See the table above for moredescription.

Lists the columns and corresponding data types from theselected table that you want to use as “metadata.”If “Procedure” was chosen as Selection Type, then this field isused to specify the parameters and corresponding data typesfor the selected procedures listed here.Spaces in a table or column name are not permitted.

Column(s)(or Parameter(s))

Specifies the name of the selected table, view, or procedure.Click the arrow button to select from a list of table, view, orprocedure owner names.Spaces in a table or column name are not permitted.

Name

Enables you to narrow the selection of data sources to aspecific owner level. Click the arrow button to select from a listof owner names.

Owner

DescriptionField


Lotus Connector for OLE DB Operational Considerations Below are some important considerations when using the Lotus Connectorfor OLE DB with the Microsoft SQL server:

• A Microsoft SQL server table that is the destination for a ReplicationActivity must have a unique index. Submit the following commandthrough ISQL or another SQL front end to create the index beforeattempting the Replication: create unique index <indexname> on <tablename> (<col1>,<col2>,..., <colN>)

Note You can use just one column or many columns, but for efficientreplication, the replication keys should be included in the index. Toremove an index, use the command: drop index <tablename>.<indexname>

• When doing timestamp replication using the LEI Replication Activity, aMicrosoft SQL server timestamp type column (an internal type) cannotbe used as the timestamp; it must be a DATETIME orSMALLDATETIME type.

• Binary is a fixed-length data type. Use this type when you expect thedata entries in a column to be exactly the same size. SQL server 7.0appends zero bits to entries where the binary data is less than thecolumn length. When this occurs, the data can no longer be read byNotes.

For example, if you have a Notes rich text field mapped to a SQL server7.0 binary type in a Advanced RealTime Virtual Fields Activity, anydata entered into Notes will be saved in SQL server 7.0. When youattempt to retrieve the data from SQL server through Notes, throughthe Virtual Fields Activity, the data will be corrupted. In this case, usethe image type instead of binary. Image is capable of handling data thatis greater than 8KB without truncation errors.

• When creating either a DECS Activity or an LEI Replication Activitywith the Lotus Connector for OLE DB, the key field should not be aTEXT, NTEXT or IMAGE datatype. These datatypes cannot be used inan ORDER BY clause or in the WHERE, HAVING, or ON clause, exceptwith the LIKE or IS NULL predicates.

Note When working with stored procedures, explicitly map all inputor output parameter field names. Also, the source field names and thestored procedure parameter names must match and be in the samesequential order.


• When creating a connection to Access 2000, you must specify thedatabase name as part of the path entered in the Data Source field onthe OLE DB Connection Document. Entering the database name in theCatalog field is not acceptable. However, when creating a connection toSQL Server, you must specify the database name in the Catalog field,not as part of the path entered in the Data Source field.

Example 1: Correct specification to example database test.mdb for anAccess 2000 connection:

Example 2: Correct specification to example SQL Server nameSQLServerN1 and table name testDB for a SQL Server connection:

Calling MS SQL Server Stored ProceduresWherever procedures are allowed, you can use a Microsoft SQL serverstored procedure such as the destination of a Direct Transfer or within anLSX script. The stored procedure being called must have its parameters setup correctly for the call.

Input values are provided to SQL procedures as named parameters. Thismeans that the parameters in SQL must use the same names as the fieldsbeing provided as input values. These inputs include key values when usedin the context of a keyed operation (selection, update, or delete context),and data values when relevant (insert or delete context). The input valuedatatypes are selected as the closest match to the datatype in LEI or DECS,and are converted by SQL to the procedure parameter defined datatypes, aslong as the conversion is supported by Microsoft SQL server.


Any output from a stored procedure must be returned through a finalSELECT statement in the procedure. The result set of this selection willbecome the result set produced by the stored procedure.

The following is an example of a Microsoft SQL server stored procedure.This is the format that would be required for the Open event of a AdvancedRealTime Virtual Fields Notes Activity assuming that the key field is calledNUMBER1 and the data fields are called NUMBER2, TEXT1, and TEXT2. Inthis context, the key field is the input parameter, and the result set isexpected to include the data fields followed by the key field.

create procedure OpenProc @NUMBER1 int

as select NUMBER2, TEXT1, TEXT2, NUMBER1 from tablename

where NUMBER1 = @NUMBER1

Note When you use a stored procedure, field mapping order in theActivity must match the order of the stored procedure’s parameters.

For example, in the following stored procedure, new data is being insertedinto a table called emp_back.

CREATE PROCEDURE DECS_CREATE @FIRSTNAME varchar(100),@LASTNAME char(100), @DEPTNO int, @HIREDATE datetime,@BIRTHDATE smalldatetime, @GRADE real, @EMPNO int as insertinto EMP_BACK (EMPNO, FIRSTNAME, LASTNAME, DEPTNO, HIREDATE,BIRTHDATE, GRADE) values (@EMPNO, @FIRSTNAME, @LASTNAME,@DEPTNO, @HIREDATE, @BIRTHDATE, @GRADE)

To reiterate, when you map fields in an Activity Document, mapping mustmatch the portion of the stored procedure that directs where the new data isto be stored.

Stored Procedure ExampleBelow is a set of stored procedures that do not pertain to the result set. Thestored procedures set is followed by an example of how the storedprocedure names should be entered in an Advanced RealTime VirtualFields Activity document.

CREATE procedure QECreateaddrbook(

@CompanyName varchar(20),

@MailDomain varchar(20),

@MailServer varchar(20),

@MailAddress varchar(20),

@MiddleInitial varchar(1),

@State varchar(20),


@FirstName varchar(20),

@LastName varchar(20))

as

INSERT INTO Venturi.addrbook(FirstName,MiddleInitial,LastName, MailDomain, MailServer,MailAddress, CompanyName,State)

VALUES

(@FirstName, @MiddleInitial, @LastName, @MailDomain,@MailServer, @MailAddress, @CompanyName, @State)

create procedure QEDeleteaddrbook (@FirstName varchar (20),@LastName varchar (20)) as DELETE FROM addrbook WHEREFirstName=@FirstName and LastName = @LastName

CREATE procedure dbo.QESelectaddrbook(@FirstNamevarchar(20),@LastName varchar(20)) as

select FirstName, MiddleInitial, LastName, MailDomain,MailServer, MailAddress, CompanyName, State fromVenturi.addrbook

WHERE FirstName = @FirstName and LastName = @LastName

CREATE procedure dbo.QEUpdateaddrbook(

@CompanyName varchar(20),

@MailDomain varchar(20),

@MailServer varchar(20),

@MiddleInitial varchar(1),

@State varchar(20),

@MailAddress varchar(20),

@FirstName varchar(20),

@LastName varchar(20))

as

UPDATE Venturi.addrbook SET

MailDomain=@MailDomain, MailServer=@MailServer,MailAddress=@MailAddress, CompanyName=@CompanyName,State=@State

WHERE

FirstName=@FirstName and LastName=@LastName


The following illustration shows how these stored procedures would bereferenced in a Virtual Fields Activity Document.



Using Stored Procedures to Approximate Output ParametersWhile the Lotus Connector for OLE DB does not support outputparameters, stored procedures can be used to generate a result setapproximating output parameter functionality. This can be an effective wayof accessing database-generated information when inserting or updatingrecords. However, the Lotus Connector for OLE DB can only retrieve oneresult set from a stored procedure and it is possible for many result sets tobe generated.

The stored procedure writer must be careful to generate only the desiredresult set. Avoid writing any stored procedure that clearly generates morethan one result set. For example, a stored procedure with two selectstatements, such as select1 in the following example, is not compatible withthe Lotus Connector for OLE DB. Using the Union operator and storingdata in local variables or temporary tables are two helpful techniques formerging multiple select statements into one.

create table oledb_test (descriptionID int, descriptionvarchar(200), updtQty int)

go

insert into oledb_test values (1,“My description”, 0)

go

create procedure select1

as

select count(*) from oledb_test

select distinct @newDescription from oledb_test

go

Insert, update, and delete statements within a stored procedure return thenumber of rows that were affected by the statement. OLE DB treats thisaffected row count as a result set. Thus, in the update1 stored procedure inthe following example, two result sets would be generated. Fortunately, theaffected row count reporting can be disabled with the Transact-SQLcommand “set nocount on.” Thus the update2 stored procedure in thefollowing example, which uses the set nocount command, causes only theresult set generated by the select statement to be returned.

Note Using set nocount in this fashion can provide additional performanceand reduced network traffic benefits. create procedure update1 (@descriptionID int, @newDescriptionvarchar(200))

as


update oledb_test

set description = @newDescription,

updtQty = updtQty + 1

where descriptionID = @descriptionID

select updtQty from oledb_test where descriptionID =@descriptionID

go

create procedure update2 (@descriptionID int, @newDescriptionvarchar(200))

as

set nocount on

update oledb_test

set description = @newDescription,

updtQty = updtQty + 1

where descriptionID = @descriptionID

set nocount off

select updtQty from oledb_test where descriptionID =@descriptionID

go

Microsoft SQL Server Data Types The following tables show the correspondences of Microsoft SQL server toLEI and DECS data types for various types of Activities.



Refer to Chapter 3, “Introduction to Lotus Connectors” for moreinformation about these tables.


Execute The Execute data types are listed below.

Binary TIMESTAMP

Binary (variable length, unbounded)IMAGE

Binary (variable length, bound <= 8000)VARBINARY

Binary (fixed length, bound <= 8000)BINARY

Text (variable length, unbounded)NTEXT

Text (variable length, bound <= 8000) NVARCHAR

Text (fixed length, bound <= 8000) NCHAR

Text (variable length, unbounded)TEXT

Text (variable length, bound <= 8000) VARCHAR

Text (fixed length, bound <= 8000) CHAR

DatetimeDATETIME

DatetimeSMALLDATETIME

CurrencyMONEY

CurrencySMALLMONEY

Text (fixed length, bound = 39)UNIQUEIDENTIFIER

NumericNUMERIC

NumericDECIMAL

FloatFLOAT

FloatREAL

IntINT

IntSMALLINT

IntTINYINT

IntBIT

Lotus Connector API Microsoft SQL Server



Text listCHAR, VARCHAR, TEXT, NCHAR,NVARCHAR, NTEXT, BINARY,VARBINARY, IMAGE, TIMESTAMPUNIQUEIDENTIFIER

Numberlist

TINYINT, SMALLINT, INT, REAL, FLOAT,DECIMAL (p, o), NUMERIC (p, o),SMALLMONEY, MONEY (p)

Datetimelist

SMALLDATETIME, DATETIME (p)

BLOBBinary (o)CHAR, VARCHAR, TEXT, BINARY,VARBINARY, IMAGE, TIMESTAMP

Text (o)CHAR, VARCHAR, TEXT, NCHAR,NVARCHAR, NTEXT, BINARY,VARBINARY, IMAGE, TIMESTAMPUNIQUEIDENTIFIER

DatetimeSMALLDATETIME, DATETIME (p)

NumericTINYINT(p, o), SMALLINT (p, o), INT (p, o),REAL (p, o), FLOAT (p, o), DECIMAL (p, o),NUMERIC (p, o), SMALLMONEY(p, o),MONEY (p, o)

CurrencyTINYINT, SMALLINT, INT, REAL (o), FLOAT(o), DECIMAL (p, o), NUMERIC (p, o),SMALLMONEY, MONEY

FloatTINYINT, SMALLINT, INT, REAL, FLOAT,DECIMAL (p, o), NUMERIC (p, o),SMALLMONEY, MONEY (p)

IntBIT, TINYINT, SMALLINT, INT

Lotus Connector APIMicrosoft SQL Server



SMALLDATETIME (p), DATETIMEdatetime list

TINYINT (p, o), SMALLINT (p, o), INT (p,o), REAL (p, o), FLOAT, DECIMAL (p, o),NUMERIC (p, o), SMALLMONEY (p, o),MONEY (p, o), CHAR (o), VARCHAR (o),TEXT, NCHAR (o), NVARCHAR (o),NTEXT

number list

CHAR (o), VARCHAR (o), TEXT, BINARY(o), VARBINARY (o), IMAGE

BLOBBinary:

CHAR (o), VARCHAR (o), TEXT, NCHAR(o), NVARCHAR (o), NTEXT, BINARY (o),VARBINARY (o), IMAGE

Text

SMALLDATETIME (p), DATETIMEDatetime

INT (p, o), REAL (p, o), FLOAT (p, o),DECIMAL (p, o), NUMERIC (p, o), CHAR(o), VARCHAR (o), NCHAR (o),NVARCHAR (o)

Numeric

INT (p, o), REAL (p, o), FLOAT (p, o),DECIMAL (p), NUMERIC (p),SMALLMONEY (p, o), MONEY, CHAR (o),VARCHAR (o), TEXT, NCHAR (o),NVARCHAR (o), NTEXT

Currency

TINYINT (p, o), SMALLINT (p, o), INT (p,o), REAL (p, o), FLOAT, DECIMAL (p, o),NUMERIC (p, o), SMALLMONEY (p, o),MONEY (p, o), CHAR (o), VARCHAR (o),TEXT, NCHAR (o), NVARCHAR (o),NTEXT

Float

BIT, TINYINT (p, o), SMALLINT (p, o), INT,REAL (p), FLOAT, DECIMAL (p),NUMERIC (p), SMALLMONEY, MONEY,CHAR (o), VARCHAR (o), TEXT, NCHAR(o), NVARCHAR (o), NTEXT

Int

Microsoft SQL ServerLotus Connector API



CHAR (fixed, len<=8000), VARCHAR(variable, len<=8000), or TEXT (len>8000)

text list

DATETIMEdatetime list

FLOATnumber list


composite

BINARY(fixed, len<=8000), VARBINARY(variable, len<=8000), or IMAGE (len>8000)

BLOBBinary:


Text

DATETIME or DATETIME4Datetime

NUMERIC (prec, scale)Numeric

MONEY, SMALLMONEYCurrency

FLOAT, or REALFloat

INT, TINYINT, SMALLINT, or BITInt

Microsoft SQL ServerLotus Connector API

Microsoft Access 2000 Data TypesThe following tables show the correspondences of Microsoft Access to LEIand DECS data types for various types of Activities.

• (p) - Indicates that if Allow Precision Loss is not enabled, then an errorwill be generated on the type match. Allowing precision loss is thedefault.

• (o) - Indicates that overflow checking will be performed when data isbeing transferred. If an overflow occurs and Truncate Data WhenNecessary is enabled, then the data is truncated; if not, an error isgenerated.

Refer to Chapter 3, “Introduction to Lotus Connectors” for moreinformation about these tables.


Execute

Binary (variable length, unbounded)LONGBINARY, OLE OBJECT

Binary (variable length, bound <= 510)VARBINARY, BINARY

Text (variable length, unbounded)LONGTEXT, MEMO, Hyperlink

Text (variable length, bound <= 255) TEXT, VARCHAR

DatetimeDATE/TIME

CurrencyCURRENCY

FloatNUMBER DOUBLE

FloatNUMBER SINGLE

IntNUMBER LONG INTEGER, COUNTER,AUTONUMBER (AutoNumber is set by FieldSize to 4, or 16 if FieldSize is set to Replication ID)

IntNUMBER INTEGER

IntNUMBER BYTE

IntBIT, YES/NO

Lotus Connector API (used by LEI andDECS)

Microsoft Access

Fetch

Binary (variable length, unbounded)LONGBINARY, OLE OBJECT

Binary (variable length, bound <= 510)VARBINARY, BINARY

Text (variable length, unbounded)LONGTEXT, MEMO, Hyperlink

Text (variable length, bound <= 255) TEXT, VARCHAR

DatetimeDATE/TIME

CurrencyCURRENCY

FloatNUMBER DOUBLE

FloatNUMBER SINGLE

IntNUMBER LONG INTEGER, COUNTER,AUTONUMBER (AutoNumber is set by FieldSize to 4, or 16 if FieldSize is set to Replication ID)

IntNUMBER INTEGER

IntNUMBER BYTE

IntBIT, YES/NO

Lotus Connector API (used by LEI and DECS)

Microsoft Access


Insert/Update

LONGBINARY, OLE OBJECTBinary(variable length, unbounded)

BINARY (o), VARBINARY (o)Binary (variable length, bound <= 510)

LONGTEXT, MEMO, HyperlinkText (variable length, unbounded)

TEXT (o), VARCHAR (o)Text (variable length, bound <= 255)

DATETIME, DATE, TIME, Datetime

CURRENCYCurrency

NUMBER SINGLE (p, o), NUMBER DOUBLEFloat

BIT, YESNO, NUMBER BYTE(o), NUMBERINTEGER(o), COUNTER, NUMBER LONGINTEGER, AUTONUMBER

Int

Microsoft AccessLotus Connector API(used by LEI and DECS)

Create

LONGBINARY, OLE OBJECTBinary(variable length, unbounded)

BINARY (o), VARBINARY (o)Binary(variable length, bound <= 510)

LONGTEXT, MEMO, HyperlinkText (variable length, unbounded)

TEXT (o), VARCHAR (o)Text (variable length, bound <= 255)

DATETIMEDatetime

CURRENCYCurrency

NUMBER SINGLE (p, o), NUMBER DOUBLEFloat

BIT, YESNO, NUMBER BYTE(o), NUMBERINTEGER(o), COUNTER, NUMBER LONGINTEGER, AUTONUMBER

Int

Microsoft AccessLotus Connector API (used by LEIand DECS)

Lotus Connector for OLE DB PropertiesSee the Lotus Connector LotusScript Extensions Guide for a list of propertiesfor the Lotus Connector for OLE DB.


Chapter 11Lotus Connector for Sybase

This chapter provides information about the Lotus Connector for Sybase,including descriptions of the fields in the Connection Document.

Introduction to the Lotus Connector for SybaseThis chapter provides information about the Lotus Connector for Sybase.The Lotus Connector for Sybase can be used with IBM Lotus EnterpriseIntegrator for Domino (LEI), Domino Enterprise Connection Services(DECS), and Lotus Connector LotusScript Extensions (LC LSX).

The Lotus Connector for Sybase allows you to connect to a Sybase database.



TerminologyThe table below lists LEI terms and the corresponding terms in Sybase.

RowRecord

ColumnField

IndexIndex

TableMetadata

DatabaseDatabase

ServerServer

SybaseLEI

Supported CharacteristicsThe following list captures supported characteristics of the Lotus Connectorfor Sybase.

For a definition of the terms used in this section, see “Supported ConnectorCharacteristics — List of Terms” in Chapter 3 of this manual. If you are

183

accessing the Connector using LotusScript, see the Lotus ConnectorLotusScript Extensions Guide for more information.

• Writeback support — Full - see Note below.

• Writeback index — Index required. Use the command “create uniqueindex <indexname> on <tablename> (<column1>, <column2>, ...,<columnN>)”

• Statement syntax — Full Transact-SQL syntax, including storedprocedures

• Condition syntax — Valid when placed in the following Sybasestatement: SELECT ... WHERE <condition> ORDER BY ..



• Catalog types — Database (no connection required), Metadata, Index,Field, Procedure, Parameter




Note Sybase requires a unique index on a table in order to create anupdateable cursor against that table. If you set the writeback property of anLCConnection, issue a non-keyed select, and then receive an error, create aunique index against that table to enable the operation to completesuccessfully.

Sybase Connection Document for LEIThe Sybase Connection Document defines a connection to a Sybasedatabase. Connection Documents enable you to define your systemconnections. They contain access information for specific databases andusers. When you create an Activity, you make connection choices from yourset of defined connections.

To create a new Sybase Connection Document in LEI:



3. Select Sybase.


To open an existing Sybase Connection Document, select it from theConnection view on the LEI Administrator.




Chapter 11: Lotus Connector for Sybase 185








Specifies the password associated with the user name above.Password encryption is described in the “Introduction to LotusConnectors” chapter.

Password

Specifies the user name required to log in to the Sybase SQLServer database.

User Name

Specifies the name of the Sybase SQL Server database.Database

Specifies the name of the Sybase SQL Server where the databaseis located.

SQL Server


Name

DescriptionField

Data Transfer OptionsWhen you select the Data Transformation tab, the following options appear.These settings have no effect on Advanced RealTime Activities.

Interprets the status code separately, not as a result set, but asan error indicator (non-zero is error, and zero is success). A Sybase stored procedure can generate a result set or return astatus code. When a non-zero code is returned, this may signalan error. The default behavior is to interpret the status as a1-row, 1-column result set.

Cursor Options:CaptureProcedure Status

Disables the use of Sybase cursors. These cursors lock the tablewhen producing a writeback result set (such as throughreplication). When modifying the table outside the cursor, suchas through an insert or timestamp replication update, theoperation can deadlock against the cursor. If this behavioroccurs, simulate cursors through keyed operations by selectingthis option.

Cursor Options:Disable Cursors

DescriptionField


Data Creation OptionsWhen you select the Data Creations Options tab, the following optionsappear. These settings have no effect on Advanced RealTime Activities.

When a Sybase table is created, Text and Binary columns longerthan 254 characters are created as Sybase Text or Imagecolumns. The long Sybase data types Text and Image areinefficient and should only be used when necessary.You can use these options to change Text and Image data typesto Char and Binary types when the database is a destinationdatabase and a table is being created.�� Never Truncate: Prevents truncation of Text and Image data

types.�� Less than 64K: Truncates all LEI Text and Binary data types

that are less than 64KB in length, but does not truncatelengths of 64KB or greater.

�� Always Truncate: Truncates all LEI Text and Binary datatypes to Sybase Char and Binary data types.

TruncateText/Image toChar/Binary

DescriptionField

Logging OptionsWhen you select the Logging Options tab, the following options appear.The Logging Options section provides a feature for including SQLstatements in the Activity log. These settings have no effect on AdvancedRealTime Activities.



DescriptionField



Enables you to specify the metadata type for a connection.�� Select Table to connect to a Sybase table.�� Select View to connect to a Sybase view.�� Select Procedure to connect to a Sybase stored procedure.Spaces in a table or column name are not permitted.

Selection Type

DescriptionField

Table OptionsThese settings display a current list of tables and allow you to specify whichtables will be accessed. You can also specify a table name not shown in thelist by selecting the Manual button.

Click this button to enter a table name not shown in the list.Manual


Column

Lists the available table, view, or procedure names defined for thespecified Owner.A selection list displays all Sybase tables, views, or procedures forthe selected Owner. Choose the table, view, or procedure toconnect to.If an owner is not specified, all names are listed for the specifiedSelection Type.Spaces in a table or column name are not permitted.

Name

Lists the available owner names for the above table, view, orprocedure selection type in the specified Database. A selection list displays all Sybase owners. Choose the owner ofthe table, view, or procedure being connected to from the list(Optional).

Owner

DescriptionField

Sybase Connection Document for DECSThe Connection Document for Sybase defines a connection to a Sybasedatabase. Connection Documents enable you to define your systemconnections. They contain access information for specific databases andusers. When you create an Activity, you make connection choices fromyour set of defined connections.


To create a Sybase Connection Document in DECS:



3. Choose Sybase from the dialog box.

4. Click OK.

To open an existing Sybase Connection Document, select the ConnectionDocument you want from those displayed in the Connections View.

The Sybase Connection Document for DECS is shown and described below.









continued

Lists the available owner names for the above table, view, orprocedure selection type in the specified Database. A selection list displays all owners. Choose the owner of the table,view, or procedure being connected to from the list (Optional).

Owner

Specifies the metadata type for the connection.�� Select Table to connect to a database table.�� Select View to connect to a database view.�� Select Procedure to connect to a stored procedure.Spaces in a table or column name are not permitted.

SelectionType

Specifies the password associated with the User Name. Password

Specifies the user name required to log in to the specified Database.User Name

Specifies the name of the Sybase SQL server database.Database

Specifies the server on which the Database resides.SQL Server

DescriptionField



Comment


Column(s)

Lists the available table, view, or procedure names defined for thespecified Owner.A selection list displays all tables, views, or procedures for theselected Owner. Choose the table, view, or procedure to connect to.If an owner is not specified, all names are listed for the specifiedSelection Type.Spaces in a table or column name are not permitted.

Name

DescriptionField

Sybase Operational ConsiderationsThis section describes several important considerations for using the LotusConnector for Sybase.

ReplicationA Sybase SQL Server table that is the destination for a Replication Activitymust have a unique index. Submit the following command through SQL oranother Sybase front end to create the index before attempting theReplication:

create unique index <indexname> on <tablename> (<col1>,<col2>,..., <colN>)

Note that you can use just one column or many columns, but for efficientreplication, the replication keys should be included in the index.

To remove an index, use the command:

drop index <tablename>.<indexname>

When doing Timestamp Replication using the LEI Replication Activity, aSybase timestamp type column (an internal type) cannot be used as thetimestamp. It must be a datetime or smalldatetime type.

Data InsertIn Activities that insert data into a Sybase table, performance improves ifthe target table does not contain columns of type Text or Image. If the targetis automatically created by LEI to contain these types, and the columns do


not have to be Text or Image, set the Connection option TruncateText/Image to Char/Binary to Always Truncate.

Troubleshooting and Supported VersionsWhen connecting to Sybase, the error “Invalid Connection” may result froman unsupported Sybase client/server version configuration. You can verifythat the Sybase client and server versions are supported in the Connectivitychapter of this manual.

Calling Sybase Stored ProceduresWherever procedures are allowed in LEI, a Sybase stored procedure may beused such as the destination of a Direct Transfer or within an LSX script.The stored procedure being called must have its parameters set up correctlyfor the call.

Input values are provided to Sybase procedures as named parameters. Thisrequires that the parameters in Sybase use the same names as theLEI/DECS fields being provided as input values. The inputs beingprovided include key values when being used in the context of a keyedoperation (selection, update, or delete context), and data values whenrelevant (insert or delete context). The input value datatypes are selected asthe closest match to the datatype in LEI/DECS. They will be converted bySybase to the procedure parameter defined datatypes, provided theconversion is supported by Sybase.

Any output from a Sybase stored procedure must be returned through afinal SELECT statement in the procedure. The result set of this selection willbecome the result set produced by the stored procedure.

The following is an example of a Sybase stored procedure. This is theformat that would be required for the Open event of an AdvancedRealTime Virtual Fields Activity assuming that the key field is calledNUMBER1 and the data fields are called NUMBER2, TEXT1, and TEXT2. Inthis context, the key field is the input parameter and the result set isexpected to include the data fields followed by the key field.

create procedure OpenProc @NUMBER1 int

as select NUMBER2, TEXT1, TEXT2, NUMBER1 from tablename

where NUMBER1 = @NUMBER1


Sybase Data TypesThe following tables show the correspondences of Sybase to LEI/DECSdata types for various types of Activities.





continued


DatetimeSMALLDATETIME

DatetimeDATETIME

CurrencySMALLMONEY

CurrencyMONEY

NumericotherNUMERIC

Floatprec <=15NUMERIC


NUMERIC

NumericotherDECIMAL

Floatprec <=15DECIMAL


DECIMAL

FloatFLOAT

FloatREAL

IntINT

IntSMALLINT

IntTINYINT

IntBIT

Lotus Connector APISybase


Binary (variable length, unbounded)IMAGE

Binary (variable length, bound <= 256)VARBINARY

Binary (fixed length, bound <= 256)BINARY

Text (variable length, unbounded)TEXT

Text (variable length, bound <= 256)NVARCHAR

Text (variable length, bound <= 256)VARCHAR

Text (fixed length, bound <= 256)NCHAR

Lotus Connector APISybase


invalidnon-BLOB

CHAR, NCHAR, VARCHAR, NVARCHAR,TEXT, BOUNDARY, BINARY, VARBINARY,IMAGE

BLOBBinary (o)

CHAR, NCHAR, VARCHAR, NVARCHAR, TEXT, BOUNDARY, SENSITIVITY, BINARY,VARBINARY, IMAGE

Text (o)

SMALLDATETIME, DATETIMEDatetime

BIT, TINYINT(p, o), SMALLINT (p, o), INT (p, o),REAL (p, o), FLOAT (p, o), DECIMAL (p, o),NUMERIC (p, o), MONEY (p, o),SMALLMONEY (p, o)

Numeric

BIT, TINYINT, SMALLINT, INT, REAL (o),FLOAT (o), DECIMAL (p, o), NUMERIC (p, o),MONEY, SMALLMONEY

Currency

BIT, TINYINT, SMALLINT, INT, REAL, FLOAT,DECIMAL (p), NUMERIC (p), MONEY (p),SMALLMONEY (p)

Float

BIT, TINYINT, SMALLINT, INT, REAL (o),FLOAT (p, o), DECIMAL (p, o), NUMERIC (p, o),MONEY (p, o), SMALLMONEY (p,o)

Int

SybaseLotus Connector API



SMALLDATETIME, DATETIMEdatetimelist

BIT (p), TINYINT (p, o), SMALLINT (p, o), INT(p, o), REAL (p, o), FLOAT, DECIMAL (p),NUMERIC (p), MONEY (p), SMALLMONEY (p)

numberlist

CHAR (o), NCHAR (0), VARCHAR (o),NVARCHAR (o), LONGCHAR, TEXT,BOUNDARY (o), SENSITIVITY (o), BINARY (o),VARBINARY (o), LONGBINARY, IMAGE

anyBinary

CHAR (o), NCHAR (0), VARCHAR (o),NVARCHAR (o), TEXT, BOUNDARY (o),BINARY (o), VARBINARY (o), IMAGE

Text


BIT (p), TINYINT (p, o), SMALLINT (p, o), INT(p, o), REAL (p), FLOAT (p, o), DECIMAL (p, o),NUMERIC (p, o), MONEY (p, o),SMALLMONEY (p, o)

Numeric

BIT (p), TINYINT (p, o), SMALLINT (p, o), INT(p, o), REAL (p), FLOAT (p, o), DECIMAL (p),NUMERIC (p), MONEY, SMALLMONEY

Currency

BIT (p), TINYINT (p, o), SMALLINT (p, o), INT(p, o), REAL (p, o), FLOAT, DECIMAL (p, o),NUMERIC (p, o), MONEY (p, o),SMALLMONEY (p, o)

Float

BIT (p), TINYINT (p, o), SMALLINT (p, o), INT,REAL (p), FLOAT, DECIMAL (p), NUMERIC(p), MONEY, SMALLMONEY

Int

SybaseLotus Connector API



CHAR (fixed, len<=256), NCHAR (fixed,len<=256), VARCHAR (variable, len<=256),NVARCHAR (variable, len<=256), TEXT(len>256)

text list

SMALLDATETIME, DATETIMEdatetime list

FLOATnumber list


composite

BINARY(fixed, len<=256), VARBINARY(variable, len<=256), or IMAGE (len>256)

BLOBBinary


Text


NUMERIC (prec, scale)Numeric

MONEY, SMALLMONEYCurrency

FLOAT, NUMERIC (prec), or REALFloat

INT, NUMERIC (prec), or BITInt

SybaseLotus ConnectorAPI

Lotus Connector for Sybase PropertiesSee the Lotus Connector LotusScript Extensions Guide for a list of propertiesfor the Lotus Connector for Sybase.


Chapter 12Lotus Connector for Text

This chapter provides information about the Lotus Connector for Text,including descriptions of the fields in the Connection Document.

Introduction to the Lotus Connector for TextThis chapter provides information about the Lotus Connector for Text. TheLotus Connector for Text can be used with IBM Lotus Enterprise Integratorfor Domino (LEI), and Lotus Connector LotusScript Extensions (LC LSX).

The Lotus Connector for Text allows data transfer between text files andLotus Connectors. You define formats for the input (source) and output(destination) data in a file, called the ZID file. The ZID file is referenced byfile name from the Text Connection form, or you can specify the actual ZIDfile contents entirely within the Text Connection form. You can also selectvarious options for processing the source and destination data and canselect internationalization of days of the week and months of the year.



Note The Lotus Connector for Text cannot be used with DominoEnterprise Connection Service (DECS) or the LEI Advanced RealTimeactivities.

Supported LEI Activities ConsiderationsThe Lotus Connector for Text does not support any browsing. It does notsupport selection criteria, keyed operations, or conditions. As a result, itcannot be used with the Archive Activity or the Advanced RealTimeActivities (Virtual Fields, Virtual Documents and Virtual Agents).

The Lotus Connector for Text supports a limited Select operation withminimal properties and no keys. This allows it to be used in combinationwith the Order Metaconnector as the source of a one-way non-timestampReplication Activity. In any other configuration, the Lotus Connector forText does not support the Replication Activity.

199

The command statement has no effect; all records are retrieved for relevantactivities, including Direct Transfer and Polling.

TerminologyThe table below lists LEI/DECS terms and the corresponding terms used bythe Lotus Connector for Text.

Record, as defined by record delimiter or record lengthRecord

Field, as defined in the information description (ZID) areaField

(Not applicable)Index

Replacement substringsMetadata

File nameDatabase

(Not applicable)Server

Lotus Connector for TextLEI/DECS

Supported CharacteristicsThe following list captures supported characteristics of the Lotus Connectorfor Text.


• Writeback support — N/A

• Writeback index — N/A

• Statement syntax — N/A — use ZID file instead

• Condition syntax — N/A



• Catalog types — None

• Create types — None

• Drop types — None



When using long file names, include the file name as is (with anyembedded spaces). Do not put quotation marks around the file name, sincethe quotation marks will be considered part of the file name.

Field Options and Text Information Definition SyntaxWhen specifying information in the ZMerge Field Specifications and Sourceand Target Options sections of the Connection Document, you will need tobe familiar with the field and format information described here.

Text fields can be read and written in fixed positions or infloating/delimited positions. Fixed position fields are determined byuser-defined start and end or by the length of column definitions.Floating/delimited fields are determined by placement before or after otherfields in the ZID file definition.

For input text data, field definitions provide a logical name for data items,decipher special format issues, and specify ultimate destination attributes.For output text data, field definitions define number and date formatting,justification, and literal string values. Allowable text formats are:

• Text (converts to and from Notes simple text or rich text)

• Numbers (including currency symbols)

• Dates (including time components)

You create a field entry in the ZID file or in the Text Field Specificationsarea for each field that you want to process.

Field entries are in the form:

<fieldname> TYPE <datatype> <field option <argument>>

where:

<fieldname>

For Source Connection AccessParentheses around any field name indicate a place holder that you do notwant assigned as a field within LEI in a destination database record. Forexample, if you are reading a file that includes a field called Publisherwhich you do not need, use the expression (Publisher) in the fieldname toomit the data.

Note <fieldname> is the database field name assigned to the data withinLEI. The <fieldname> is required.

Chapter 12: Lotus Connector for Text 201

For Target Connection Access<fieldname> is the database field name to be extracted to the destinationtext. If the field name does not exist in the specified input database, then anull value is written to the output file. The <fieldname> is required.

Use parentheses around any field name that you do not expect to be presentin the input database. This allows the provisioning of literal strings to theoutput file.

TYPE defines the field data type as specified by <datatype>. This definitionrefers to the field that is being translated. You can specify any of thefollowing values for <datatype>. The TYPE is required.

Alphanumeric text.RICHTEXT

A date/time expression. The date value must be suitable forconversion in the native machine environment.

DATETIME

Numeric text. The [.n] specifies a decimal place when a decimalis NOT present in the source data. If the [.n] is specified, the incoming data should NOT include thedecimal point. For example, input data 123.45 would failwhereas 12345 would be formatted in the output as 123.45. The“.n” can be any value in the range 0 to 15. The default is 0, or nodecimal digits.

NUMBER [.n]

Alphanumeric text. TEXT

Description<datatype>

Above, <field option> is the name of a descriptive field option whichprovides additional information about the field being read or written. The<field option> is not required.

Some field options also use <arguments> to further define the data field.

You can define multiple field options/arguments for each input field. Leavea blank space between any field option or argument.

For text input, the location of the field in the input data is critical. Thelocation of an input field is either fixed (at the same place in every inputrecord) or floating (input data is a stream of fields separated by specialdelimiters).

Note You can add ZID comment entries to a ZID script by beginning a line(the first position in a line) in the ZID script with a semicolon. For example,the following statement is a valid ZID comment entry: ; This ZID file describes the monthly update


Defining Source FilesThis section provides examples showing how to define test and binary filesthat are organized in several different ways: single line, multiple line, fixedlength fields, and floating field format.

• Text input files — Single line per record (both fixed and floating fieldsformats)

• Text input files — Multiple lines per record

• Binary input files — Fixed length records

The ZID field definition has the following syntax:

<fieldname> TYPE <datatype> <field option <argument>>

Text Input FilesData in a text file can be organized in several ways.

Single Line per RecordIn text files, a record consists of one or more fields terminated by a uniquecharacter or set of characters. Usually a record is simply a single “line” oftext terminated by a new-line-character. This one record per line format isthe most common and is easily manipulated using a Text Connection. Thefollowing example shows input data organized in the one record per lineformat.

IDNO——-NAME———————TEL———-BALANCE——PAYMENT——DATE

566238744Carol Ann Wilson 1025557746000040000980000003000010-15-93

012358743Nathan Varberg 1015552345000003000000000002500010-11-93

524135698David Fein 1015553222000035599550000010255009-30-93

This example of a customer record includes a unique ID number, thecustomer name, telephone number, balance due, payment, and date. Weuse this input data as the basis for the examples in the next sections.

Fixed Field VersionUsing the data in the above sample input file as an example, the followingexample builds the ZID field entries necessary to process the data usingLEI. For simplicity, all fields in this example are fixed, that is, they are all inthe same location in every record. In addition, for purposes of visual clarityin this example, initial caps indicate entries you make, specific to your data.

In the following example, the first line denotes the field named Type asCustomer. The first line illustrates the use of the VALUE field option for


inserting literal strings into fields. This parameter inserts “Customer” intothe Type field.

The first data field (the second line) in our example is a customer IDnumber (labeled IDNO). The IDNO field could be described as a number ora text field. Because the value here is for identification purposes and doesnot represent a quantity or magnitude, we define the IDNO field as text. Inthis example, the IDNO field always begins in column 1 (the first position inthe record) and always ends in column 9. The Connector inserts this datainto the field named IDNO.

The ZID field description in our first example look like this:

Type: TYPE TEXT VALUE “Customer”

Idno: TYPE TEXT START 01 END 9

Name: TYPE TEXT START 10 END 29

Tel: TYPE TEXT START 30 END 39

Balance: TYPE NUMBER.2 START 40 END 50

Payment: TYPE NUMBER.2 START 51 END 61

Date: TYPE DATE START 62 END 67 FORMAT MM.DD.YY

Note NUMBER.2 is the correct format as long as the input data has nodecimal point in it. If there is a decimal in the input data, then do not usethe [.2] formatting.

The START and END field options with their corresponding numeric valuesdescribe the beginning and ending position of the input fields (note thatyou could use the WIDTH or LENGTH field options instead of the ENDfield option). The decimal place (.2) notation after the TYPE NUMBERspecification tells the Text Connection how many decimal places areimplied in the input numeric value. If you do not configure the decimalplace notation, the Text Connection copies the input numeric value as aninteger.

Creating ZID field entries for date and time values is more complex thansimple TEXT or NUMBER types. Dates and times come in various formatswith unusual field separators, prefixes, and suffixes. The Text Connectionallows for these various formats, but requires that you describe the inputdate format with a special FORMAT field option specification. Notice theformat specified in the DATE field in our example.

The FORMAT field option identifies the various components of an inputdate and/or time field. In this example, M designates a month field, Ddesignates a day field, and Y designates a year field. Refer to the FORMATfield option for more information on time and data formats.


Floating Field VersionAnother typical format for input data is the floating field format. A field isconsidered to be floating if its position is determined by the end of the fieldimmediately before it in the input record. The example below shows datafrom our fixed field example as a floating field format file. Each field isseparated from the subsequent field by a comma:

IDNO,NAME,TEL,BALANCE,PAYMENT,DATE

566238744,Carol Ann Wilson,1025557746,4000098,30000,10-15-93

012358743,Nathan Varberg,1015552345,300000,25000,10-11-93

524135698,David Fein,1015553222,3559955,102550,09-30-93

For the floating field version, configure the ZID field description as follows:


Idno: TYPE TEXT UNTIL “,”

Name: TYPE TEXT UNTIL “,”

Tel: TYPE TEXT UNTIL “,”

Balance: TYPE NUMBER.2 UNTIL “,”

Payment: TYPE NUMBER.2 UNTIL “,”

Date: TYPE DATE FORMAT MM.DD.yy

The IDNO field begins in column 1 and continues until a comma isencountered in the input data. Subsequent fields are processed similarly. Inthe DATE field specification, notice that the last field in the record does nothave an UNTIL specification. The last field in a record does not need anUNTIL specification because scanning for the end of the last value in arecord always stops at the end of the data record.

Text Input Files Using Multiple Lines per RecordThe Text Connection can also read input records from multiple contiguouslines of text. A multiple line per record format requires that you specify aninput record delimiter (a unique character or string of characters) to denotethe end of one input record and the beginning of the next input record.Specify the input record delimiter in the Text Connection. The recorddelimiter string can be up to 256 characters long. Usually the input recorddelimiter is a single character such as a form feed (\f) character or aparagraph symbol (¶).


The following example shows how the first three records from the singleline example look in multiline format. The input delimiter is a singlecharacter paragraph symbol.

IDN:566238744

Nm:Carol Ann Wilson

Tel:1025557746

Bal:4000098

Pmt:30000

Date:10-15-93

¶

IDN:012358743

Nm:Nathan Varberg

Tel:1015552345

Bal:300000

Pmt:25000

Date:10-11-93

¶

IDN:524135698

Nm:David Fein

Tel:1015553222

Bal:3559955

Pmt:102550

Date:09-30-93

To translate this multilined data, configure the ZID field description asfollows:


Idno: TYPE TEXT START 5 UNTIL “\nNm:”

Name: TYPE TEXT UNTIL “\nTel:”

Tel: TYPE TEXT UNTIL “\nBal:”

Balance: TYPE NUMBER.2 “\nPmt:”

Payment: TYPE NUMBER.2 “\nDate”



Notice the differences in this example compared to the single line perrecord example. Remember we are using a record delimiter of (0x14). Weuse the escape sequence (\0x14) to specify the special character recorddelimiter string in hexadecimal notation. (Refer to the ASCII/hexadecimalequivalence chart for these values.)

The UNTIL specifications are multiple character strings, also with a specialescape sequence (\n) to allow description of the line feed characters thatdelimit the input field values. The sequence (\n) indicates a single new-linecharacter.

Remember, the input record now spans several input lines. The IDNO fieldbegins in column 5, after the “IDN:” label, and continues until the TextConnection encounters the string “\nNm:”. The Text Connection processessubsequent fields similarly. Notice, as before, in the DATE fieldspecification, the last field in the record does not have an UNTILspecification. The UNTIL specification is not needed because, whenscanning for the end of the last value in a record, the Lotus Connector forText always stops at the end of the data record.

Binary Input Files Using Fixed Length RecordsData in binary files can only be organized as fixed length records. Allrecords contain the same amount of data (number of bytes). With binaryfiles, a record consists of one or more fields of a given fixed length. Youspecify the fixed size of input binary data records with the record delimiterspecification in the Text Connection. Binary input files most closelyresemble the text fixed field format. As with the text fixed field format,fields within binary files must exist at the same location and have the samelength in every input record.

The next example shows a typical ZID field description for reading IBMhost-originated data with Text Connection. Character data from IBM hostcomputers is generally in EBCDIC format. This example shows how theText Connection can translate EBCDIC characters to ASCII text charactersduring processing. Note that the Text Connection can also translate packeddecimal data, another common format found in IBM host data, to numbertypes.


Idno: TYPE TEXT START 01 END 9 EBCDIC

Name: TYPE TEXT START 10 END 29 EBCDIC

Tel: TYPE TEXT START 30 END 39 EBCDIC

Balance: TYPE PACKED.2 START 40 END 44

Payment: TYPE PACKED.2 START 45 END 59

Date: TYPE DATE START 60 END 67 FORMAT MM.DD.YY EBCDIC


Defining Target FilesOutput records can be single or multiple line text. You can generatemultiple lines by designating carriage returns or line feeds as UNTILstrings.

Within the Lotus Connector for Text, you can define a character string toindicate the end of each output record. The Lotus Connector for Text thenuses this text string to delimit records. For example, whenever the LotusConnector for Text encounters the specific text string, it knows to end thecurrent output record and begin another. The default record delimiter is asingle new-line character (\n).

The following example depicts a sample ZID field definition for output:

(Idn): TYPE TEXT VALUE “IDN:”

Idno: TYPE TEXT START 5 UNTIL “\nNm:”

Name: TYPE TEXT UNTIL “\nTel:”

Tel: TYPE TEXT UNTIL “\nBal:”

Balance: TYPE NUMBER.2 UNTIL “\nPmt:”

Payment: TYPE NUMBER.2 UNTIL “\nDate”


As shown in the first four lines of the example, when you output documentdata you use the record delimiter to define a character to mark the end ofeach record. In this example, the escape sequence is a paragraph symbolindicated by the hexadecimal notation \0x14.

The UNTIL specifications are multiple character strings with a specialescape sequence (\n). These allow the definition of the line feed charactersthat delimit the input field values and, ultimately, create our multiple lineoutput file.

Notice, as in the input example, in the DATE field specification, the lastfield in the record does not have an UNTIL specification. The LotusConnector for Text does not require the UNTIL specification because therecord delimiter is specified and the Lotus Connector for Text places thedelimiter string at the end of each output record. Also note the decimalpoints indicated by the NUMBER.2 options used in the ZID fielddescription.

The ZID field description produces an output file as follows:

IDN:566238744

Nm:Carol Ann Wilson

Tel:1025557746


Bal:40000.98

Pmt:300.00

Date:10-15-93

¶

IDN:012358743

Nm:Nathan Varberg

Tel:1015552345

Bal:3000.00

Pmt:250.00

Date:10-11-93

¶

IDN:524135698

Nm:David Fein

Tel:1015553222

Bal:35599.55

Pmt:1025.50

Date:09-30-93

Using Field OptionsThe Text Connection allows you to use field options to describe the locationof fields in both fixed and variable records and also to format the data. Asdescribed previously, include the desired field option on the far right sideof the field entry.

Use the following field options to designate location of data in a file.

• START [nnn] or

START [@fldname] Fixed position field begin column

• WIDTH [nnn] or Fixed position field end column

• LENGTH

• END [nnn] Fixed position field end column

• UNTIL [until_string_spec] Floating field string delimiter

Use the following field options to format the text data:

• EBCDIC EBCDIC to ASCII conversion

• FORMAT Set date format or special field format


• RIGHT Output right justify

• SEPARATOR Multiple-value list delimiter

• TRIM Remove redundant white space

• VALUE Default values for input fields

More detailed information on these field options follows.

Specifying Field LocationSTART, WIDTH, END, and LENGTH numbers designate the starting andending columns of a fixed size column of data in a text file. Use START andEND when columns are aligned at a fixed column position rather thanbeing separated by specific characters. For example, if the customer IDnumber (IDNO) is a text field that always begins in column 1 and ends incolumn 9, specify the following:

IDNO: TYPE TEXT START 01 END 09.

Values can also “float” within a specified column of white space. Forexample, the field option location description of START 1 WIDTH 9indicates a value somewhere in the first nine columns of a record. Thismeans that the data in these three records has, in each case, a value of “5”.

Column position

123456789

Record 1: 5

Record 2: 5

Record 3: 5

The START @fldname syntax allows you to reset the current (start) positionwithin the input record to redefine an input area for use by other databasefields. It allows you to access portions of a field or group of fields. Forexample:

WholeField: TYPE TEXT UNTIL “,”

FirstChar: TYPE TEXT START @wholeField WIDTH 1

The WholeField is defined as a text field containing all data up to the firstcomma within the input record. The FirstChar field specification resets thecurrent field position back to the first WholeField position and, since thewidth is 1, sets the FirstChar field with only the first position of theWholeField value. The LENGTH option can be used in place of WIDTH.

UNTIL describes the character string that is used to delimit or end an inputor output text item. A field within a text file is terminated at the firstoccurrence of the UNTIL string. In the last example, the delimiter is acomma (,), and WholeField continues to the first occurrence of a comma in


the record. The specified string can contain escape sequences, such as thefollowing:

\a Alarm or bell character

\b Backspace character

\f Form feed character

\n New line character

\t Tab character

\r Carriage return

\\ Single backslash

\v Vertical tab character

\0bbb Octal conversion (where bbb is the octal number to convert to acharacter)

\0xhh Hexadecimal conversion (where hh is the hexadecimal number toconvert to a character)

\nnn Integer conversion (where nnn is the decimal number to convert to acharacter)

UNTIL is useful for fields that are separated by a single word or string. TheLotus Connector for Text scans input or output text until it encounters theUNTIL string specification. The Lotus Connector for Text scans until theend of the current logical record. However, if it does not find the specifiedUNTIL string, all data up to the very end of the logical record is placed inthe corresponding named field.

UNTIL is useful for describing quoted values separated by commas. Forexample, the following statement can be delimited by specifying UNTIL“”,“”:

“FIELD 1”, “FIELD 2”

Sometimes you want to watch for one of several different individualcharacters that can indicate the end of a field. The Lotus Connector for Textallows you to watch for a list of these individual characters with theUNTILLIST field option. The Lotus Connector for Text determines the endof a field at the first occurrence of any individual character in theUNTILLIST string.

UNTILLIST is useful for describing comma-separated values or other datafields separated by a unique character. UNTILLIST can be coded withSTART, END, and WIDTH parameters, in which case the UNTILLIST stringis only searched for within the indicated START, END, or WIDTH columns.


Note If you need to watch for several characters together, rather thanindividually, use the UNTIL field option.

Specifying Formatting OptionsThe Lotus Connector for Text supports the following script options and thefunctions they represent. Use them by placing the option name at the rightside of the field entry.

EBCDIC

EBCDIC to ASCII Conversion

The EBCDIC field option converts input fields from EBCDIC to ASCIIbefore adding the fields to a Notes document.

Note When you use EBCDIC, you must use fixed column positions withyour fields. Also, if your input is in EBCDIC format, you cannot use theUNTIL format notation.

Example: In this example, Lotus Connector for Text reads EBCDIC datafrom a tape dump and converts it to LEI text.

;EBCDIC.ZID

Type: TYPE TEXT VALUE “Stock”

Part: TYPE TEXT START 1 WIDTH 12 EBCDIC

Quantity: TYPE TEXT START 13 WIDTH 3 EBCDIC

Description: TYPE TEXT START 16 WIDTH 24 EBCDIC

FORMATUse this to set date format or special field format.

FORMAT specifies the format for an input or output field. The field can beone of several types: DATE, TEXT, or NUMBER. This section describes theuse of the FORMAT field option with each type.

FORMAT with TYPE DATEUse the format_spec for DATE fields to identify the various components ofa date and/or time field where, for dates:

M Designates a month field

N Designates a month name (for example, January, Feb, April). Amonth name must be at least three characters long to guaranteeuniqueness.

D Designates a day field


Y Designates a year field. A lower case ’y’ indicates a two-digit 20thcentury year. The Lotus Connector for Text adds 1900 to the yearvalue.

J Indicates a Julian date

W Designates a weekday name (for example, Monday). This is used inoutput only and for times:

h Designates an hour field

m Designates a minutes field

s Designates a seconds field.

A or P Indicates use of a meridian indicator (AM or PM). For example, if adate field had the following form:

02xxxMAR0315

the ZID entry could be (unrecognized characters are disregarded, so that“x” is disregarded):

Important Date: TYPE DATE BEGIN 1 WIDTH 12 FORMAT

“YYxxxxxxMMDD”

This would transform the ImportantDate field to a date with the format,“03/15/02.”

Note Only Y or y, M, N, D, J, h, m, s are recognized for formatting. Wdesignates a weekday (destination only). Other characters are ignored.

Note If you you specify a date type without a format, the date value willbe converted as described in the “Year 2000” section of Appendix A.

FORMAT with TYPE TEXT or NUMBERUse the format_spec to conditionally change values from the actual inputvalues. The syntax for conditional FORMAT specifications is:

FORMAT “a,b,c=X;d,e=Y;Z”

You can read the format specification above as:

IF the input field is equal to a, b, or c, then set value to X

ELSE if the input field is equal to d or e, then set value to Y

ELSE set value to Z

If a final ELSE clause (without compare values) is not given, then theinput value is unchanged.

Note The comparison is for the length of the compare value only, not thelength of the input field. Fields are “normalized” before comparison, soleading and trailing white space is not compared.


Example:

This example uses a variety of date and text formats for an employeerecord.

; Mon_Name2 ZID SCRIPT

;

Type: TYPE TEXT VALUE “Employees”

Name: TYPE TEXT UNTIL “,”

HireDate: TYPE DATE FORMAT NNN-DD-YY UNTIL “,”

Title: TYPE TEXT FORMAT “Pres,Pre=CEO,Man,Mgr=MGR,EMP” UNTIL“,”

Date_Of_Birth: TYPE DATE FORMAT yy-MMDD UNTIL \r\n

*

Claude Hopper,Mar-07-95,Pres,14-0904

Evander Holyfield,Jun-30-96,Man,69-0315

RIGHTUse this to right-justify output.

With output TEXT data, you can control whether the data is left or rightjustified. The default justification is left. To override this and make it rightjustification, you must do two things:

• Specify the LENGTH of the data on the output field.

• Specify RIGHT on the output field.

Note The default justification for number fields is right justification.

Example:In this example, the Lotus Connector for Text sets the length ofCompanyName, the field to be output, to 40 and specifies right justification.This results in leading white space for company names of less then 40characters in length.

; RIGHT ZID SCRIPT

;Type: TYPE TEXT VALUE “1. Customer Profile”

CompanyName: TYPE TEXT UNTIL \r\n LENGTH 40 RIGHT

CompanyAddress: TYPE TEXT UNTIL \r\n

CompanyCity: TYPE TEXT UNTIL \r\n

CompanyState: TYPE TEXT UNTIL \r\n

CompanyZip: TYPE TEXT UNTIL \r\n


CompanyPhone: TYPE TEXT UNTIL \r\n

CompanyFax: TYPE TEXT UNTIL \r\n

Body: TYPE RICH UNTIL \r\n SEP \r\n

SEPARATORUse this to enable a multiple-value list delimiter.

For non-rich text fields, SEPARATOR or “SEP” describes the charactersseparating multiple-value list items. SEP is useful for describing LotusNotes multiple-value “list-type” fields whose elements are separated by aunique character. Other database types might or might not supportmultivalue list types.

Note For non-rich text fields, the SEPARATOR option specifies a set ofcharacters that can separate multiple field elements.

For rich text fields, Lotus Connector for Text creates new rich text lines ateach occurrence of the SEPARATOR string. For example: If your separatorstring is “$$”, you would enter “$$”. The default line separator iscarriage-return and line feed characters, or “\r\n”. When the default isused, any combination of carriage-return and line feed characters creates anew line.

Note For rich text fields, SEPARATOR specifies a string of characters that,in its entirety, separates rich text lines.

Escape sequences are allowed as follows:

\a alarm or bell character

\b backspace character

\f form feed character

\n new line character

\r carriage return character

\t tab character

\v vertical tab character

\0bbb octal conversion (where bbb is the octal number toconvert)

\0xhh hexadecimal conversion (where hh is the hexadecimalnumber to convert)

\nnn integer conversion (where nnn is the decimal number toconvert)


Example:In this example, Lotus Connector for Text defines the SEP character stringas “$$,” overriding the defaults of carriage return and line feed.

; NSEP ZID SCRIPT

Type: TYPE TEXT VALUE “Letter”

Subject: TYPE TEXT UNTIL “,” VIEWKEY 1

Author: TYPE TEXT UNTIL “,”

Body: TYPE TEXT SEP “$$” UNTIL \0x0c\r\n

*

Painters Invade Monhegan Island, SWD,LINE1$$LINE2$$LINE3$$LINE4

TRIMUse this to eliminate extra white space in your input data. When the TRIMfield option is used, Lotus Connector for Text removes leading, trailing, andmultiple interspersed white space characters (blanks and tabs).

Example:

In this example, input data embedded in the ZID script has extra whitespace in it. Using the TRIM field option, Lotus Connector for Text parsesout the white space.

; TRIM ZID

Type: type text value “Stock”

Part: TYPE TEXT UNTIL “,” viewkey 1 TRIM

Quantity: TYPE TEXT UNTIL “\n”

*

Rubber Hoses ,125

Widgets and Gidgets ,255

The output will look like this:

Rubber Hoses, 125

Widgets and Gidgets, 255


VALUEUse this to set default values for input fields.

The value_spec is the default value for an input field. This is useful foradding new fields to a Notes document that have no corresponding inputfield. For example, given the ZID descriptor:

OFFICE_TITLE: TYPE TEXT VALUE “Originator”

Every document that the Lotus Connector for Text adds to or updates frominput would be given a new field, named OFFICE_TITLE, with a value of“Originator.”

Text Connection Document for LEIThe Text Connection Document defines the location and format of the textdata. Text Connections are defined as source or destination processingoptions, specifying the location and format of the data in its destination.The format and basic methodologies are the same for each specification.

Connection Documents enable you to define your system connections. Theycontain access information for specific databases and users. When youcreate an Activity, you make connection choices from your set of definedconnections.

To create a new Text Connection Document in LEI:



3. Select Text.

Note There is no Text Connection Document for DECS. In addition, theText Connection Document cannot be use with LEI Advanced RealTimeActivities.


Common Features

Each LEI Connection Document contains the following common features.





Password EncryptionThis option enables the author of a Connection Document to encryptpasswords using Notes encryption keys. See the ”Introduction to LotusConnectors" chapter for details.



Fields in the LEI Connection DocumentThis section describes the Connection Document fields.

ConnectivityThe Connectivity options enable you to create a new connection name,specify the full path of the source or destination text file, and specifywhether the connection is a source or a target.

Specifies a unique name that identifies this connection. TheName

DescriptionField


Specifies whether the connection is a source or target.Connection Type

Specifies the path of the source or destination text, forexample on Win32, C:\data\datafile.txt. When using long filenames, include the filename as is (withany embedded spaces). Do not use quotation marks in thefilename since they will be considered part of the filename.

File Name

maximum number of characters allowed is 255.

DescriptionField

Text SpecificationsThe Text Field Specification describes either the input or output data,depending on whether you are defining a source or destination form.

If the data records are variable in length, enter the delimiteryou are using. The default is \n, indicating a new line orcarriage return. This field is mutually exclusive to Fixed Record.

RecordDelimiter

If you want to override the default character set of theunderlying Connector, enter the overriding character set inthis field. For example, enter “CP392” if you wish to overridethe default character set with the CP392 character set.The default character set is the character set that is native tothe machine on which you are working.

File Text CharacterSet

Specifies the type of file you are describing in this form. Thechoices are listed below.�� Text: Specifies that the file type is text. Text files can be

composed of either fixed-length or variable records.�� Binary: Specifies that the file type is binary.By default, the Lotus Connector for Text processes files in textmode. Text mode translates each carriage return/line feedcombination to mean a new record. In certain circumstances,when records are not delimited by carriage return/ line feedcombinations, you might want the Text Connection to processthe data exactly as is with no text mode translations, andwould select binary as the file type.

File Type

DescriptionField


Fixed-length records are determined by a user-defineddecimal value that specifies the actual record length. Variablelength records are determined by a user-specified delimiter incharacter or hexadecimal notation; for example, a carriagereturn/line feed.This field is mutually exclusive to Record Delimiter.

Fixed RecordLength

DescriptionField

Connection OptionsThe Connection Options section contains the Field Specifications and theText Options tabs. It provides options for managing data transactions,creating tables, and logging SQL commands.

A Text Connection offers several options that specify how the data shouldbe processed. For example, you can request that the Connection check for aminimum input record size, strip quotation marks from input text or addquotation marks to output text, and skip a specific amount of data beforebeginning processing.

Note Source Options are used when an Activity references the TextConnection as its Source Connection. Target Options are used when anActivity references the Text Connection as its Target Connection.

Field SpecificationsWhen you select the Field Specifications tab, the following option appears.


Either reference the ZID file by name (using thesyntax: @filepath\filename.zid) or specify theactual field options.An ASCII table is provided to assist you in creatingdefinition strings. The ASCII table lists the decimal,hexadecimal, and character equivalents for theASCII character set. Supported escape sequencecharacters are indicated in red text. Characteroptions for 0-255 are available.

Specify field options, or fora ZID file, [email protected]

DescriptionField

Text Options - SourceWhen you select the Text Options tab and then the Source tab, the followingoptions appear.


Specifies the number of bytes that the Connector shouldskip before it begins processing. This is useful forignoring header information or extraneous whitecap atthe beginning of a data file. The default is 0.

Skip Bytes

Specifies the number of records that the LotusConnector for Text should skip before it beginsprocessing. This is useful for ignoring headerinformation or extraneous white space at the beginningof a data file. The default is 0.

Skip Records

Specifies the maximum record size.Maximum Record Size

Specifies the minimum record size. Use this option when you need to set a minimum inputrecord length. The default value is 1. A value of 0 indicates that no minimum record lengthexists. Specifying a value greater than 0 forces the LotusConnector for Text to bypass input records that aresmaller than the specified minimum. This feature isvery useful for bypassing junk records or blank linesthat might be present in an input text file.

Minimum Record Size

Checking this option places quotes around field valuesin the output document.Select this option if you want the Lotus Connector forText to remove quotation marks that surround inputtext. If you do not select this option, the LotusConnector for Text puts text into the document fieldsexactly as supplied.

Input Options: Checkfor Input Values WithinQuotes

DescriptionField

Text Options - TargetWhen you select the Text Options tab and then the Target tab, the followingoptions appear.


Specifies the character that you want to occupy unused orwhitecap areas in output records. If you do not enter avalue, the Lotus Connector for Text defaults to ASCIIblanks.

Fill Character/String

Selecting this option appends the data to an existing file.If you do not select this option, the Lotus Connector forText processes output text as a new file and overwritesany existing data in the file. If you elect to append thedata to an existing file, the Lotus Connector for Textwrites the string specified by the record delimiter to theoutput file before any document processing begins. If thefile does not exist, the Lotus Connector for Text createsone.

Append Data to OutputFile

Selecting this option outputs your data with surroundingquotes. If you do not select this option, the LotusConnector for Text outputs the data exactly as it exists.

Output Values WithinQuotes

DescriptionField

Text Options - ProcessingWhen you select the Text Options tab and then the Processing tab, thefollowing options appear.


The text value entered here will appear as the last entryin the output file.

Output File Trailer

The text value entered here will appear as the first entryin the output file.

Output File Header

n Bytes — Specifies that any record larger than this valuewill be handled as a composite format binary field.

Maximum Length ofSimple Text Data

Stop after n records processed — Specifies the maximumnumber of records that can be processed by a singleactivity using this connection.

Maximum RecordsProcessed

Echo ZID Field Options — Enabling this option capturesthe ZID state values in a log file. See the section entitled“Using Field Options” earlier in this chapter for relatedinformation.

ZID Field Options

DescriptionField

Text Options - InternationalWhen you select the Text Options tab and then the International tab, thefollowing options appear.

Enables you to specify the P.M. equivalent term in theexpected language of the incoming text file.

P.M. String

Enables you to specify the A.M. equivalent term in theexpected language of the incoming text file.

A.M. String

Enables you to enter the months of the year in the expectedlanguage of the incoming text file. For example, for aSpanish text file enter Enero, Febrero, Marzo, and so on.

Months of the Year

Enables you to enter the days of the week in the expectedlanguage of the incoming text file. For example, for aSpanish text file enter Domingo, Lunes, Martes, and so on.

Days of the Week

DescriptionField


Text Options - ConnectionsWhen you select the Text Options tab and then the Connections tab, thefollowing appears.

Enables you to specify a substitute string for thecurrent string. You can change the definition of fieldsin your text file by changing the values of the ZIDarea of the connection. This lets you change the valueassigned to the field to something else.

Format is current string =replacement string.

DescriptionField

Lotus Connector for Text Data TypesThe following tables show the correspondences of Lotus Connector for Textdata types to LEI data types for various types of Activity.



• Text, Number, or Time indicates single value unless otherwisespecified.

• The Lotus Connector for Text option Maximum Length for Text Dataalters the default bound of 64996 for LEI Text.



Currency

Numeric

Rich Text

allow multivaluesText (with defined SEPARATOR string)

single valueText

allow multivaluesDatetime (with defined SEPARATORstring)

single valueDateTime

allow multivaluesNumber (with defined SEPARATORstring)

single valueNumber (suffix .n for implied decimal)

Lotus Connector APIText


Texttext list

Time, Text (single value)datetime list

Number, Text (single value)number list

Text (single value), Rich Textcomposite

Text, Number allow multiple values, Timeallow multiple values, Rich Text

BLOBBinary (o)

Text, Rich Text, FormulaText (o)

DatetimeDatetime

NumericNumeric

CurrencyCurrency

NumberFloat

Number (p, o)Int

TextLotusConnector API


InsertThe Insert data types are listed below.

Text (o)text list

Time (o), Text (single value) (o)datetime list

Number (o), Text (single value) (o)number list

Text (single value) (o), Rich Textcomposite

Text (o), Number (allow multiple values) (o),Time (allow multiple values) (o), Rich Text

BLOBBinary

Text, Rich TextText

DatetimeDatetime

NumericNumeric

CurrencyCurrency

NumberFloat

NumberInt






Rich Textcomposite

Text (single value)BLOBBinary

Rich Textunbounded

Text (single value)boundedText

Time (single value)Datetime

NumericNumeric

CurrencyCurrency

Number (single value)Float

Number (single value)Int



Lotus Connector for Text PropertiesSee the Lotus Connector LotusScript Extensions Guide for a list of propertiesfor the Lotus Connector for Text.


Chapter 13Lotus Metaconnectors for LEI

This chapter provides an introduction to LEI Metaconnectors and containsinformation for creating and using the different types of Metaconnectors.

Note Metaconnector functionality is available transparently in LEIAdvanced RealTime Activities and DECS. This chapter does not apply toLEI Advanced RealTime Activities or DECS.

Introduction to MetaconnectorsA Metaconnector is a special kind of LEI Connector that providespreprocessing operations on Connector data prior to transfer within adefined activity form.

LEI supports the following Metaconnectors:

• Collapse/Expand Metaconnector — The Collapse/ExpandMetaconnector provides the capability to take multiple records from adata source table, and “Collapse” them to a single form field, andperform the reverse operation, or “Expand” the data into multiplerecords.

• Meter Metaconnector — The Metering Metaconnector provides a wayto collect statistical usage data. A Metering Metaconnection can identify and quantify data access.

• Order Metaconnector — The Order Metaconnector is useful whenordering data sets from different server sources. For example, a DB2table on an iSeries system and a Notes database on a Domino servermay use different order systems when ordering data. This can result ina data set comparison problem when using a LEI Replication Activity,which requires data sets to be ordered in parallel for data setcomparisons. The Order Metaconnector may be applied in this situationto preprocess the data sets to be compared during the activity, ensuringthe order pattern will be in parallel for accurate data set comparisonsduring the Replication Activity.

231

• Trace Metaconnector — The Trace Metaconnector allows you to traceevents associated with a specified sub connection. You may specifyoptions including where to capture data and whether or not to includea timestamp with each trace log entry. The Trace Metaconnector is atool for you and Lotus support staff to use when troubleshooting.

Once a Metaconnector is created, the Metaconnection Document can befound in the views under Connections.

You can use LEI browsing functionality within a Metaconnector. However,you must first select a metadata object (table, form, view, and/orprocedure) in every base Connector that is used with the Metaconnector. Ifbase Connectors referenced by the Metaconnector do not have metadataselected, a message appears at which time you can return to the baseconnector, select metadata, and then rebuild the Metaconnection Document.This is a requirement only if you intend to browse the Metaconnectors forfields, etc. Note that browseable fields are not editable.











Collapse/Expand MetaconnectorUse a Collapse/Expand Metaconnector to group or ungroup multiplerecords, with a common key value, into a single record with multivaluefields. The Collapse/Expand Metaconnector wraps another Connector orMetaconnector and collapses records on Fetch operations. It then expandsthem on write operations according to user-defined criteria. TheCollapse/Expand Metaconnector has no effect on metadata operations; itsimply passes through Create, Drop, and Action statements.

Since multiple records are combined into or generated from one record,writeback operations are not available. Writeback operations are simulatedwith keyed operations. When performing a writeback operation through aCollapse/Expand Metaconnector, make sure to provide the relevant keyvalues.

In all cases, a key must be defined as one or more fields. When producing aresult set or fetching data, all fields that are not part of the key are retrievedas multivalue datatypes (binary stream formats text list, number list, anddatetime list). There are no multivalue equivalents to binary datatypes. Onretrieval of data, records are fetched until the key value changes, and thenall values for each field are combined into multivalue data objects. Whenwriting data, the inverse occurs — multiple write operations are invoked(using an optional additional key field or fields for keyed operations), withthe key fields staying constant, and the multivalue fields changing on eachoperation.

It is crucial to the proper behavior of a Collapse/Expand Metaconnection toensure that any external result set is properly ordered by the grouping keys.This ordering occurs on exactly equivalent keys only; it is not possible todisregard case, even when the Order Metaconnector is used in combinationwith the Collapse/Expand Metaconnector. This ordering is accomplishedby also using the Order Metaconnector. All records with the samegrouping key field values are combined (collapsed) until a different keyvalue is encountered, so if all the equivalent keys are not returnedconsecutively, the corresponding records will not all be combined.

Chapter 13: Lotus Metaconnectors for LEI 233

Note One of the primary uses of a Collapse/Expand Metaconnection is toallow a single document in a Notes database to relate to multiple records inan external relational database. Although there are no restrictions thatrequire Notes or a relational database to be used with this Metaconnector,Notes fully supports multivalue fields, and this is the most commonscenario.

Connectivity to a Collapse/Expand MetaconnectionThere are no connectivity requirements beyond those for the underlyingconnection to which the Collapse/Expand Metaconnection is connecting.Since there is no external database for the Collapse/ExpandMetaconnection itself, there is no connectivity test.

Collapse/Expand Metaconnection DocumentTo create a new Collapse/Expand Metaconnection Document in LEI:



3. Select Metaconnection\Collapse/Expand.

To open an existing Collapse/Expand Metaconnection Document, select itfrom the Connection view on the LEI Administrator.

Note You can define multiple Metaconnections by saving them withdifferent Collapse/Expand Metaconnection names. You can also configuredifferent Collapse/Expand Metaconnections for the same Connector, andsort the Connector differently depending on the Collapse/ExpandMetaconnection chosen for use with an Activity.


Collapse/Expand Metaconnector PropertiesThe Collapse/Expand Metaconnector Properties are described below.

Disables the trimming of trailing spaces in text data.In normal operation, whenever text data is fetched from aconnection, trailing spaces are removed from the text. The propertyNoTrimText has been added to the Direct Transfer and ReplicationActivities. When using this option in a Direct Transfer or Replication Activitythat uses a Collapse/Expand Metaconnector, you must also selectthis option here in the metaconnection definition.

DisableTrimmingof TextTrailingSpaces

Specifies additional keyfield or fields which define the unique keywithin a collapsed record. For example, if four orders by a singlecustomer are collapsed into one document, with the customernumber as the key, and one order is changed, then the order numbermay be required to ensure the key’s uniqueness across individualexternal records for this customer on expansion.

AdditionalWrite Keys

Specifies the field or list of fields that define the grouping key. Oneinternal record is constructed from all external records with the samekey value. To ensure that all records with this key value arecollapsed into a single multivalue record, make sure that the externalresult set is ordered using the Order Metaconnector by the groupingkey fields. Note Grouping occurs only on exactly equal keys, it is not possibleto ignore case even if combining the Collapse/ExpandMetaconnector with the Order Metaconnector.

GroupingKeys

Specifies the name of the underlying connection that is providing thedata. This will often be an Order Metaconnector.

Connectionto Use


Name

DescriptionField

Using the Collapse/Expand Metaconnector with a Replication ActivityWhen using a Collapse/Expand Metaconnection with a ReplicationActivity, the key fields and the grouping keys need to be the same and inthe same order in the Metaconnection definition as in the ReplicationActivity definition to work properly.


Collapse/Expand Metaconnector Data TypesSince the Collapse/Expand Metaconnector has no external database, italways operates with LEI/DECS datatypes. For key fields, all LEI/DECSdatatypes convert within their class (number, datetime, or stream); inaddition, precision and overflow checking are performed as needed. Fornon-key fields, on Fetch, external single-value data types map to internalmultivalue datatypes, and vice-versa on output. Therefore, an externalnumber class type maps to a number list; a datetime to a datetime list; andtext to a text list. Note that binary data types (unformatted BLOB orformatted binary types such as composite) cannot be mapped to multivaluetypes.

For Create operations, see the underlying Connector documentation.

Meter MetaconnectorUse the Meter Metaconnector to track data flowing to and from anotherconnection or metaconnection. The Meter Metaconnector has no effect onany operations; it simply monitors the data transferred. Results from themetering are logged to a file. The specific information logged isconfigurable through use of the Meter Metaconnection Document.

Connectivity to a Meter MetaconnectionThere are no connectivity requirements beyond those required for theunderlying connection to which the Meter Metaconnection is connecting.Since there is no external database for the Meter Metaconnection itself,there is no connectivity test.

Meter Metaconnection DocumentTo create a new Meter Metaconnection Document in LEI:



3. Select Metaconnection\Meter.

To open an existing Meter Metaconnection Document, select it from theConnection view on the LEI Administrator.


Meter Metaconnector PropertiesThe Meter Metaconnector Properties are described below.

continued

Specifies the path to the meter log file.Note The meter log file is written to a directory accessible fromthe LEI server. To transfer this file into a database, follow themetering activity with a direct transfer using the Lotus Connectorfor Files to access the meter log file and any other Connector as thedestination.

Meter Filepath

Use this to generate results grouped by a particular data fieldvalue. This is an optional field containing the value to groupresults by.

Key Fieldname

Specifies how often to record subtotal results computed in numberof records. Subtotals can be printed during the process. The number specified is how many records to process to getsubtotal information. For example, if you process 1000 records andthe subtotal frequency is set to 300, you would receive 3 subtotalresults and a final tally.

SubtotalFrequency

Specifies the name of the underlying connection that is providingthe data.

Connection toUse


Name

DescriptionField


Selects the items to track at the subtotals and totals level. Theoptions are listed below.�� Track Bytes: reports the number of bytes per record�� Track Records: reports the number of records transferred�� Track Keys: reports the key field value(s) for each record�� Track Timestamp: reports the current time for each record

Total Level

Selects the items to track at the record level. The options are listedbelow:�� Track Bytes: reports the number of bytes per record�� Track Keys: reports the key field value(s) for each record�� Track Timestamp: reports the current time for each record

Record Level

DescriptionField

Supported CharacteristicsThe following list captures supported characteristics of the MeterMetaconnector.


• Connection Properties — As supported by the underlying Connector

• Standard Functionality — Full, as supported by the underlyingConnector

• Writeback Support — Full, as supported by the underlying Connector

• Writeback Index — N/A

• Statement Syntax — See the underlying Connector documentation.

• Condition Syntax — See the underlying Connector documentation.

• Connection Properties — Connector, LogRecord, LogSubtotal,LogTotal, SubtotalFrequency, KeyFieldname, MeterFilename, plusthose supported by the underlying Connector

• Array Transfer — See the underlying Connector documentation.

• Actions Supported — See the underlying Connector documentation.

• Catalog Types — See the underlying Connector documentation.

• Create Types — See the underlying Connector documentation.

• Drop Types — See the underlying Connector documentation.

All Connections have a set of properties with values that can be assignedand retrieved. See the Lotus Connector LotusScript Extensions Guide for a listof supported properties for each Connector. Also see the “Common


Connector Properties” and “LCConnection Properties” sections in theLCConnection Class chapter of that same manual.

Meter Metaconnector Data TypesSince the Meter Metaconnector has no external database, it always operateswith LEI datatypes. All LEI datatypes convert within their class (number,datetime, or stream). Precision and overflow checking are performed asneeded. For more information, see the underlying Connectordocumentation.

Order MetaconnectorUse an Order Metaconnection to obtain consistent ordering of result setsfrom other Connections. The Order Metaconnector wraps anotherConnector and orders the result set based on user-defined criteria. Orderoptions are available. The Order Metaconnector has no effect on dataoperations, other than producing a result set or fetching - it simply passesthrough Insert, Update, Remove, Create, Drop, and Action statements.

The Order Metaconnector loads and sorts the entire result set produced byits subconnector (through an Execute, Select, or Catalog operation) and thenreturns records in order for Fetch operations. Since the entire result set isloaded into memory, writeback operations are not available. Writebackoperations are simulated with keyed operations. When performing awriteback operation through an Order Metaconnection, make sure toprovide the relevant key values.

One of the primary problems solved by the Order Metaconnector is that ofdifferent sort orders during replication. For example, when replicatingbetween Oracle and Notes, there are two potential sort order problems.First, the two databases handle case sensitivity differently. Second, certainpunctuation characters are sorted differently. These differences may appearbetween any disparate databases, depending on the options selected forthat database and the data set being replicated. For more information ondatabase sort orders, contact your database system administrator.

Sort order differences may result in data that is out of sync. This results innumerous unnecessary insertions and deletions. While the end result iscorrect, the additional change operations can seriously degradeperformance or cause problems with triggers and other events. To correctthis problem, use an Order Metaconnection on both sides of the replication.Choose the same Order Metaconnection sorting options for each connection.This will replace the external databases sorting with its own consistentsorting. In addition, using the same character set for both sides of thereplication may increase efficiency.


Connectivity to an Order MetaconnectionThere are no additional requirements for connectivity beyond those of theunderlying connection to which the Order Metaconnection is connecting.Also, since there is no external database for the Order Metaconnection itself,there is no connectivity test.

Order Metaconnection DocumentTo create a new Order Metaconnection Document in LEI:



3. Select Metaconnection\Order.

To open an existing Order Metaconnection Document, select it from theConnection view on the LEI Administrator.

Note You can define multiple Order Metaconnections by saving them withdifferent Order Metaconnection names. You can also configure differentOrder Metaconnections for the same connection and sort the connectiondifferently depending on the Order Metaconnection chosen for use with anActivity.


Order Metaconnector PropertiesThe Order Metaconnector properties are described below.

Specifies how text is to be sorted. The choices are listed below.�� Sort Text as Binary�� Sort Text with Case Sensitivity�� Sort Text without Case Sensitivity

Order

Specifies whether to sort in ascending (default) or descendingorder. LEI replication depends on an ascending sorting to operateproperly. Do not use the Sort Descending option with aReplication Activity.

Sorting Options

Contains a list of fields in which to sort data. For activitieswhere ordering is specified, such as Replication, theseselections are overridden and therefore ignored in theConnector form. For other activities, this is a place to providethe ordering (which was not available before).

Sorting Fields

Specifies the optional character set to force text data into. Bydefault, the underlying Connection’s character set is used. Toprovide a character set, use the corresponding constant suffix.Character sets are listed in the Lotus Connector LotusScriptExtensions Guide. For example, for character set Code Page 932,represented by the LEI constant LCSTREAMFMT_CP932,enter “CP932” here.

Sort Character Set(optional)

Specifies the name of the underlying connection which isproviding the data.

Connection to Use


Name

DescriptionField

Using the Order Metaconnector with a Replication ActivityReplication depends on an ascending sort to operate properly. Do not usethe Sort Descending option of this Metaconnector when performingReplication Activities.

Order Metaconnector Data TypesSince the Order Metaconnector has no external database, it always operateswith LEI data types. All LEI data types convert within their class (number,datetime, or stream). Precision and overflow checking are performed asneeded.

For operations other than Result Set Production and Fetch, see theunderlying Connector documentation.


Trace MetaconnectorThe Trace Metaconnector allows you to trace events associated with aspecified sub connection. You may specify options including where tocapture data (either to the LEI console or to a user-specified file name) andwhether or not to include a timestamp with each trace log entry.

If there is a problem with your activity or connection, the TraceMetaconnector is a tool for you to use when troubleshooting. Also, traceoutput is useful for Lotus support staff when troubleshooting customercalls.

After launching an activity that uses a Trace Metaconnection, the first pieceof information seen is a “BEGIN TRACE” string along with a timestamp.The next sequence of calls is typically LCXIdentify, LCXSetProperty, andthen LCXConnect. At this point you may see a number of differentActivity-specific operations such as LCXExecute, LCXSelect, LCXInsert,LCXFetch, LCXUpdate, or LCXRemove. At the conclusion of an activityyou’ll usually see LCXDisconnect, followed by LCXTerminate, and then an“END TRACE” label.

Activity Log FileTrace information can be sent to the activity log.

Trace output using the stdout and log file methods uses carriage returns toformat some information types, such as field list data. This formatting is notpresent when using the activity log method for capturing trace output.

Note The activity log may perform with a noticeable amount of delay. Thisis caused by the disk input-output operations that are required for makingeach log entry.

Trace Metaconnection DocumentTo create a new Trace Metaconnection Document in LEI:



3. Select Metaconnection\Trace.

To open an existing Trace Metaconnection Document, select it from theConnection view on the LEI Administrator.


The Trace Metaconnection Document is shown and described below.

Trace Metaconnector PropertiesThe Trace Metaconnector properties are described below.

continued

Allows you to capture trace data to a text file. All outputcaptured to a log file is appended to the end of the file. Ifthe output file does not exist, it will be created. If the logfile cannot be opened, a message indicating this will besent to the activity log.The log file can grow quite large. You can delete the logfile when the trace data is no longer needed. The default log file name is trace.log. If you specify someother name (using the Log Filename option), such as“c:/foo/mytrace.log” on Win32, then the initial output,up to the point where the file name parameter is read,will be sent to “trace.log”, and trace output after thatpoint will be logged to the “c:/foo/mytrace.log” file.

Trace is written to afile

Specifies whether or not to write trace data to the LEIconsole window.

Trace is displayed onscreen

Names the underlying connection to be traced.Connection to Use

Specifies a unique name that identifies this connection.The maximum number of characters allowed is 255.

Name

DescriptionField


Records a timestamp with each entry that is captured inthe log file.

Record time stampwith each logged entry

Determines whether or not output will be written into theactivity log.

Trace is written to theactivity log

User-specified log file name — allows you to specify a logfile name. This option can provide more control over thetrace output destination. When a trace is started, initialization occurs followed by aseries of LCXSetProperty calls based on information fromthe Connection Document. It is only after this point thattrace data can be logged to a user-specified file: the initialtrace output is lost.

Log Filename

DescriptionField


AActivities

replication, 235, 241supported Connectors, 38, 39

Attachments, 26

CCollapse/Expand Metaconnector,

231, 233Connection Document, 234connectivity, 234data types, 236writeback operations, 233

Connection DocumentCollapse/Expand Metaconnector,

234common features, 30fields, 32introduction, 23LEI for File System Connector, 92,

96LEI for Oracle 7 Connector, 121,

140, 184, 217Meter Metaconnector, 237Order Metaconnector, 241password encryption, 30process for creating, 29process for viewing and editing,

29Trace Metaconnector, 243

Connection Documents, 28Connection pooling, 28Connectivity

Collapse/Expand Metaconnector,234

CONTEST, 4DB2 and DB2/400, 9DCTEST, 3Meter Metaconnector, 236ODBC, 16ODBC and DB2/400, 11OLE DB, 19Oracle 8, 18Order Metaconnector, 240

Sybase, 20testing, 23testing with CONTEST, 1testing with DCTEST, 1

Connectivity testingCONTEST, 65

Connectorsdata type conversion tables, 40data type terms and definitions,

27list of available, 23MetaConnectors, 24processing attachments, 26processing empty field entries, 27processing NULL entries, 26processing rich text, 25, 26support terminology, 27supported Activities, 38, 39using multiple Connectors, 24

CONTEST, 1, 4, 23, 65contest, 5ncontest.exe, 5syntax, 4

Create operationsdescription, 42

DData types

Collapse/Expand Metaconnector,236

conversion tables, 41Meter Metaconnector, 238, 239Microsoft SQL server, 176Notes Connector, 44ODBC Connector, 104, 113OLE DB Connector, 158, 176Oracle 7 Connector, 120, 133Oracle 8 Connector, 140, 154Order Metaconnector, 241Sybase Connector, 183, 194terms and definitions, 27Text Connector, 200, 226

DB2 Connection Documentfields in the DECS document, 75fields in the LEI document, 69

DECS, 74LEI, 68

DB2 ConnectorDB2 CLI, 65error logging and problem

determination, 88supported characteristics, 67using on an iSeries system, 88

DB2/400, 113DCTEST, 1

dctest, 3nlctest.exe, 3ODBC, 4syntax, 3

Documentsconnection documents, 28

Dominocluster, 57

EEncryption, 219Execute operations

description, 41

FFetch operations

description, 41Fieldlist object, 40File Connector

cannot be used with VirtualDocuments or Virtual Agents,92, 96

introduction, 91supported characteristics, 92terminology, 91

File System ConnectorConnection Document for LEI,

92, 96field mapping by position, 99, 101metadata field descriptions, 100See File Connector, 91

245

Index

IInsert/Update operations

description, 42iSeries, 9, 231

LLCTEST, 23LEI

data types, 27terminology, 27

LotusScriptprocessing attachments, 26processing empty field entries, 27processing NULL entries, 26processing rich text, 26terminology, 27

MMerant

ODBC, 16MetaConnectors

introduction, 24Meter Metaconnector, 231, 236

Connection Document, 237connectivity, 236data types, 238, 239

Microsoft SQLdata types, 176

NNotes Connection

considerations, 58Notes Connector, 43

@functions, 59considerations, 60data types, 44, 54, 60not available in DECS, 43processing attachments, 26processing rich text, 25, 26terminology, 43timestamp replication, 58virtual fields, 63

notes.iniOracle 7 native text setting, 119,

139Oracle 8 text format setting, 139

NULL character entries, 26, 27, 60

OODBC, 11

connectivity, 16testing connectivity, 16

ODBC Connector, 103Connection Document for DECS,

111data types, 104, 113DB2 client, 103Merant, 16terminology, 103

OLE DBconnectivity, 19testing connectivity, 19

OLE DB Connector, 157data types, 158, 176data types BINARY, 169Microsoft SQL Server, 169, 170ODBC Connector, 157output parameters, 175rich text fields, 169stored procedures, 170, 171terminology, 157Timestamp replication, 169

Oracle 7 Connector, 119, 139Connection Document for LEI,

121, 140, 184, 217data types, 120, 133data types binary, 134data types CHAR, 134, 136data types LONG, 134data types LONGRAW, 134data types NULL entries, 136data types RAW, 134data types VARCHAR, 136native text setting in notes.ini, 119output parameters, 132stored procedures, 131, 132terminology, 120transfer to and from Notes, 136Virtual Fields activity, 130, 131

Oracle 8connectivity, 18testing, 18

Oracle 8 Connector, 139data types, 140, 154data types BLOB, 154data types CLOB, 154data types LOB, 150data types LONG, 150, 154data types RAW, 154data types VARCHAR, 154

data types versioning, 154output parameters, 151RealTime activities, 150stored procedures, 150terminology, 139text format setting in notes.ini,

139Virtual Fields activity, 149writeback consideration, 140

Order Metaconnector, 231, 239Connection Document, 241connectivity, 240data types, 241replication, 241

Output parametersand Oracle 8 Connector, 151

Output parametersand Oracle 7 Connector, 132OLE DB Connector, 175stored procedures, 175

PPassword encryption, 30, 219

RRich text, 25, 26

SSecurity

password encryption, 219set nocount, 175Stored procedure, 33

calling external procedures, 37Oracle 7 Connector, 131Oracle 8 Connector, 150output parameters, 175result set, 38Sybase Connector, 193

Supported characteristicsDB2 Connector, 67

Sybaseconnectivity, 20testing connectivity, 21

Sybase Connector, 183data insert, 193data types, 183, 194operational considerations, 192replication, 192stored procedures, 193termininology, 183


TTables

manual name specification, 33TCP/IP, 9, 15Terminology

Notes Connector, 43ODBC Connector, 103OLE DB Connector, 157Oracle 7 Connector, 120Oracle 8 Connector, 139 Sybase Connector, 183Text Connector, 200

Text Connector, 199binary files, 207data types, 200, 226EBDIC to ASCII, 212field options, 209, 211format options, 212, 213, 215, 217input files, 205LEI Connection Document, 226Order Metaconnector, 201replication, 201source files, 203supported activities, 200syntax, 201target files, 208terminology, 200text specifications, 220text substitutions, 226

Timestampreplication, 50, 52, 53

Trace Metaconnector, 232, 242Connection Document, 243log, 243

trace.log, 243Troubleshooting

Trace Metaconnector, 242

UUser Assistant Help, 36, 111, 165

WWeb sites

DECS, x, xiLEI, xiPTFs, xi

Writebackterm definition, 27

Writeback operationsOrder Metaconnector, 239

Index 247