lotus connector lotusscript extensions guide - lotus documentation

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 orin part, 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/Courieris a trademark of Tivoli Systems and/or IBM Corporation in the United States, other countries, orboth.

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, OROTHERWISE RELATED 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.

17Sequence of Events in Connection

Pooling . . . . . . . . . . . . . . . . . . . . . . . . .

15Connection Pooling Overview . . . . . . . . . .

14Connection Pooling . . . . . . . . . . . . . . . . . . . .

10Working with the LSX . . . . . . . . . . . . . . . . . .

10LCDatetime . . . . . . . . . . . . . . . . . . . . . . . .

10LCCurrency . . . . . . . . . . . . . . . . . . . . . . . .

10LCNumeric . . . . . . . . . . . . . . . . . . . . . . . .

10LCStream . . . . . . . . . . . . . . . . . . . . . . . . .

10LCField . . . . . . . . . . . . . . . . . . . . . . . . . . .

9LCFieldlist . . . . . . . . . . . . . . . . . . . . . . . . . .

9LCConnection . . . . . . . . . . . . . . . . . . . . . . .

9LCSession . . . . . . . . . . . . . . . . . . . . . . . . . .

8LC Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7Terms and Concepts . . . . . . . . . . . . . . . . . .

6For LEI Users . . . . . . . . . . . . . . . . . . . . . . . .

6Loading and Registering the LC LSX . . . . . . . .

6Connectivity Software Requirements . . . . . .

5Overview of the LotusScript Extension for

Lotus Domino Connectors . . . . . . . . . . .

5Technical Support . . . . . . . . . . . . . . . . . . . .

5Enterprise Integrator Web Site . . . . . . . . . . .

5Contact and Support Information . . . . . . . . . . .

4Other Documentation . . . . . . . . . . . . . . . . .

3DECS Documentation . . . . . . . . . . . . . . . . .

3LEI Documentation . . . . . . . . . . . . . . . . . . .

2Related Documentation . . . . . . . . . . . . . . . . . .

1Organization of This Manual . . . . . . . . . . . . . .

11 Introduction . . . . . . . . . . . . . . . . . . . . . .

40Catalog Method for LCConnection . . . . . . . . .

38Call Method for LCConnection . . . . . . . . . . . .

36Action Method for LCConnection . . . . . . . . . .

33New Method for LCConnection . . . . . . . . . . .

32LCConnection Class Methods Summary . .

30Common Connector Properties . . . . . . . . .

30LCConnection Properties . . . . . . . . . . . . . .

29Syntax for LEI Scripted Activities . . . . . . . . . .

29Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . .

292 LCConnection Class . . . . . . . . . . . .

28For LCLSX only . . . . . . . . . . . . . . . . . . . . .

28For DECS only . . . . . . . . . . . . . . . . . . . . . .

27For LEI only . . . . . . . . . . . . . . . . . . . . . . .

26For Both LEI and DECS . . . . . . . . . . . . . . .

25NOTES.INI Variables . . . . . . . . . . . . . . . . . . .

25Multiple Row Operations . . . . . . . . . . . . .

25Tight Loops . . . . . . . . . . . . . . . . . . . . . . . .

24Locate Fields Before Looping . . . . . . . . . . .

23Connector Caching . . . . . . . . . . . . . . . . . .

23Performance . . . . . . . . . . . . . . . . . . . . . . . . . .

23Optional Parameters . . . . . . . . . . . . . . . . . . .

22Working with Multiple Rows of Data . . . . . . .

21Arrays and Indexes . . . . . . . . . . . . . . . . . . . .

20Advanced Data Types . . . . . . . . . . . . . . . .

19Standard Data Types . . . . . . . . . . . . . . . . .

19LSX Data Types . . . . . . . . . . . . . . . . . . . . . . .

19Security and Access . . . . . . . . . . . . . . . . . .

19LotusScript and Lotus Notes . . . . . . . . . . . . .

iii

Contents

92Compare Method for LCCurrency . . . . . . . . .

91Add Method for LCCurrency . . . . . . . . . . . . .

90New Method for LCCurrency . . . . . . . . . . . . .

90LCCurrency Properties . . . . . . . . . . . . . . .

90LCCurrency Class Methods Summary . . . .

90Type CURRENCY Format and Values . . . .

89Syntax for LEI Scripted Activities . . . . . . . . . .

89Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . .

893 LCCurrency Class . . . . . . . . . . . . . . .

83Update Method for LCConnection . . . . . . . . .

79SetProperty<Type> methods for

LCConnection . . . . . . . . . . . . . . . . . . . .

78SetProperty Method for LCConnection . . . . . .

76Select Method for LCConnection

for DB2 . . . . . . . . . . . . . . . . . . . . . . . . .

74Select Method for LCConnection . . . . . . . . . .

73Remove Method for LCConnection for

DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . .

70Remove Method for LCConnection . . . . . . . .

69LookupProperty Method for LCConnection . .

66ListProperty Method for LCConnection . . . . .

63Insert Method for LCConnection . . . . . . . . . .

59GetProperty<Type> Methods . . . . . . . . . . . . .

58GetProperty Method for LCConnection . . . . .

57Fetch Method for LCConnection for the

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

54Fetch Method for LCConnection . . . . . . . . . . .

53Execute Method for LCConnection . . . . . . . . .

51Drop Method for LCConnection . . . . . . . . . . .

50Disconnect Method for LCConnection . . . . . .

47Create Method for LCConnection . . . . . . . . . .

46Copy Method for LCConnection . . . . . . . . . .

45Connect Method for LCConnection . . . . . . . .

44Catalog Method for LCConnection using

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

129GetFloat Method for LCField . . . . . . . . . . . .

127GetFieldlist Method for LCField . . . . . . . . . .

126GetDatetime Method for LCField . . . . . . . . .

125GetCurrency Method for LCField . . . . . . . . .

124Copy Method for LCField . . . . . . . . . . . . . .

123Convert Method for LCField . . . . . . . . . . . .

121Compare Method for LCField . . . . . . . . . . .

120ClearVirtualCode Method for LCField . . . . .

119New Method for LCField . . . . . . . . . . . . . . .

118Processing Attachments Stored in RTF

Fields . . . . . . . . . . . . . . . . . . . . . . . . .

114LCField Class Methods and Properties

Summary . . . . . . . . . . . . . . . . . . . . . .

113Syntax for LEI Scripted Activities . . . . . . . . .

113Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .

1135 LCField Class . . . . . . . . . . . . . . . . . .

112SetCurrent Method for LCDatetime . . . . . . .

111SetConstant Method for LCDatetime . . . . . .

109GetDiff Method for LCDatetime . . . . . . . . . .

108Copy Method for LCDatetime . . . . . . . . . . .

107Compare Method for LCDatetime . . . . . . . .

106Clear Method for LCDatetime . . . . . . . . . . .

105Adjust Method for LCDatetime . . . . . . . . . .

104New Method for LCDatetime . . . . . . . . . . . .

103LCDatetime Properties Summary . . . . . . . . .

102LCDatetime Class Methods Summary . . .

102Type DATETIME Format and Values . . .

101Syntax for LEI Scripted Activities . . . . . . . . .

101Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .

1014 LCDatetime Class . . . . . . . . . . . . . .

95Example: LCCurrency with LCFieldlist and

LCField . . . . . . . . . . . . . . . . . . . . . . . . .

94Subtract Method for LCCurrency . . . . . . . . . .

93Copy Method for LCCurrency . . . . . . . . . . . .

iv Lotus Connector LotusScript Extensions Guide

166IncludeField Method for LCFieldlist . . . . . . .

165GetName Method for LCFieldlist . . . . . . . . .

163GetField Method for LCFieldlist . . . . . . . . . .

162CopyRef Method for LCFieldlist . . . . . . . . . .

160CopyField Method for LCFieldlist . . . . . . . .

159Copy Method for LCFieldlist . . . . . . . . . . . .

157Append Method for LCFieldlist . . . . . . . . . .

156New Method for LCFieldlist . . . . . . . . . . . . .

154LCFieldlist Class Methods Summary . . . .

153Fieldlist Merging and Mapping . . . . . . . .

152Accessing Field Data . . . . . . . . . . . . . . . .

152Syntax for LEI Scripted Activities . . . . . .

151Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .

1516 LCFieldlist Class . . . . . . . . . . . . . . .

149SetVirtualCode Method for LCField . . . . . . .

148SetStream Method for LCField . . . . . . . . . . .

148SetNumeric Method for LCField . . . . . . . . . .

147SetInt Method for LCField . . . . . . . . . . . . . .

146SetFormatStream Method for LCField . . . . .

144SetFormatNumber Method for LCField . . . .

143SetFormatDatetime Method for LCField . . . .

142SetFloat Method for LCField . . . . . . . . . . . .

141SetFieldlist Method for LCField . . . . . . . . . .

140SetDatetime Method for LCField . . . . . . . . .

139SetCurrency Method for LCField . . . . . . . . .

138LookupVirtualCode Method for LCField . . .

136IsNull Method for LCField . . . . . . . . . . . . . .

135GetStream Method for LCField . . . . . . . . . . .

134GetNumeric Method for LCField . . . . . . . . .

133GetInt Method for LCField . . . . . . . . . . . . . .

132GetFormatStream Method for LCField . . . . .

131GetFormatNumber Method for LCField . . . .

130GetFormatDatetime Method for LCField . . .

214Return Values . . . . . . . . . . . . . . . . . . . . .

211LookupConnector Method for LCSession . . .

207ListMetaconnector Method for LCSession . .

203ListConnector Method for LCSession . . . . . .

202GetStatusText Method for LCSession . . . . . .

200GetStatus Method for LCSession . . . . . . . . .

199ClearStatus Method for LCSession . . . . . . . .

199New Method for LCSession . . . . . . . . . . . . .

198LCSession Class Methods Summary . . . . . . .

197LCSession Class Properties Summary . . . . . .

197Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .

1978 LCSession Class . . . . . . . . . . . . . . .

195Subtract Method for LCNumeric . . . . . . . . .

194Copy Method for LCNumeric . . . . . . . . . . . .

193Compare Method for LCNumeric . . . . . . . . .

192Add Method for LCNumeric . . . . . . . . . . . .

191New Method for LCNumeric . . . . . . . . . . . .

190LCNumeric Class Methods Summary . . .

190LCNumeric Class Properties Summary . .

190Type NUMERIC Format and Values . . . .


189Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .

1897 LCNumeric Class . . . . . . . . . . . . . .

186SetName Method for LCFieldlist . . . . . . . . .

184Replace Method for LCFieldlist . . . . . . . . . .

182Remove Method for LCFieldlist . . . . . . . . . .

181MergeVirtual Method for LCFieldlist . . . . . .

178Merge Method for LCFieldlist . . . . . . . . . . .

175MapName Method for LCFieldlist . . . . . . . .

173Map Method for LCFieldlist . . . . . . . . . . . . .

172Lookup Method for LCFieldlist . . . . . . . . . .

170List Method for LCFieldlist . . . . . . . . . . . . .

168Insert Method for LCFieldlist . . . . . . . . . . . .

Contents v

244NumberListGetRange Method for LCStream

243DatetimeListRemoveValue Method for

LCStream . . . . . . . . . . . . . . . . . . . . . .

242DatetimeListRemoveRange Method for

LCStream . . . . . . . . . . . . . . . . . . . . . .

241DatetimeListInsertValue Method for

LCStream . . . . . . . . . . . . . . . . . . . . . .

240DatetimeListInsertRange Method for

LCStream . . . . . . . . . . . . . . . . . . . . . .

238DatetimeListGetValue Method for LCStream

237Parameters . . . . . . . . . . . . . . . . . . . . . . .

237DatetimeListGetRange Method for LCStream

236Trim Method for LCStream . . . . . . . . . . . . .

236SetFormat Method for LCStream . . . . . . . . .

234ResetFormat Method for LCStream . . . . . . .

233Merge Method for LCStream . . . . . . . . . . . .

232Extract Method for LCStream . . . . . . . . . . . .

231Copy Method for LCStream . . . . . . . . . . . . .

230Convert Method for LCStream . . . . . . . . . . .

228Compare Method for LCStream . . . . . . . . . .

227Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . .

227Append Method for LCStream . . . . . . . . . . .

227Clear Method for LCStream . . . . . . . . . . . . .

225New Method for LCStream . . . . . . . . . . . . .

224LCStream Properties . . . . . . . . . . . . . . . .

223Stream Format . . . . . . . . . . . . . . . . . . . . .

223Stream Flags . . . . . . . . . . . . . . . . . . . . . .

222LCStream Type BINARY Format and Values

222LCStream Type TEXT Format and Values . .


221Overview . . . . . . . . . . . . . . . . . . . . . . . . . . .

2219 LCStream Class . . . . . . . . . . . . . . . .

218Sleep Method for LCSession . . . . . . . . . . . . .

215LookupMetaConnector Method for

LCSession . . . . . . . . . . . . . . . . . . . . . .

335Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

319Appendix E Additional ScriptingCapability for LEI . . . . . . . . . . . . . . . . .

307Appendix D Character Sets . . . . . .

273Appendix C Connector Properties

269Appendix B Connector PropertyTokens . . . . . . . . . . . . . . . . . . . . . . . . . . .

253Appendix A Error Messages . . . . .

251TextListRemove Method for LCStream . . . . .

251TextListInsert Method for LCStream . . . . . .

250TextListFetch Method for LCStream . . . . . . .

249NumberListRemoveValue Method for

LCStream . . . . . . . . . . . . . . . . . . . . . .

248NumberListRemoveRange Method for

LCStream . . . . . . . . . . . . . . . . . . . . . .

247NumberListInsertValue Method for

LCStream . . . . . . . . . . . . . . . . . . . . . .

246NumberListInsertRange Method for

LCStream . . . . . . . . . . . . . . . . . . . . . .

245NumberListGetValue Method for LCStream

vi Lotus Connector LotusScript Extensions Guide

Chapter 1Introduction

This chapter provides an introduction to the LotusScript Extension forLotus Connectors (LC LSX) and explains the organization of this manual.

This chapter also supplies a glossary of common terms and concepts usedthroughout the documentation, a general description of the individualclasses of the LotusScript Extension for Lotus Connectors, and describeshow the classes might be used to implement a typical application. Thedocumentation assumes a working knowledge of LotusScript, the Notesdevelopment environment, and the Notes classes. For more information onany of these subjects, please refer to the Notes Programmer’s Guide.

Organization of This ManualThe table below describes the organization of this documentation and theinformation contained in each section.

continued

This chapter provides descriptions of the LCFieldlist Classmethods and properties, and includes examples for usingeach of the methods.

Chapter 6 LCFieldlist Class

This chapter provides descriptions of the LCField Classmethods and properties, and includes examples for usingeach of the methods.

Chapter 5 LCField Class

This chapter provides descriptions of the LCDatetime Classmethods and properties, and includes examples for usingeach of the methods.

Chapter 4LCDatetime Class

This chapter provides descriptions of the LCCurrency Classmethods and properties, and includes examples for usingeach of the methods.

Chapter 3LCCurrency Class

This chapter provides descriptions of the LCConnectionClass methods and properties, and includes examples forusing each of the methods.

Chapter 2LCConnection Class

This chapter provides an introduction to the LotusScriptExtension for Lotus Connectors. It also includes informationabout the organization of this manual.

Chapter 1Introduction

DescriptionChapter

1

This appendix provides information about expandedLCSession functionality and additional class methodsavailable when using Lotus Enterprise Integrator forDomino (LEI).

Appendix EAdditional ScriptingCapability for LEI

This appendix provides a list of character sets supported foruse with the LotusScript Extension for Lotus Connectors.

Appendix DCharacter Sets

This appendix provides a list of the properties for eachLotus Connector.

Appendix CConnector Properties

This appendix provides a list of property tokens that areused in some of the LotusScript Extension for LotusConnectors methods.

Appendix B Connector PropertyTokens

This appendix provides a list of error messages that canoccur during a script execution, and provides a descriptionof the error message format.

Appendix A Error Messages

This chapter provides descriptions of the LCStream Classmethods and properties, and includes examples for usingeach of the methods.

Chapter 9 LCStream Class

This chapter provides descriptions of the LCSession Classmethods and properties, and includes examples for usingeach of the methods.

Chapter 8 LCSession Class

This chapter provides descriptions of the LCNumeric Classmethods and properties, and includes examples for usingeach of the methods.

Chapter 7LCNumeric Class

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 LotusScriptExtensions Guide - lsxlc6.nsf) are also part of the DECS documentation setand are now supplied with Domino only, not LEI. To obtain these twoneeded documentation databases, you must either install DECS or performa custom 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.

2 Lotus Connector LotusScript Extensions 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 itsActivities (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 with LEI. The lccon6.pdf file is available for download athttp://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 with LEI. Thelsxlc6.pdf file is 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 with LEI. The lccon6.pdf file is available for download athttp://www.notes.net.

Chapter 1: Introduction 3

• 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 with LEI. Thelsxlc6.pdf file is available for download at http://www.notes.net.

• Domino Enterprise Connection Services (DECS) Release Notes — Therelease notes contain information about the current release of DECS that may not be included in the documentation set.

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


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.

Overview of the LotusScript Extension for Lotus Domino ConnectorsLotus Domino Connectors provide native access to a wide variety of DBMSproducts, ODBC, the platform File system, Enterprise Resource Planningsystems, and Transaction Processing systems. The LotusScript Extension forLotus Connectors (LC LSX) extends these Connectors to LotusScript.

LotusScript provides an integral programming interface to Lotus Notes. TheLotusScript Extension for Lotus Domino Connectors enhances the power ofNotes by extending its scripting to data outside of Notes. The programmingmodel is independent of the individual Connector. This eliminates the needto learn each individual system, while at the same time allowing experi-enced users to access the individual features of a specific system.

For example, through Lotus Connectors, Notes and Web applications havethe ability to retrieve and act upon data within agents, during documentevents, or at the click of a button.

This release of the LC LSX supports access to the following connectors:

• Notes

• DB2

• File System

• ODBC


• Oracle 7

• Oracle 8

• OLE DB

• SybaseIn addition to these Connectors, the Lotus Connector LSX also supportsadditional premium connectors, such as SAP and PeopleSoft. These special-ized Connectors may require additional methods; see the documentationthat ships with each of these connectors for more information.

The LC LSX can be used alone or in conjunction with the Domino Enter-prise Connection Services (DECS) or IBM Lotus Enterprise Integrator forDomino (LEI). Respectively, these technologies provide programmatic anddeclarative access to external data for application development.

Connectivity Software RequirementsAccess to supported Lotus Connectors may require software to be installedon the Domino server or the Notes client from which the LC LSX scripts arerun.

See the Lotus Connectors and Connectivity Guide for information aboutsoftware that may be required to access a particular data source.

Loading and Registering the LC LSXYou must load the LotusScript Extensions for Lotus Connectors (LC LSX)using the following statement in your script:

Uselsx "*lsxlc"

Note As of Domino Release 5, Domino no longer registers the LC LSXwhen the Domino server is installed. The LotusScript interpreter insideDomino (and Notes) detects the “*“ at the start of the lsx name and knowshow to perform necessary name construction to find the LSX.

For LEI UsersThe following information, as well as Appendix E, pertain to LEI users only.

Each method described in this manual is accompanied by basic examplesyntax that begins with the following statement:

Uselsx "*lsxlc"

LEI requires that you also provide a name for every session and the name ofan existing Connection Document. You must specify Dim LCSession as anamed session (this becomes the default log document name).


LCConnections must be dimensioned as existing named ConnectionDocuments that have been created in the LEI Administrator.

Example statement syntax is shown below:

Uselsx "*lsxlc"

Sub Initialize

DIM MyLEISession As New LCSession ("MainLEISession")

Dim MyNotesConnection as New LCConnection("MyNotesConn")

Dim MyOracleConnection as New LCConnection("MyOracleConn")

In the above example, “MyNotesConnection” and “MyOracleConn” areassumed to be existing named Connection Documents in the LEI Adminis-trator. When writing LC LSX scripts for LEI, LCSession must be named.This name is used as the default log document name. Named sessionsenable support of LEI activity log documents.

Note The LEI Administrator uses the LC LSX to perform various browsingcalls, such as Select Metadata and Map Fields.

Terms and ConceptsKey terms are defined below.

MetadataThis is a generic term referring to a Connector’s data definition. The datadefinition includes the names of data elements, their data types, and impliesthe order of the elements. For example, Notes uses Forms to describe boththe names of data fields as well as the data type of each field. Sybasemetadata describes a Table. See the Connector Properties appendix forinformation specific to each Connector metadata.

Alternate MetadataAvailable through some Lotus Connectors, this is an alternate source for thedata definition. For example, DB2 metadata is in the form of a ‘table’, whileits alternate metadata form is a SQL view. See the Connector Propertiesappendix for information on whether a specific Connector supports alter-nate metadata.

Result SetThe return from an information request through a connection produces aresult set. Each connection can have a single active result set. The LCCon-nection methods Execute, Select, Call and Catalog each generate a result set,replacing any existing result set. The result set describes the collection ofdata or information from the connection, which matched the input criteria.


It does not return the actual data until fetched. If desired, these methodswill build a fieldlist representing the metadata as part of generating theresult set.

When using other connection methods which read or write data of a resultset, the implied order of the metadata may be suspended by using theconnection’s OrderByName property to indicate that, regardless of theorder of the data elements within the metadata, match the names in themetadata to the names in the external system.

Writeback Result SetA writeback result set is an optimized form of result set supported by someConnectors. A writeback result set provides both sequential read and writeoperations on the data, and may be used for efficient Update and Removeoperations by directly operating on the most recently fetched record in theresult set, rather than having to locate the information in the externalsystem a second time. Some Connectors may implement locking in theexternal system for writeback result sets.

TokenA token is an integer used to identify a property of a connection. Allconnection properties have a token value. Common properties have prede-fined tokens represented by constants. Connection-specific properties donot have predefined tokens.

For a list of property tokens and names for each connection, see theappendix.

Connection properties may be accessed by token or by name. The tokenmethod may be used when testing if a property is supported. The namemay be used when it is known that a given property exists.

LC ClassesThe Lotus Connectors provides external data and system access to theDomino LotusScript environment. The LSX classes consist of LCConnection,LCFieldlist and LCField, and four advanced data types, LCStream,LCNumeric, LCCurrency, and LCDatetime. In addition to these sevenclasses, there is also an LCSession class. Each of these classes and theirprimary usage is described below.


LCSessionThe LCSession class provides error information useful in error handlers. Italso provides for query and lookup of available Lotus Connectors.

Note The LCSession class has additional capabilities for LEI users. Forexample, using LCSession enables you to create a new session. Theseadditional capabilities are described in Appendix E, “Additional ScriptingCapability for LEI.”

LCConnectionThe LCConnection class represents an instance of a Lotus Connector. Thisclass provides query and data access to the external system. Multipleconnections may be allocated to a single Connector.

LCFieldlistThe LCFieldlist class is the primary class for manipulating data through aconnection. It binds a group of fields together with names and an impliedorder.

Fieldlists are used primarily for a number of connection operations; resultsets and selection criteria, as well as reading and writing data.

When a result set is generated, and an empty fieldlist was initially passedin, the fieldlist is automatically populated by the Connector. For each dataelement of the result set, the fieldlist receives the element’s name and a fieldobject of the corresponding data type. The result set may be controlled bymanually building the fieldlist before the result set is constructed or byusing the FieldNames property of the connection.

The Select and Call connection methods use an optional fieldlist of keys orparameters to restrict the result set. This fieldlist is manually constructedand passed to the select method. A key or parameter list is constructed byappending or inserting names and data types to the list. These methodscreate fields in the fieldlist and return these fields for further manipulation.These fields are then given values and, using field flags, may be givenconditions such as greater-than, not-equal, and so on.

By specifying a number of rows in the New method, you make it possiblefor the field list to contain multiple rows of data. This lets you fetch or writeseveral rows simultaneously. Some connectors are capable of “array” readand write operations; using a multirow fieldlist lets you take advantage ofthis capability to improve performance by minimizing network traffic. If theConnector does not allow array operations, you can still read and writemultiple rows but doing so will not improve performance.


LCFieldLCField is the storage class that contains one or more data values. The datatype of a field is for all values contained within and may be any of the fouradvanced data types below. Other advanced data types include longinteger, double precision floating point, fieldlist, and connection.

LCStreamLCStream is a general-purpose text and binary data type. The contents of astream are marked with a format that details the character set of the text orany special attributes of the binary data.

LCNumericThe LCNumeric class is a container for very high precision numbers.

LCCurrencyThe LCCurrency class is a fixed point decimal data type with 4 decimalplaces and 19 digits of precision. (This is mathematically equivalent to theLotusScript data type and is provided to support connections with adedicated currency.)

LCDatetimeThe LCDatetime class is a date and time data type which is accurate to thehundredth of a second and which is aware of time zones and daylightsavings time.

Working with the LSXA typical use of the Lotus Connectors is to gather, create, or modify data inan external system. For example, a Notes application has a number of datafields on a form. Once the user input is complete, a button activates thescript to take the form data and establish a connection to Oracle, locatingcorresponding information from one or more tables and updating the Notesform. The script is responsible for the following tasks:

1. Accessing the active Notes form

2. Gathering the input data

3. Creating a connection to the external system

4. Selecting the data based on the input values

5. Loading the data from the external system

6. Storing the results in the active Notes form


Here is a simple script to accomplish the task. The assumption is that theNotes form has a single text input field called “Customer”. The script willuse the value of the customer field to locate the corresponding customerinformation in DB2 and return an address and phone number for thecustomer storing the return values in the form using fields called“Address”, “City”, “State”, and “Phone”.

Note No attempt has been made to prescribe a code style. The practice ofgrouping object declarations together at the beginning of a script versuslocating declarations close to the code is a preference and does not affect theexecution. In this example, declarations and code are grouped to facilitateexplaining the process.

The first step in writing the script is to load the LotusScript Extensions forLotus Connectors. The Uselsx statement accomplishes this step. Additionaloptions may be used to check variables, simplify string comparison, and soon.

Option PublicOption Explicit

Uselsx "*lsxlc"

Note For LEI you must also use Dim LCSession as a named session (thisbecomes the default Log Document name) and LCConnections must bedimensioned as existing named connection documents that have beencreated in the LEI Administrator. See the overview section of each of themethod chapters for more information and an example.

The remainder of the script is located in the Click Event of the form’sbutton. Errors are displayed to the user. A simple error handler is written atthe bottom of this example. The LSX Session class has a Status property thatmay be used to determine if the error handler was triggered by an LSXerror or a LotusScript error. In all cases where the LSX reports an error, theLotusScript “Error$” will contain error information. However, when firstcreating LSX objects, the LSX has additional error information not availablethrough the LotusScript error statements. Creating and initializing theSession status provides this additional information for the error handler.

The creation of the session object is not necessary for normal error handling.

Sub Click (Source as Button) On Error Goto Handler Dim session As New LCSession session.ClearStatus

The input values are in the current active document. This information isaccessible via the NotesUIDocument, which may be located through theNotesUIWorkspace from its “CurrentDocument” property.


Dim wksp As New NotesUIWorkspace Dim uidoc As NotesUIDocument Set uidoc = wksp.CurrentDocument

The next step establishes a connection to the Lotus Connector for DB2. Afterthe connection has been created, all of its properties are accessible tocustomize the connection to the target system. Common properties includeDatabase and/or Server, UserID, and Password. Properties are not casesensitive.

For a complete list of properties for each Lotus Connector, see Appendix B.

The following code connects to the DB2 system called Rainbow as jdoe withthe password gold.

Dim src As New LCConnection ("db2") src.Database = "Rainbow" src.UserID = "jdoe" src.Password = "gold" src.Connect

There are four connection methods for querying through a connection -Catalog, Execute, Select and Call.

• The Catalog operation is used to return metadata information withinthe external system, for example, the tables of a DB2 database or thecolumns of a specific Sybase table. For a complete list of Catalogoptions, see the Catalog method.

The remaining methods, Execute, Select and Call, create result sets ofdata from the connection. The methods differ significantly in theirinterface.

• The Execute statement uses a connector-specific command statement todetermine the contents of the result set. This interface is helpful whenthe external system’s command structure is familiar and whencross-connector portability is not an issue.

• The Select method uses a combination of key names, values, andcondition flags to indicate the desired contents of the result set. Thisinterface works across connectors and does not require knowledge ofthe connector’s command language.

• The Call method is similar to Select, but is used for calling back-endprocedures or functions. Instead of keys, parameters are provided.

For our example, the important data are stored in the “Customer” DB2table, as indicated by the Metadata property of the connection. The onlyrecord of interest is the customer named by the input value from the Notesform.


Customer selection is accomplished by creating a key list. The default keyflag, LCFIELDF_KEY, indicates match exactly. If an inequality match suchas ‘greater-than’ or ‘like’ is needed, then the field’s flags property would beORed with the corresponding constant. In all cases, key fields must have theLCFIELDF_KEY constant in addition to any optional conditional flagconstants.

Dim keys As New LCFieldList Dim field As LCField

src.Metadata = "Customer" Set field = keys.Append ("Name", LCTYPE_TEXT) field.Flags = LCFIELDF_KEY field.Text = uidoc.FieldGetText ("Customer")

The Select connection method creates a result set of all records from theexternal system which match the keylist. If the LotusScript keyword“Nothing” is substituted for the key list, then all records of the specifiedmetadata would be selected. In this case, all records from the “Customer”DB2 table would be selected. This example is interested in just the customerrecord matching the input value from the Notes form. The key list is createdto make this restriction.

The fieldlist receiving the result set is currently empty. The selection willpopulate the fieldlist will the fields from the DB2 table. If all of the fields ofthe metadata are not needed, the result set may be restricted to just thefields of interest either by creating the fieldlist prior to the selection or bysetting the ‘FieldNames’ property of the connection.

src.FieldlNames = "Address, City, State, OfficePhone"

The selection returns one of three values: the number of records selected;zero (0) if no matching records were found; or LCCOUNT_UNKNOWN,when records were found but the connection does not know the total. Sincea return of zero is the only case where data was not found, it is the test casefor error handling or branching.

Dim fields As New LCFieldList If (src.Select (keys, 1, fields) = 0) Then End

A result set has been created and there is a match. The result set has notretrieved the data. The Fetch connection method reads the data from theexternal system into the fieldlist. The individual data values may beaccessed from a fieldlist using the expanded class properties. For each fieldin a fieldlist, there is a property with the corresponding name. Thisproperty is an array of values using the closest available LotusScript datatype to match the LSX LC data types.


If (src.Fetch (fields) > 0) Then Call uidoc.FieldSetText ("Address", fields.Address(0)) Call uidoc.FieldSetText ("City", fields.City(0)) Call uidoc.FieldSetText ("State", fields.State(0)) Call uidoc.FieldSetText ("Phone", fields.OfficePhone(0)) End If

Note When writing scripts that act on more than one record, it is moreefficient to locate the field from within the fieldlist, outside the loop, andthen use the field for data access. Refer to “Performance” in this chapter fordetails.

The data has been retrieved from the external system and placed in theNotes form. This completes this example. The final step is to refresh theNotes document to display the new data to the user.

uidoc.Refresh End

An error handler was designated as the first line of this example. Testing foran LSX error first provides additional information in the case of an objectcreation error. Without the session object and subsequent test in the errorhandler, failure while creating a connection to DB2 generates the LotusS-cript message, “Error creating product object”. However, for the same errorcondition, the LSX reports “Error: Cannot load LSX library ‘db2’.”

Handler: If (Session.Status <> LCSUCCESS) Then Messagebox Session.GetStatusText, 0, "The following LotusConnector error has occurred" Else Messagebox Error$, 0, "The following LotusScript error hasoccurred" End If EndEnd Sub

This example is very simple. It is meant only to provide an understandingof the Lotus Connectors, the classes, and the relationship between theconnection, metadata result set, fieldlist, fields and data.

Connection PoolingConnection pooling is part of the common LC API. The LSX is currently theonly technology which provides an end-user interface to the pooling code.The functionality is switched off by default, this minimizes any potentialadverse behavior connection pooling might introduce to existing code.


Note The LSX operates in two different modes - standard and LEI.Connection pooling is available only when the LSX is used in standardmode.

Connection Pooling OverviewThe LSX provides a simple programmatic interface to connection pooling.The LCSession class exposes a property called “ConnectionPooling.” Settingthis property to “True” enables connection pooling.

A typical operation consists of three major parts (see below, “Sequence ofEvents for Connection Pooling,” for more details):

1. Connecting to the data source

2. Identifying information of interest, retrieving and or updating theinformation

3. Disconnecting from the data source

The middle step is the processing step. When you work with large amountsof information or when you are performing complex operations, processingbecomes the most significant time consideration. Many applications have avery short processing step. In these applications, a much greater percentageof total time is associated with connecting to and disconnecting from theexternal data source. The connect/disconnect time is amplified when itmust occur for each processing request.

The LSX provides a connection pooling property that makes it possible toretain discarded connections for later use. The pooling functionality iscontrolled by the LCSession property, ConnectionPooling, which is aBoolean with a default value of FALSE. When this property is set to TRUE,subsequent requests for new connections are processed through the connec-tion pool.

With connection pooling, creating a new connection is serviced first bychecking the pool for an existing compatible connection and then if one isnot available, creating a new connection. A compatible connection is deter-mined by the external system and all of the system’s required connectivityproperties. This prevents a connection originally established for one user,later being used by another. As an example, a connection to DB2 which wasoriginally created using John’s user name and password, and then release tothe connection pool would not be issued if a new connection was requestedusing Jane’s user name and password.

A connection is removed from the pool when the “Connect” method occurs.A connection is returned to the pool when the “Disconnect” method occurs.If no explicit disconnect occurs, an automatic disconnect is performed whenthe object is deleted. Note: In LotusScript, if no explicit “delete” occurs on


an object, it is automatically deleted when it falls out of the scope of thefunction, subroutine, or script.

Keep in mind that a connection that is returned to the pool does not discon-nect from the external system. Code that takes advantage of connectionpooling must anticipate this behavior. The important issues to rememberare related to what may happen automatically during a normal disconnectfrom an external system. For example, disconnecting from an RDBMS maytrigger a commit of records inserted, updated, or deleted, since the connec-tion was first established. Likewise, there may be rollback or other databaseoperations that take place automatically as a result of disconnecting. Whenconnection pooling is enabled, these events do not take place because theconnection is not actually dropped. Therefore, if you expect and want thesetypes of operations to take place, the processing portion of the script mustexplicitly perform them.

The life span of a pooled connection is dependent on the LSX. Within Notesand Domino, an LSX is loaded when the execution of the Uselsx statementoccurs in a script. The LSX is not unloaded until the Notes or Dominoprocess terminates. Once a connection is pooled, it remains available untilthe associated process terminates.

The connection pool defaults to a maximum of 20 pooled connections for agiven external system. When the maximum number of connections havebeen created and are already in use, a request for an additional connectionwill be granted but the connection will not be pooled. The default may beoverridden using settings in the notes.ini file.

The syntax for configuring the connection pools is a list of comma-delimitedLotus Connector names, the pool size, and an optional data sourcemaximum. The default pool size for all connectors is 20. The optional datasource maximum value indicates the limit of allowed connections to asingle database. This value cannot be greater than the total pool size for agiven connector. For example, a DB2 pool size of 10 and a data sourcemaximum of 5 indicates the pool will hold no more than 10 connections toDB2 and of the 10, no more than 5 will be to any one database. If you do notspecify a data source maximum, it is the same as the pool size.

Here is an example of an INI entry:

EIConnectionPool=oracle,10,db2,20,5,psoft7,4

This example has pooling information for three connectors: Oracle, DB2,and PeopleSoft 7.0. Respectively, they support connection pools of 10, 20,and 4 connections each. In addition, DB2 indicates that no more than 5connections in the pool can be to a single database.


Note Connection pooling works for LotusScript agents because the LSX isloaded and maintained by the process space (that is, whatever processloaded the LSX: the server, the agent manager, http, or some other process).Also, if two agents use the RunOnServer method and they are run atseparate times, they both execute in the same process space and poolingworks.

Sequence of Events in Connection PoolingPrograms which use the LC API follow a typical progression:

1. Allocate a connection

2. Set connectivity properties

3. Connect

4. Select data

5. Fetch data

6. Manipulate data

7. Store data

8. Disconnect

9. Free connection

Connection pooling primarily affects the first three steps during which theconnection is established. While the presentation material contains materialpertaining to each step, the diagram below details the connection poolingprocess.

One goal of connection pooling is to minimize any adverse impact onperformance. For this reason, all code which utilizes a connection handle,must determine quickly if pooling is enabled and if a given connectionhandle refers to a traditional connection or a pooled connection.

The connection pool is subdivided based on connectors. There is a portionof the overall pool for each connector type used. The pool is configurable ona per connector basis. The default pool maintains 20 connections for anygiven connector. Connections are not established until requested by theusers program. Additionally, new connections are not created unless noapplicable connection is available in the pool. The pool may be configuredto limit the total number of connections for an individual connector as wellas limit the number of identical connections. A connection’s individuality isbased on its connectivity parameters or credentials. Connections are consid-ered to be identical when they are for the same connector and all of theconnectivity properties match. The matching criteria is also used to deter-mine if a connection in the pool satisfies a user request for a connection.


When a connection is first allocated, the connection pool is checked to verifythat pooling is enabled and the pool has as least one connection of therequested type: DB2, Oracle, SAP, and so on.

• The pooling code creates a facsimile of a connection and returns itshandle in place of a real connection handle. The purpose of thisfacsimile is to emulate a connection while the user assigns theconnectivity properties. The properties must be kept separate from areal connection until the request to establish a connection to the externalsystem.

• When connect request occurs, the properties held in the facsimile areused to locate a matching connection in the pool. Assuming one isfound, it is returned. Otherwise, a new connection is created returned.

• If the pool is full, the newly created connection is not pooled. The LCAPI can quickly differentiate between pooled and non-pooledconnection permitting them to be mixed freely. The user is unawarethat a request for a pooled connection was actually served by anunpooled connection. The only evidence would be the absence of anyperformance gains associated with pooling.


LotusScript and Lotus NotesUse of the Lotus Connectors LotusScript Extensions is limited to the Notesenvironment and Notes applications. For example, LSX scripts cannot becalled from within Lotus 1-2-3 or Lotus Approach, because the Connectorsonly have context within the Domino server and Notes client.

Security and AccessAgents or other LotusScript code that uses the Notes Connector or FileConnector must be signed with a Notes ID that has permission to rununrestricted agents. This also applies to any script libraries used by suchcode. Specifically, connections through these Connectors will be blockedwith an error unless the signing Notes ID has this permission.

Note There is a similar situation in the DECS application. Within DECS,attempting to browse Notes when creating an Activity or using the InitializeKeys functionality may generate a LotusScript error regarding access tounrestricted agents. The DECS application must be allowed to rununrestricted agents in order for these capabilities to work.

You can correct this problem by adding the ID “Lotus Notes TemplateDevelopment/Lotus Notes” to the “Run Unrestricted Agents” field in theDomino server’s entry in the name and address book (NAB) which containsthat server. The “Run Unrestricted Agents” field resides under the Securitytab. Alternately, you can re-sign the DECS administrator database with aNotes ID already listed in the “Run Unrestricted Agents” field.

LSX Data TypesStandard and advanced LSX data types are described below.

Standard Data TypesThese are the types for data that you will read from or write to data sourcesyou connect to using LC or LEI. Standard data types come in the followingthree classes:

• Number (Int, Float, Currency, and Numeric)

• Datetime (Datetime)

• Stream (Text and Binary)

All types except Int and Float are represented by Lotus Connector classesdescribed in this manual (Int is represented by a LotusScript Long, andFloat by a LotusScript Double).


• Int: A four-byte signed integer. Integers are very efficient, but limited inprecision and range. An Int is any whole number between -2147483647and 2147483647 (9 digits of precision).

• Float: An eight-byte (double-precision) floating point number. Floatshave less precision than currencies or numerics, but have a far greaterrange of values and are more efficient. A float has 15 digits of precision,and can represent any practical value (with an exponential rangebetween 10^308 and 10^-308).

• Currency: An eight-byte integer with four decimal places. Currencyprovides greater precision than either int or float values. While it is lessprecise than a numeric, it is far more efficient, making it the preferablechoice when higher precision is required. A currency has 19 digits ofprecision, and a maximum value of 922,337,203,685,477.5807.

• Numeric: A numeric is larger and less efficient than any other numberdata type, but has far greater precision. A numeric is assigned aprecision (number of digits) up to 88 and a scale (number of decimalplaces) between -127 and 127, allowing it to express a very largenumber of values with very high precision.

• Datetime: A datetime indicates a specific date and time. Its range is anydate between the years 1 and 32767, with a precision of .01 seconds. Inaddition, datetimes are specific to time zone and DST settings, makingthem usable in international settings.

• Text: Text is a stream of characters up to 4GB in length. All text has acharacter set, and conversion between character sets is supported.When transferring between systems, character set conversion isautomatically performed as needed.

• Binary: Binary is a stream of bytes up to 4GB in length. All binary datahas a format which is either BLOB (Binary Large Object) forunformatted data, or a structured binary format such as composite, textlist, number list, and datetime list. The three list formats allow for asingle data value to itself contain multiple values.

Advanced Data TypesAdvanced data types comprise two areas: Fieldlist and connection.

• Fieldlist: A fieldlist itself is a collection of named fields with one ormore values each, similar to a SQL table. A fieldlist as a data typeallows for a single data value to itself contain a fieldlist, supportinghierarchical or nested data. The fields in a fieldlist data value may inturn contain additional nested fieldlists. Fieldlists are only usable bythose back-end that support such data structures.


• Connection: A connection supports interaction with a back end systemthrough a Lotus Connector. Connections as a data type are only validwhen working with metaconnectors, since metaconnectors haveproperties of type connection.

Arrays and IndexesThe default for array indexes in LotusScript is 0 based. For example,elements of an array are specified as Elem(0), Elem(1), Elem(2), etc. There isan option in LotusScript, “Option Base n,” which lets you make the defaultlower bound of an unspecified array something other than 0. LSXs do notsupport this syntax. It is recommended, for consistency, that within scriptswhich use an LSX, such as the Lotus Connectors, this option not be used.

Many Lotus Connector class methods operate on multi-value data. Classmethods include the List methods of LCStream, the Get and Set methods ofLCField and LCFieldlist, as well as the Fetch, Insert, Update, and Removemethods of LCConnection. These operations are counted from 1. Forexample, fields of a fieldlist are specified as MyFieldList.GetField (1),MyFieldList.GetField (2), MyFieldList.GetField (3),…and so on. Unlikedimensioned arrays which default to zero based, and LSX generated arrayswhich are always zero based, these class methods require an index countedfrom 1. In some cases, you will access the same data item with a zero-basedarray index, and with a one-based index method argument, depending onwhether you choose to access it with a method or with a property thatreturns an array value.

It is possible to assign a LotusScript array to a multi-value object such as aLCField. It is important that the array not contain more elements than theLCField object will store, as this will cause an overflow error. For example,5 long integers may be assigned to an LCField as follows:

Dim numbers(4) as Long ' numbers(0, numbers(1), ... numbers(4)Dim field as new LCField (LCTYPE_INT, 5)

...field.Value = numbers


Working with Multiple Rows of DataThe Fetch, Insert, Update, Remove methods of a connection use a Record-Count parameter and may operate on more than a single row at a time.However, the LCFiedllist parameter must have been created to hold morethan one record for this to work. You may operate on fewer records thanthe Fieldlist was created with, but not more.

A simple example of different configurations for RecordIndex and Record-Count might be as follows:

Dim Records as New LCFieldlist (3, LCFIELDF_TRUNC_DATA)

Dim count As Long

Dim i As Long

...

Call connection.Fetch (Records, 1, 3) ' fetch up to threerecords

Call connection.Insert (Records, 3, 1) ' insert them 'in reverse order

For i = count To 1 Step -1

Call connection.Insert (Records, I, 1)

Print "IName(" & I & ") = " & Records.IName(i-1)

' retrieve a value from the array of IName field values.

Next

Note Both parameters for New LCFieldlist are optional and default to 1,and LCFIELDF_TRUNC_PREC, respectively. Likewise, the RecordIndex andRecordCount parameters are optional for Fetch, Insert, Update and Remove,and default to 1 and 1. Lastly, the RecordIndex and RecordCount, whenadded to each other (minus 1) must not exceed the size of the createdFieldlist.

If you retrieve multiple rows, the field (IName in this case) will have multi-ple values. Although the records are indexed starting at 1, the index of thearray of field values starts at 0, so to read a field value from row n of theresult, you should ask for Records.fieldname(n-1).

Note It’s not efficient to use the LCFieldlist.fieldname syntax when readinga large result set. Refer to “Performance” (in this chapter) for a betterperforming alternative. In either case, however, field values are returned asan array and you must at some point specify the array index.


Optional ParametersSome methods have optional parameters. The LotusScript keyword“Nothing” is used for output parameters that the user is not interested inreceiving. If one or more optional parameters are at the end of a call, theymay simply be ignored as in the case of a datetime. For example, a datetimewith only the date portion provided is created using the followingstatement.

Dim Calendar as New LCDatetime (1998, 8, 7)

'In this case hour, minute, second, and so on 'have been omitted at the end

When optional parameters that occur in the middle are omitted, thecommas must remain.

Call session.GetStatus (ErrorText, , DBError)

PerformanceCertain techniques can be used to increase LSX code performance. Thesetechniques are described below.

Connector CachingMost connectors are optimized for repeated calls using the sameparameters, but different data values. This generally applies to Fetch, Insert,Update, Remove, and Select operations. When these methods are calledwith the same fieldlist more than once, they are able to avoid certain stepssuch as field mapping and type checking. This optimized functionality isavailable as follows:

Select: METADATA property and KeyFieldlist are the same.

Fetch: Result set and DestFieldlist are the same.

Insert: METADATA property and SrcFieldlist are the same.

Update and Remove: WRITEBACK and METADATA properties andSrcFieldlist are the same.

Calls to one type of method generally do not affect others, so the followingpseudo-code obtains the optimal use of this caching:

Connect to Connection CONN

Set Metadata

Generate result set, producing Fieldlist FL


Loop until done:

Fetch into FL

Insert from FL

Exit

If this were changed to fetch the data and then inserted into one of twotables depending on some condition, then every time the table changed,new field mapping and type checking would be performed. In such a case,establishing two connections for Insert would be optimal.

Locate Fields Before LoopingIf you’re reading or writing a large number of results, avoid using theLCFieldlist.fieldname syntax. Each time you use an expression of the formLCFieldlist.fieldname, LC must scan through the fields in the list looking forone with a matching name. It’s better to create separate a LCField object foreach field, and use Lookup to assign them before entering the loop, so thatthe work of searching for the field name can be done just once. Here’ssample code that illustrates this technique.

Dim address as LCField

Dim city as LCField

Dim state as LCField

Dim phone as LCField

Set address = fieldlist.Lookup ("Address")

Set city = fieldlist.Lookup ("City")

Set state = fieldlist.Lookup ("State")

Set phone = fieldlist.Lookup ("OfficePhone")

while (src.Fetch (fields) > 0) Then

Call uidoc.FieldAppendText ("Address", address.Text(0))

Call uidoc.FieldAppendText ("City", city.Text(0))

Call uidoc.FieldAppendText ("State", state.Text(0))

Call uidoc.FieldAppendText ("Phone", phone.Text(0))

Wend


Tight LoopsAnother way to optimize LSX code is to produce tight loops, moving asmuch code out of the loop as possible. Anything inside such a loop must bedone for every iteration of the loop, and can therefore become costly withlarge data sets. For example, inside a loop which transfers 10,000 records,you may need to access a field in a fieldlist. Instead of using the property asFieldlist.Fieldname, which will locate the field by name every iteration, youcould instead use Field = Fieldlist.Fieldname outside the loop and thensimply refer to Field inside the loop. This will remove 10,000 propertyaccesses for the fieldlist.

Multiple Row OperationsSome databases are capable of “array” operations that fetch or insert multi-ple rows of data with a single call. One call to return ten elements of a resultset simultaneously is substantially faster than ten fetches of one elementeach. You can take advantage of this by writing your code to use multi-value LCFieldlist objects.

If the database doesn’t support array operations, you can still Fetch orInsert with multiple rows, but you won’t see any performance improve-ment from doing so, because the connector code implements the multipleoperation by issuing repeated calls to read or write one record at a time.

NOTES.INI VariablesLEI and DECS set and use certain environment variable settings in thenotes.ini file. Some of these variables are set based on choices you makeduring the Domino or LEI installation. You can use the notes.ini file tochange these settings for DECS and LEI.

You can use the notes.ini file to adjust some aspects of LEI. For example,you can force the local machine’s native character set to be overridden byadding the following line to the notes.ini file.

EINativeText=IBMCP932

The LCSTREAMFMT_IBMCP932 represents IBM character set code page932. For information about international character sets within LEI, see theIBM Lotus Enterprise Integrator for Domino (LEI) Activities and User Guide.


For Both LEI and DECSEnvironment variables used by LEI and DECS are listed below:

• EITranslation

• EICentruryBoundary

• EINativeText

• EIMaxRTEntries

• EIConnectionPool

EITranslationControls text translation, allowing you to increase performance in exchangefor certain assumptions about the data being accessed. Note that none ofthese settings affects translation between Unicode and other character sets.There are three valid numeric settings:

• 0 = Disabled — Do not perform translation between character sets(except Unicode). This is valid when all data being accessed iscompatible with the Notes LMBCS character set - primarily ASCIIprintable characters.

• 1 = LMBCS only — Do not perform translation between non-LMBCS(and non-Unicode) character sets. This is valid when all data beingaccessed, except for Notes LMBCS data, is in compatible character sets.

• 2 = Enabled — Always translate between any character sets. This is thedefault.

In previous versions of LEI and DECS, this was named Translation orDECSTranslation, respectively.

There are three valid numeric settings:

Enabled — Always translate between any character sets. This is thedefault.

2.00

LMBCS only — Do not perform translation between non-LMBCS (andnon-Unicode) character sets. This is valid when all data beingaccessed, except for Notes LMBCS data, is in compatible charactersets.

1.00

Disabled — Do not perform translation between character sets (exceptUnicode). This is valid when all data being accessed is compatiblewith the Notes LMBCS character set - primarily ASCII printablecharacters.

0.00

DescriptionValue


EICenturyBoundaryThis controls how to interpret the year in a text string being converted to adatetime, when the year contains only two digits. Values greater than orequal to the century boundary are considered to be in 1900s, values lessthan are in the 2000s. There are three ways to set this:

Since all values are less than 101, always use 2000.101.00

If the two-digit year is greater than or equal to this value, use 1900;otherwise use 2000.

1-100

Since all values are greater than or equal to zero, always use 1900.0.00

DescriptionValue

The default setting is 50, which is the same as Notes. This means that anytwo-digit year from 0-49 is in 2000, and 50-99 is in 1900.

EINativeTextThis allows the local machine’s native character set to be overridden. Thereare various situations when the native character set is used within the LSX,and some external systems always consider client data to be in the nativecharacter set. Setting this value to a valid text format string replaces thecharacter set obtained from the operating system by the LSX with theindicated character set. Appendix D lists supported character sets. Use the text that remains after removing the “LCSTREAMFMT_” prefix. For example, Code Page 932, represented by the constantLCSTREAMFMT_IBMCP932, would be set as follows:


EIMaxRTEntriesThis functionality has been added to allow support for more than 128 concur-rent RealTime activities. To increase the maximum number of AdvancedRealTime activities that can run concurrently, add “EIRTMaxEntries=” to thenotes.ini file and assign it an integer value to indicate the new upper limit. If aline already exists, edit its value to the new setting. The lower limit is 128active activities; a value less than 128 will not change the limit below 128. Ifthe number of activities started exceeds the specified value in the notes.inifile, the server will display a warning message and subsequent activities willnot be started. An example INI entry is shown below.

EIRTMaxEntries=175

For LEI onlyWhen you install LEI, several variables are set in the notes.ini file. Fordetailed information about the notes.ini variables that pertain to LEI, see theIBM Lotus Enterprise Integrator for Domino (LEI) Installation Guide suppliedwith LEI and also found at www.notes.net.


Environment variables used by LEI only are listed below:

• EIName

• EIAdminServer

• EIVersion

EINameSpecifies the name of the LEI server as found in the server document of theLEI Administrator database. This variable value is assigned when youinstall LEI. Example syntax is shown below:

EIName=HERMANM

EIAdminServerSpecifies the name of the Domino server where the LEI Administrator islocated. This variable value is assigned when you install LEI. Examplesyntax is shown below:

EIAdminServer=RALPHITE

EIVersionSpecifies the version of the LEI server, entered here by the LEI installation.Example syntax is shown below:

EIVersion=101006

For DECS onlyEnvironment variables used by DECS only are listed below:

• DECSPollingInterval

DECSPollingIntervalSpecifies the interval at which DECS will reference the DECS Administratorconfiguration document.

DECSPollingInterval=5

For LCLSX onlyEnvironment variables used by the Lotus Connectors Extensions for LotusScript only are listed below:

• EIConnectionPool

EIConnectionPoolSee the Connection Pooling section in this chapter for information aboutconnection pooling. Example syntax is shown below:

EIConnectionPool=oracle,10,db2,20,5,psoft7,4


Chapter 2LCConnection Class

This chapter provides information about the Lotus Connectors LCConnec-tion class methods and properties.

OverviewThe LCConnection class represents an instance of an individual LotusConnector. One connection object should exist for each individual dataconnection through a Connector. This is true when the connections are tothe same Lotus Connector as well as to different Connectors. For example,transferring data from one DB2 table to another table in Oracle is bestaccomplished by creating two LCConnection objects, one for DB2 and onefor Oracle, and fetching data from one and inserting it into the other.

Connection methods manage individual Lotus Connector connectionswithin a session. The connection class enforces Connector state and require-ments, and must always be used when interacting with Connectors. Oneconnection object should exist for each individual data connection througha Connector used in a session.

Error information for a connection is available through use of the LCSessionclass.

Syntax for LEI Scripted ActivitiesWhen writing LC LSX scripts for LEI Scripted Activities, you must specifyDim LCSession as a named session (this becomes the default log documentname). LCConnections must also be dimensioned as existing, named LEIConnection Documents.

29

An example statement of the proper syntax is shown below:

Uselsx "*lsxlc"

Sub Initialize


Dim MyNotesConnection As New LCConnection("MyNotesConn")

Dim MyOracleConnection As New LCConnection("MyOracleConn")

In the above example, the “MainLEISession” is the session name. The“MyNotesConn” and “MyOracleConn” are existing, named ConnectionDocuments.

LCConnection PropertiesAll Connections have a set of properties with values that can be assignedand retrieved. All properties are represented by both an integer value(called a property token) and a name. Some property tokens are valid for allConnectors, while others are connector-specific. Refer to Appendix C for alist of properties for each Lotus Connector.

All Connector properties are of the closest LotusScript data types when youaccess connection properties using this form:

Value = LCConnection.<PropertyName>

or

LCConnection.<Property.Name> = value

When referencing the Connector’s property by name, the property will berepresented using the closest matching LotusScript data type; not the LotusConnector data type. For example, if the property were textual, the LC datatype would be an LCStream, however, the syntax above would use theclosest matching LotusScript data type which would be a “String”.Likewise, an LCDatetime corresponds to a LotusScript “Variant” with dateand/or time information.

Note When you use the LCConnection.GetPropertyXXXXXX() syntax, thedata type will be an LC data type.

Common Connector PropertiesThe following is a list of predefined properties common to all LotusConnectors. Use these predefined properties with theLCConnection.GetProperty and LCConnection.SetProperty methods. See“Miscellaneous” under the “LCConnection Class Methods Summary”section below as well as the entry for each method.


Boolean. TRUE following asuccessful Connect call, untilDisconnect is called. FALSEotherwise.

“IsConnected”LCTOKEN_IS_CONNECTED

String. Use this property tospecify which connector ametaconnector is filtering. Thiscorresponds to the “Connectionto use” field in theMetaconnection document in theLEI Administrator.

“ConnectorName”LCTOKEN_CONNECTOR_NAME

Long. Lotus connector statuscode to ignore. See below.

“IgnoreError”LCTOKEN_IGNORE_ERROR

String. Lotus connector characterset indicator. (Read only.)

“ CharacterSet”LCTOKEN_CHARACTER_SET

Long. Stream format constant fortext data passed between theconnector and the externalsystem. This property isgenerally read-only.

“ TextFormat”LCTOKEN_TEXT_FORMAT

Long. Error code (LCFAIL_XXXconstant) to treat as an event.When this error is generated, it isdowngraded to an informationalevent. Set to LCSUCCESS to clearthis property.

“EventError”LCTOKEN_EVENT_ERROR

Long. Connection Virtual Code.(Read only.)

“ConnectionCode”

LCTOKEN_CONNECTION_CODE

Long. Connector Virtual Code.(Read only.)

“ConnectorCode”LCTOKEN_CONNECTOR_CODE

String. Connector name. (Readonly.) This is the same as thelibrary name given in the Newmethod.

“Name”LCTOKEN_NAME

DescriptionNameProperty

Properties of a connection may also be accessed by name, for example, thefollowing line of script sets the value of Database property for a LotusConnector for DB2 to “HR.”

Connection.Database = "HR"

Note Connector-specific properties are listed in an appendix of thismanual.

Chapter 2: LCConnection Class 31

LCConnection Class Methods SummaryThe LCConnection class methods are summarized in the following sections.

ConnectionThe following methods control connection to a data provider. A connectionis required before gaining access to most Connector metadata and allConnector data. Multiple connections may be established to a singleconnector with multiple connection objects.

Disconnect from a data provider.LCConnection.Disconnect

Establish a connection to a data provider.LCConnection.Connect

DescriptionMethod

Create Result SetEach Connection can have a single active result set. A result set is the dataproduced by an action, for example, the execution of a Select statementagainst SQL tables. All of these methods produce a result set, replacing anyexisting result set. The result set can be produced from a Connector-specificlanguage statement, from Connector-independent properties and keys orparameters, or from Connector metadata. Connector metadata is either anSQL table or view, a Notes form, and so on.

Once a result set is produced, the data in that result set can be fetched.Under specific circumstances, efficient writeback updates and removesdirectly back into the result set are also supported.

Note The Execute and Call methods invoke an operation from the externalsystem.

Perform a Connector-independent selection controlledby various connector properties. Conditional keyinequalities, timestamp, and other control is supported.

LCConnection.Select

Execute a statement against the data provider. Thestatement is provided in the data provider’s language.

LCConnection.Execute

Produce a result set containing a list of servers,databases, tables or views, indexes, or fields in a table,that are available through this connection. Each record inthe result set describes one server, database, table, and soon.

LCConnection.Catalog

Perform a Connector-independent procedure call withparameters.

LCConnection.Call

DescriptionMethod


Data ManipulationThese methods allow access to and manipulation of Connector data.

Delete records from the data provider. Key values areprovided. No keys are required for writeback operations.

LCConnection.Remove

Update records in the data provider. Key values andupdate values are provided. No keys are required forwriteback operations.

LCConnection.Update

Insert new records into the data provider.LCConnection.Insert

Retrieve records from the current result set.LCConnection.Fetch

DescriptionMethod

Metadata ManipulationThese methods allow access to and manipulation of Connector metadata.

Drop an existing metadata object.LCConnection.Drop

Create a new metadata object.LCConnection.Create

DescriptionMethod

Miscellaneous

Set a property as a particular data type.LCConnection.SetProperty<datatype>

Set a property value for a connection.LCConnection.SetProperty

Verify the support of a property.LCConnection.LookupProperty

List supported properties and values.LCConnection.ListProperty

Fetch a property as a particular data type.LCConnection.GetProperty<datatype>

Fetch a property value for a connection.LCConnection.GetProperty

Perform one of a set of predefined actions (forexample, commit). Different actions may beavailable in different connectors.

LCConnection.Action

DescriptionMethod

New Method for LCConnectionThis is the constructor for objects of class LCConnection.

Defined InLCConnection


SyntaxDim connectionName As New LCConnection(libraryName) ‘ DECS only

or

Dim connectionName As New LCConnection(ConnectionDocumentName) ‘LEI Scripted Activity agents only

Parameters

The name of a valid Connection Document that existsin the LEI Administrator.

ConnectionDocumentName

The name of a valid, installed connector, such as db2or oracle, and the db2.lcx or oracle.lcx exists in theNotes/Domino directory. A metaconnector name mayalso be used (order, meter, and so on).

Use lowercase letters for libraryName, as some filesystems are case-sensitive. See theLCSession.ListConnectors method, which is used todetermine the installed Connectors.

libraryName

DescriptionParameter

Usage NotesThe following usage considerations are helpful.

• A connection library is located by file name. The files are located in theNotes executable directory and use the suffix “.dcx”.

• When the LEI server executes a Scripted Activity, it calls a LotusScriptagent in your Notes database. When you use the New method ofLCConnection in this context, it expects you to supply a the name ofconnection document in the LEI Administrator database (decsadm.nsf);you may not supply a Connector name. All of the properties of theconnection — Server, UserID, Password, Metadata, and so on — arefilled in based on the information in this Connection Document. Youcan then change these properties. For example, change the Metadataproperty if you need to use a different table than the one specified inthe Connection Document.

• In all cases except Scripted Activity agents, the constructor argumentspecifies a Connector or Metaconnector. Base Connectors are deliveredwith LEI and/or Domino; others can optionally be purchased or youcan use the LC APIs to write your own. See the Lotus Connectors andConnectivity Guide available at http://www.notes.net for details.


• If you use a Metaconnector, you will have to supply the actualconnection name in the ConnectorName property. The examples belowdemonstrate this.

• The constructor allocates a numeric code for this connection, uniqueamong all connections, which can be used as a virtual code for a field(see LCField.SetVirtualCode). This value can be retrieved as theproperty LCTOKEN_CONNECTION_CODE. There is also a numericvirtual code for the type of connection (for example, DB2), available inthe LCTOKEN_CONNECTOR_CODE property. You can use this codewhen merging fieldlists to separate out those fields associated with aparticular connection or Connector. See the LCFieldlist.MergeVirtualmethod for details.

Example' DECS only

Dim MyNewConnectionName as New LCConnection("oracle")

' LEI scripted agents only

Dim MyNewConnection as New LCConnection("OracleConnDoc")

' with the "order" metaconnector

Option Public

Option Declare

Uselsx "*lsxlc"

Sub Initialize

Dim birthdayTable As New LCConnection("order")

Dim flds As New LCFieldList

Dim i As Integer

With birthdayTable

.ConnectorName = "db2"

.Database = "STATS" ' local database, no userid.

.Metadata = "BIRTHDAYS"

.OrderNames = "BIRTH_DATE" ' order metaconnectorwill sort by this field.

.Connect

.Select Nothing, 1, flds


Do While birthdayTable.Fetch(flds)

For i = 1 To flds.FieldCount

Print flds.GetName(i) & " = " &flds.GetField(i).Text(0)

Next

Loop

End With

End Sub

Example OutputFIRSTNAME = Anapest

LASTNAME = Jones

BIRTH_DATE = 04/03/1901

FIRSTNAME = Ozymandias

LASTNAME = Miller

BIRTH_DATE = 02/20/1979

FIRSTNAME = Chlorine

LASTNAME = Foss

BIRTH_DATE = 09/01/1980

Action Method for LCConnectionThis method performs an action as defined by the actionType parameter.Not all available actions may be supported. If you use an unsupported actiontype, this method will generate the error LCFAIL_UNAVAILABLE.


SyntaxCall lcConnection.Action(actionType)


Parameters

LCACTION_CLEAR — Clears the current result set, freeing anylocks, but does not affect any other context. Do not count on the Clearaction doing a commit or rollback of your changes. If you havechanges outstanding, you should use the Action method to commit orrevoke them before you use Clear.

LCACTION_ROLLBACK — Rolls back all changes in the currenttransaction. Only supported by Connectors with transactionfunctionality.

LCACTION_COMMIT — Commits all changes in the currenttransaction. Only supported by Connectors with transactionfunctionality.

LCACTION_TRUNCATE — Deletes all records in the propertyMETADATA in the most efficient available manner as determined bythe connector.

LCACTION_RESET — Returns the connector to a state equivalent tothat just after connection. All outstanding results are committed andall result sets and state information are freed. Supported by allConnectors.

actionType


ExampleOption PublicOption ExplicitUselsx "*lsxlc"

Sub Initialize

Dim session As New LCSession

' In an LEI Scripted Agent, use the following syntaxinstead:

' Dim session As New LCSession ("mySession")

Dim src As New LCConnection ("db2")

' set properties to connect to both data sources

src.Database = "Gold"

src.Userid = "JDoe"

src.Password = "xyzzy"

src.Metadata = "customer"

' now connect

src.Connect


' check to see if the target metadata exists, if so clear itout.

' check for LCFAIL_INVALID_METADATA error

On Error LCFAIL_INVALID_METADATA Goto NoMetadata

Call src.Action (LCACTION_TRUNCATE)

Print "the table '" & src.Metadata & "' has been truncated."

Print "This removed all existing records."

End

NoMetadata:

' couldn't truncate the table since it didn't exist

Print "the table '" & src.Metadata & "' does not exist."

End

End Sub

Example OutputThe table 'customer' has been truncated. This removed allexisting records.

Call Method for LCConnectionThis method is used to call a stored procedure and potentially produce aresult set.

This method only supports input parameters to the stored procedure. If youwant data returned from a stored procedure, it must be returned to a resultset, not by output parameters.

For DB2, this method executes the stored procedure defined in the PROCE-DURE property. If the procedure produces a result set, limit that result setto the number of records defined in the property RECORD_LIMIT.

Note DB2 supports stored procedures written in C, C++, Java, and SQL.The DB2 Application Development Client supplies a stored procedurebuilder which generates, compiles, and links a stored procedure for use.

Note OS/400 iSeries stored procedures may be written in RPG, C, CL,COBOL, C++, FORTRAN, PLI, and REXX. Use the Create Procedure SQLstatement to generate a stored procedure. The Create Procedure statementcan also be used with the OS/400 Interactive SQL product (5769ST1).



Syntaxcount = lcConnection.Call(parmFieldList, recordIndex, destFieldList)

Parameters

LCFieldlist. Fieldlist to contain the metadata of the result set. Thefields in the result set will be appended to this fieldlist. If the resultset metadata is not required, use Nothing.

destFieldList

Long, >=1. The index location of the parameter values within thefieldlist.

recordIndex

LCFieldlist. The input parameter list for the stored procedure. Youmay not specify Nothing here; if the procedure has no arguments,supply an empty fieldlist.

parmFieldList


Return Value

Long. The number of records affected by the call. Note that not alldata sources return a count. LCCOUNT_UNKNOWN is returned ifthe count is not determined.

count

DescriptionValue

ExampleOption Public

Uselsx "*lsxlc"

Sub Initialize

Dim Con As New LCConnection ("sybase")

Dim Parms As New LCFieldList

Dim Result As New LCFieldList

Dim Parm As LCField


Con.Server = "Rainbow"

Con.Userid = "JDoe"

Con.Password = "xyzzy"

' set the connection property to the stored procedure name

Con.Procedure = "NPInsertIntoSM_ADBOOK"

' now connect


Con.Connect

' append the new field to the fieldlist

Set Parm = Parms.Append ("spParm", LCTYPE_TEXT)

' set the field to a value — in this case it is

' the one parameter needed for the stored procedure

Parm.text = " 'Edge' "

' using the fieldlist containing the field with the

' stored procedure parameter, call the stored procedure

count = Con.Call (Parms, 1, Result)

If count = 0 Then

Print "No results were generated from the procedure call."

Elseif count = LCCOUNT_UNKNOWN Then

Print "A result set was generated but the number of resultsis unknown."

Else

Print "The stored procedure returned " & count & " records."

End If

End Sub

Example OutputA result set was generated but the number of results is unknown.

Catalog Method for LCConnectionThis method returns information about the data sources, metadata objects,stored procedures and fields available through a connection. Some LotusConnectors do not support all object types.

The information is returned using the result set of the connection. Anyactive result set for this connection will be replaced. The format of the resultset produced is returned in the supplied fieldlist, and the result set contentscan be retrieved with LCConnection.Fetch. For instance, if you catalogMetadata information, each Fetch will return information about onemetadata object.

In general, you must connect to the data source (Connect method) beforeusing Catalog. However, some Connectors enable you to catalog serversand databases without an active connection.


Use the properties of the LCConnection to provide the context for the infor-mation you’re looking for. For instance, to catalog databases on a server,you must first set the Server property of the connection, but you don’t needto set the Database or Metadata property. The table below lists the requiredcontext for each type of object you can catalog.

Note For this method, do not use metadata in the form “owner.tablename”— instead, assign connection.Owner = “owner” and connection.Metadata =“tablename”.


Syntaxcount =lcConnection.Catalog(objectType, destFieldlist)

Parameters

continued

Output Fields: Index Name, Index Owner, Index Comment

Context: Current connection

LCOBJECT_INDEX

Output Fields: Metadata Name, Metadata Owner, MetadataComment

Context: Current connection, ALTERNATE METADATA property

LCOBJECT_METADATA

Output Fields: Database Name, Database Owner, Database Comment

Context: SERVER property (if supported by this connector)

LCOBJECT_DATABASE

Output Fields: Server Name, Server Owner, Server Comment

Context: None

LCOBJECT_SERVER

Long. Type of metadata information to be cataloged. Use anLCOBJECT_XXX constant to define the metadata type. The followinglist gives the required context and the resulting metadata format foreach catalog type. The general fields, Name, Owner, and Comment,are produced for all objects, but only the first output field(name) isguaranteed to have data.

All output fields are data type Text, unless otherwise specified. Fieldcataloging adds a fourth element, data type.

objectType



Output Fields: Field Name, Field Owner, Field Comment, FieldDatatype Constant.

Context: Current connection, METADATA property, ALTERNATEMETADATA property

LCOBJECT_FIELD

Output Fields: Procedure Name, Procedure Schema, Remarks

Context: Current connection

LCOBJECT_PROCEDURE


The Field Datatype Constant gives the data type of the field using one of thefollowing values:

Note More detailed information about the field, such as the maximumlength of a stream field, can be obtained by using Select on the metadataobject.

ConnectionLCTYPE_CONNECTION9.00

FieldlistLCTYPE_FIELDLIST8.00

BinaryLCTYPE_BINARY7.00

TextLCTYPE_TEXT6.00

DatetimeLCTYPE_DATETIME5.00

NumericLCTYPE_NUMERIC4.00

CurrencyLCTYPE_CURRENCY3.00

FloatLCTYPE_FLOAT2.00

IntegerLCTYPE_INT1.00

OverviewLCTYPE_INVALID0.00

TypeConstantValue

LCFieldlist. Output. Fieldlist to contain the metadata of the catalogresult set. The fields in the result set will be appended to this fieldlist.If the result set metadata is not required, use Nothing.

destFieldlist

Return Value

Long. Number of catalog records available in the result set produced.This value is LCCOUNT_UNKNOWN if the number of recordscannot be determined by the connector.

count

DescriptionValue



Uselsx "*lsxlc"

Sub Initialize

Dim connect As New LCConnection ("db2")

Dim conFldLst As New LCFieldList

' this section assigns the appropriate properties to connectto DB2

connect.Database = "Gold"

connect.Userid = "JDoe"

connect.Password = "xyzzy"

connect.Metadata = "customer"

' connect to DB2

connect.Connect

' now perform the catalog action — in this case,

' for fields in the 'customer' table.

If (connect.Catalog (LCOBJECT_FIELD, conFldLst) = 0) Then

Print "No tables were found (table does not exist)."

Else

' fetch the results

Dim nameField As LCField, typeField as LCField

Set nameField = conFldLst.GetField(1)

Set typeField = conFldLst.GetField(2)

Print "The list of columns in the '" & _ connect.Metadata & "' table include:"

While (connect.Fetch (conFldLst) > 0)

Print " " & field.text(0)

Wend

End If

End Sub


Example OutputThe list of columns in the 'CUSTOMER' table include:

ACCOUNTMANAGER

CONTACTNAME

COMPANYNAME

COMPANYADDRESS

COMPANYCITY

COMPANYSTATE

COMPANYPHONE

Catalog Method for LCConnection using Lotus Connector for DB2This method produces a result set containing requested information. Theinformation is determined by the ObjectType parameter. Not all objecttypes are supported.

Returns the input and output parameters of aprocedure. A call to LCXCatalog with thisObjectType is in error if a procedure name does notexist.

LCOBJECT_PARAMETER

Returns the procedure name, and procedure owner(used with stored procedures).

LCOBJECT_PROCEDURE

Returns the field name, field owner, a comment,field type * and native data type name.

* This ObjectType returns the input and outputparameters of a procedure. A call to LCXCatalogwith this ObjectType is in error if a procedure namedoes not exist.

LCOBJECT_FIELD

Is not supported for DB2.LCOBJECT_INDEX

Returns metadata name, metadata owner, and acomment.

LCOBJECT_METADATA

Returns database name, database owner, and acomment.

LCOBJECT_DATABASE

Is not supported for DB2.LCOBJECT_SERVER



Connect Method for LCConnectionThis method establishes a connection to a Connector. Multiple connectionsmay be independently established to a single connector.

For the Lotus Connector for DB2, this method establishes a connection toDB2 using required properties Database, UserName, and Password.

If the connection attempt fails, an error will occur. Refer to the section on“Error Messages” for possible errors.


SyntaxlcConnection.Connect


Uselsx "*lsxlc"

Sub Initialize


' set the appropriate properties to connect to DB2

' note the use of dynamic properties to do this

' all properties of a connection may be referenced

' by name




' try the connect

On error go to Trap

connect.Connect

Print "Successfully connected to DB2."

Exit Sub

Trap:

Print "Connection failed with error " & err & ": " & error

Exit Sub

End Sub


Example OutputSuccessfully connected to DB2.

Copy Method for LCConnectionThis method makes a copy of an existing connection, including all propertyvalues. Note that while all properties are copied, the current state of theconnection and result set are not copied.


SyntaxSet newConnection = lcConnection.Copy()

Parameters

The connection object that you want to copy.lcConnection


Return Value

The copy of the lcConnection object.newConnection

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize




Dim connect1 As New LCConnection ("db2")

Dim connect2 As LCConnection

' set the appropriate properties to connect to DB2

' note the use of dynamic properties to do this

connect1.Database = "Gold"

connect1.Userid = "JDoe"

connect1.Password = "xyzzy"


' now copy the connect

Set connect2 = connect1.Copy

If (connect2.Database = connect1.Database) Then

Print "The copy of connection has the same database as theoriginal."

Else

Print "The copy of connection has a different database fromthe original."

End If

End Sub

Example OutputThe copy of connection has the same database as the original.

Create Method for LCConnectionThis method creates a metadata object. Each Connector supports onlycertain object types. Refer to the documentation for the specific Connectorto determine the object types it supports.

For the Lotus Connector for DB2, this method creates an object in DB2. OnlyLCOBJECT_METADATA and LCOBJECT_INDEX are supported for DB2.


SyntaxCall lcConnection.Create(objectType, srcFieldlist)

Parameters

continued

LCOBJECT_SERVERCreates a server object (obtaining the name from the SERVERproperty). Additional information may be provided inConnector-specific properties. Not supported for DB2.

Long. Type of object. Valid types and associated behavior includethe following (refer to the documentation for the specific connectorto determine which of the following are supported):

objectType



LCFieldlist. Fieldlist from whose metadata or key fields the object iscreated. This parameter is ignored for object types SERVER andDATABASE.

srcFieldlist

LCOBJECT_FIELDCreates a field object (the metadata being appended to is inMETADATA property). The fields to append to the metadata willhave the same order, types, and names as fields in the fieldlist.Fields with the flag LCFIELDF_NO_CREATE are skipped. Notsupported in DB2.

LCOBJECT_INDEXCreates an index object (the metadata being indexed is inMETADATA property, the index name to create is in INDEXproperty). The key fields for the new index are fields in the fieldlistwith the LCFIELD_KEY flag set. For example, this creates an indexin DB2.

LCOBJECT_METADATACreates a metadata object (obtaining the name from theMETADATA property). The fields in the new metadata will havethe same order, types, and names as fields in the fieldlist. Fieldswith the flag LCFIELDF_NO_CREATE are skipped. For example,this creates a table in DB2.

LCOBJECT_DATABASECreates a database object (obtaining the name from the DATABASEproperty, and optionally the server name from the SERVERproperty). Additional information may be provided inConnector-specific properties. Not supported for DB2.



Option Explicit

Uselsx "*lsxlc"

Sub Initialize


Dim fldLstRecord As New LCFieldList

Dim fld As LCField

' build the table definition

' note the use of the 'MaxLength' parameter

' this is used to more closely control the datatype creation

' within the connection — in this case DB2


' in DB2, a text stream with a MaxLength of 64 will becreated

' as VARCHAR(64). if the flag LCSTREAMF_FIXED was used

' the column would be CHAR(64). The field flagLCFIELDF_NO_NULL

' would add NOT NULL to the column definition

Call FldLstRecord.Append ("ACCOUNTMANAGER", LCTYPE_INT)

Set fld = FldLstRecord.Append ("CONTACTNAME", LCTYPE_TEXT)

Call fld.SetFormatStream (0, 64, LCSTREAMFMT_LMBCS)

Set fld = FldLstRecord.Append ("COMPANYNAME", LCTYPE_TEXT)


Set fld = FldLstRecord.Append ("COMPANYADDRESS", LCTYPE_TEXT)


Set fld = FldLstRecord.Append ("COMPANYCITY", LCTYPE_TEXT)


Set fld = FldLstRecord.Append ("COMPANYSTATE", LCTYPE_TEXT)


Set fld = FldLstRecord.Append ("COMPANYPHONE", LCTYPE_TEXT)




src.Userid = "JDoe"



src.Connect

' create it based on the metadata property already set above

On Error LCFAIL_DUPLICATE Goto tableexists

Call src.Create (LCOBJECT_METADATA, fldLstRecord)

Print "The '" & src.Metadata & "' table was created."

End

tableexists:

Print "The '" & src.Metadata & "' table exists."


End

End Sub

Example OutputThe 'customer' table was created.

Disconnect Method for LCConnectionThis method disconnects from a data source. Any existing result set iscleared. For example, this method terminates the connection to DB2 estab-lished by the Connect method. Only the connection and state areterminated, in order that reconnection may occur.

A disconnect also happens automatically when the LCConnection object isdeallocated.

Because disconnecting may involve automatic commit or rollback (depend-ing on the Connector type and the settings of the database in question), thismethod may fail with an error.

Note Since some connections may commit changes when disconnected,while others may roll back changes, it’s probably best to use the Actionmethod to commit or roll back changes yourself if you’re in any doubt.

Note If your program enables connection pooling, the connection willremain active in the pool even after you explicitly call Disconnect. In thiscase, automatic commit or rollback will not occur, and you must manuallycommit or revoke any changes you have made.


SyntaxCall lcConnection.Disconnect


Uselsx "*lsxlc"

Sub Initialize


' set appropriate properties to connect to DB2




connect. Password = "DBINST1"

' connect to DB2 then disconnect

connect.Connect

Print "Successfully connected to DB2."

' now lets disconnect

connect.Disconnect

Print "Successfully disconnected from DB2."

End Sub

Example OutputSuccessfully connected to DB2.Successfully disconnected from DB2.

Drop Method for LCConnectionThis method deletes (drops) a specified metadata object — database, table,index, or view. The object isn’t just removed from your local memory; it’sirretrievably destroyed. Use this method with caution.

Each Lotus Connector supports only certain object types. Refer to thedocumentation for the specific Connector to determine the object types itsupports. For example, for DB2, this method drops a DB2 object and onlyLCOBJECT_METADATA and LCOBJECT_INDEX are supported.


SyntaxCall lcConnection.Drop(objectType)

Parameters

continued

LCOBJECT_DATABASEDrops a database object (obtaining the name from the DATABASEproperty, and optionally the server name from the SERVER property).

LCOBJECT_SERVERDrops a server object (obtaining the name from the SERVER property).

Long. Type of object: Valid types and associated behavior are thefollowing (refer to Appendix C for the specific Connector to determinewhich of the following are supported):

objectType



LCOBJECT_FIELDDrops a field object (metadata containing fields is in METADATAproperty, the fields being removed are in the FieldNames property).

LCOBJECT_INDEXDrops an index object (the metadata indexed is in METADATAproperty, the index name to drop is in INDEX property).

LCOBJECT_METADATADrops a metadata object (obtaining the name from the METADATAproperty).



Option Explicit

Uselsx "*lsxlc"

Sub Initialize


' set properties to connect to the data source


src.Userid = "JDoe"



src.Connect

On Error Goto NoMetadata

Call src.Drop (LCOBJECT_METADATA)

Print "The '" & src.Metadata & "' table existed and had beendeleted."

End

NoMetadata:

Print "The '" & src.Metadata & "' table did not exist."

End

End Sub

Example OutputThe 'customer' table existed and had been deleted.


Execute Method for LCConnectionThis method executes a statement in Connector-specific syntax, forexample, an SQL statement for a relational database Connector. Forexample, this method executes a DB2 SQL statement for the purposes ofproducing a result set.


Syntaxcount = lcConnection.Execute(statement, destFieldlist)

Parameters

Long. LCFieldlist. Fieldlist to contain the metadata of the executeresult set. The fields in the result set will be appended to thisfieldlist. If the result set metadata is not required, use Nothing.

destFieldList

String. The statement to execute in the syntax defined for theconnector. See the documentation for the specific connector forinformation about the required syntax.

statement


Return Value

Long. Number of records selected or affected by this statement. If this number cannot be determined by the connector, theconstant LCCOUNT_UNKNOWN is returned.

count

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize


Dim fldLst As New LCFieldList

Dim fld As LCField

Dim count As Integer

' set the appropriate properties to connect


src.Userid = "JDoe"



src.Connect

' now connected, we can execute a selection statement

If (src. Execute ("SELECT * from customer", fldLst) = 0) Then

Print "No records were fetched."

End

End If

Set fld = fldLst.Lookup ("CONTACTNAME")

Print "the 'contact names' stored in the table are:"

' fetch each record from the result set

While (src.Fetch (fldLst) > 0)

count = count + 1

Print " record #" & Cstr(count) & " = '" & fld.text(0) &"'"

Wend

If (count = 0) Then Print "No records were fetched."

End Sub

Example OutputThe 'contact names' stored in the table are:

record #1 = 'Peter Soames

record #2 = 'Trent Kent'

record #3 = 'Joan Lawrens'

Fetch Method for LCConnectionThis method obtains the next group of records from a result set. Thismethod requires an active result set in the Connection.


Syntaxcount = lcConnection.Fetch(destFieldlist, recordIndex, recordCount)


Parameters

Long. Optional, >=1. Number of records to fetch. The number ofrecords actually fetched may be less than this number if the end ofthe result set was reached. While all Connectors can fetch multiplerecords, only Connectors which indicate support for Array Fetchperform a true multi-record fetch and therefore reduce networktraffic and increase performance. Default is 1.

recordCount

Long. Optional, >=1. Starting record index in the fieldlist where therecord will be stored. Default is 1.

recordIndex

LCFieldlist. Fieldlist to receive the data. For each field in Fieldlistwithout the flag LCFIELDF_NO_FETCH, data from thecorresponding field in the result set will be copied into that field.Fields in the result set and fieldlist are matched by name if theMapByName property is TRUE, by position otherwise, and aretype-checked before retrieving data.

destFieldlist


Return Value

Long. Number of records successfully fetched.count

DescriptionValue

Usage NotesYou can achieve optimal performance by using the same fieldlist acrossconsecutive fetches from the same target.

To use the recordCount parameter to retrieve multiple records, or to use arecordIndex greater than 1, you must supply a destFieldList that hasalready been allocated to contain multiple rows of data. Refer to the Newmethod of LCFieldlist for details.

The default operation of Fetch is to map the fields in the data source to thefields in your field list by position — the first field read goes into the firstfield in your fieldlist, the second field goes into the second field in the fieldlist, and so on. You can use the LCConnection.MapByName propertyto make LC fill in fields by matching their names with the names in thefieldlist, regardless of the order in which the data source returns them.

It is advisable to use the same LCFieldlist object for the Fetch as you used inthe call to Select, Catalog or Execute. This gives you optimal performance.


Uselsx "*lsxlc"

Sub Initialize




Dim keyLst As New LCFieldList

Dim fld As LCField


' set the appropriate properties to connect to the datasource


src.Userid = "JDoe"



src.Connect

' the FIELDNAMES property of a connection is used to

' specify which fields should be used in the result set

' if no names are listed, then all fields will be fetched

src.FieldNames = "ContactName, AccountManager"

' the select statement may be called with 'Nothing' as

' the keylist parameter. this causes all records to be

' selected for the result set.

' by creating a keylist with one or more keys, conditions,

' and values, tighter control of the result set is possible

' here we want to indicate all account managers except

' number 200

' NOTE: to indicate that a field is a key, the LCFIELDF_KEYflag

' must always be included in the value of the connection'sflags

Set fld = keyLst.Append ("ACCOUNTMANAGER", LCTYPE_INT)

fld.Flags = LCFIELDF_KEY_NE Or LCFIELDF_KEY

fld.Value = 200

' the selection statement builds an international result setwhich

' is later accessed with successive fetches


If (src.Select (keyLst, 1, fldLst) = 0) Then

Print "No data were located."

End

End If

Set fld = fldLst.Lookup ("CONTACTNAME")

Print "the 'contact names' stored in the table are:"

' fetch a record from the result set

While (src.Fetch (fldLst) > 0)

count = count + 1

Print " record #" & Cstr(count) & " = '" & fld.text(0) & "'"

Wend

If (count = 0) Then Print "The table contains no records."

End Sub

Example Outputthe 'contact names' stored in the table are:

record #1 = 'Peter Soames

record #2 = 'Trent Kent'

record #3 = 'Joan Lawrens'

Fetch Method for LCConnection for the Lotus Connector for DB2This method retrieves one or more records from the current result set.

The function requires that a result set was previously produced by theLCConnection methods Execute, Select, Call, or Catalog. The result set datais type-checked against and then moved into the supplied DestFieldlist.Fields with the flag LCFIELDF_NO_FETCH set are not fetched.

The property MAP_NAME indicates whether to map fields in DestFieldlistand the result set by name or position. Handling of both mapping and fieldflags is implicitly done by calling LCFieldlistMerge with the result set fieldnames as NameFieldlist, DestFieldlist as DataFieldlist, and MergeFlagsLCMERGEF_NAME_LOSS, LCMERGEF_FETCH, and optionally (depend-ing on the MAP_NAME property) LCMERGEF_MAP_NAME.

For non-scrollable result sets, each record in the result set is fetched exactlyonce and only in a forward direction. LCFAIL_END_OF_DATA should bereturned when the last call to LCXFetch retrieved the last record in theresult set. If at least one record was fetched but the end of the result set wasreached before fetching RecordCount records, LCSUCCESS is returned.


For scrollable result sets produced by LCXExecute or LCXSelect with theproperty LCTOKEN_SCROLLABLE set, backwards fetching is performedstarting with the record before the most recently fetched record and movingbackwards in the result set.

GetProperty Method for LCConnectionThis method retrieves a copy of the current value for a connection property.Note that use of dynamic properties is more efficient. For example, thismethod returns the value of a Lotus Connector for DB2 property, specifiedby the PropertyToken parameter, in the DestField parameter. For DB2, allproperties are supported except Password.

If the property is not supported for the Connector, GetProperty will gener-ate the error LCFAIL_INVALID_PROPERTY.

Note Although properties with a text value return a field with a Streamdata type, the LCField.GetFormatStream method does not returninformation about the property (for example, the maximum length).Consult the documentation of the external database system for thisinformation.


SyntaxSet destField = thisConnection.GetProperty(propertyToken)

Parameters

Long. Token representing the connector property for which thevalue is returned. See Appendix B for a list of tokens.

propertyToken


Return Value

LCField. The value of the connection property whose token ispropertyToken.

destField



Option Explicit

Uselsx "*lsxlc"

Sub Initialize



Dim conFld As LCField

' get the value of the server property

Set conFld = connect.GetProperty (LCTOKEN_WRITEBACK)

Print "The writeback property value is: " & conFld.text(0)

End Sub

Example OutputThe writeback property value is: 0

GetProperty<Type> MethodsThis method returns a Connector property value as a specific data type.Supported data types include Boolean, Currency, Datetime, Float, Int,Numeric, and Text.

This method allows retrieval of Connect properties as withLCConnection.GetProperty, but does not require a field object. If theproperty value is of a different type, data conversion will be performed.The value of the password property cannot be obtained with this function,and will result in an INVALID_PROPERTY error.


Syntaxflag = lcConnection.GetPropertyBoolean(propertyToken, default)

Set destCurrency = lcConnection.GetPropertyCurrency(propertyToken)

Set destDatetime = lcConnection.GetPropertyDatetime(propertyToken)

destFloat = lcConnection.GetPropertyFloat(propertyToken)

destInt = lcConnection.GetPropertyInt(propertyToken)

Set destNumeric = lcConnection.GetPropertyNumeric(propertyToken)

Set destStream = lcConnection.GetPropertyStream(propertyToken, streamFor-mat)


Parameters

(GetPropertyStream only) Format that the stream is converted tobefore being returned. If streamFormat is zero, no conversion occursand the stream is copied in the same format as the property value.Otherwise, use a stream format flag as described in the section“Stream Format” in Chapter 5.

streamFormat

(GetPropertyBoolean only) Value to be returned if the propertycannot be located. Default value is FALSE.

default

A token identifying the Connection property. See Appendix B for alist of property tokens.

propertyToken


Return Values

Current value for the connector property.dest<Type>

GetPropertyBoolean only. Boolean value, either TRUE or FALSE. Ifthe property does not exist, the default is returned.

flag

DescriptionValue

ExamplesOption Public

Uselsx "*lsxlc"

Sub Initialize

Dim connect As New LCConnection ("oracle")


Dim propName As String

Dim propDate As LCDateTime

Dim propNumeric As LCNumeric

Dim propStrm As LCStream

Dim propCurr As LCCurrency

Dim propFloat As Double

Dim propInt As Long

Dim propBool As Variant

Dim tokenId As Long

Dim propType As Long

Dim propFlags As Long

' set some connector properties


connect.Server = "Rainbow"



' it is not necessary to connect to list properties

Call connect.ListProperty (LCLIST_FIRST, _

tokenId, propType, propFlags, propName)

Print "NAME" Tab(20); "ID"; Tab(28); "FLAGS"; _

Tab(36); "TYPE"; Tab(48); "VALUE"

Print "-————————" Tab(20); "———"; Tab(28); "———"; _

Tab(36); "—————"; Tab(48); "—————"

Do

Set conFld = connect.GetProperty (tokenId)

' match the property to a datatype and fetch it as thatdatatype

Select Case propType

Case LCTYPE_DATETIME:

Set propDate = connect.GetPropertyDatetime (tokenId)

Print propName; Tab(20); Hex(tokenId); Tab(28);Hex(propFlags); _

Tab(36); "LCDatetime"; Tab(48); propDate.text

Case LCTYPE_NUMERIC:

Set propNumeric = connect.GetPropertyNumeric (tokenId)


Tab(36); "LCNumeric"; Tab(48); propNumeric.text

Case LCTYPE_TEXT:

Set propStrm = connect.GetPropertyStream (tokenId,LCSTREAMFMT_NATIVE)


Tab(36); "LCStream"; Tab(48); propStrm.text

Case LCTYPE_CURRENCY:

Set propCurr = connect.GetPropertyCurrency (tokenId)



Tab(36); "LCCurrency"; Tab(48); propCurr.text

Case LCTYPE_FLOAT:

propFloat = connect.GetPropertyFloat (tokenId)


Tab(36); "Double"; Tab(48); Cstr(propFloat)

Case LCTYPE_INT:

If (propFlags And LCPROPERTYF_BOOLEAN) Then

propBool = connect.GetPropertyBoolean (tokenId, False)


Tab(36); "Boolean"; Tab(48); Cstr(propBool)

Else

propInt = connect.GetPropertyInt (tokenId)


Tab(36); "Long"; Tab(48); Cstr(PropInt)

End If

End Select

Loop _

While connect.ListProperty (LCLIST_NEXT, _


End Sub

Example OutputNAME ID FLAGS TYPE VALUE

----------------- ------ ------ ---------- ----------

Name 30004 4 LCStream oracle

IsConnected 3000C 6 Boolean False

Server 10001 1 LCStream mycyclone

Userid 10003 1 LCStream scott

Metadata 10005 0 LCStream


Index 10006 0 LCStream

MapByName 10007 2 Boolean False

Writeback 10008 2 Boolean False

Condition 1000B 0 LCStream

StampField 1000C 0 LCStream

BaseStamp 1000D 0 LCDatetime

MaxStamp 1000E 0 LCDatetime

TextFormat 1000F 4 Long 65535

CharacterSet 30008 4 LCStream NATIVE

Procedure 10010 0 LCStream

Owner 10011 0 LCStream

AlternateMetadata 10013 2 Boolean False

CommitFrequency 1 0 Long 0

RollbackOnError 2 2 Boolean False

CreateLongColumn 3 0 LCStream

CreateLongByUser 4 0 Long 0

TraceSQL 5 2 Boolean False

Insert Method for LCConnectionThis method inserts a specified number of records into the connectionmetadata. For example, this method inserts one or more records into thedefined METADATA object in DB2.

Note You can achieve optimal performance by using the same fieldlistacross consecutive inserts from the same target.


Syntaxcount = lcConnection.Insert(srcFieldlist, recordIndex, recordCount)


Parameters

Long. Optional, >=1. Number of records to insert. The number ofrecords actually inserted may be less than this number if an errorwas encountered. While all Connectors can insert multiplerecords, only Connectors that indicate support for Array Insertperform a true multi-record insert and therefore reduce networktraffic and increase performance. The default is 1.

To use the recordCount parameter to write multiple records, or touse a recordIndex greater than 1, you must supply a destFieldListthat has been allocated to contain multiple rows of data. Refer tothe New method of LCFieldlist for details.

recordCount

Long. Optional, >=1. Starting record index of the insert in thefieldlist. The default is 1.

recordIndex

LCFieldlist. Fieldlist containing the records to insert. For eachfield in Fieldlist without the flag LCFIELDF_NO_INSERT, datafrom the corresponding field in the result set will be copied intothat field. Fields in the result set and fieldlist are matched byname if the MapByName property is TRUE, by positionotherwise, and are type-checked before inserting data.

srcFieldlist


Return Value

Long. Number of records successfully inserted.count

DescriptionValue

Usage NotesIf there is an error midway through a multiple record insert operation, anerror event will occur. The changes up to that point will not be committed,and you should use the Action method to rollback or commit.


Uselsx "*lsxlc"

Sub Initialize


Dim fields As New LCFieldList (5)

Dim field As LCField

Dim data(4) As String

Dim idata(4) As Long


' set the appropriate properties to connect to the datasources


src.Userid = "JDoe"



src.MapByName = True

' connect to the two data sources

src.Connect

' use a key to find certain records to remove

Set field = fields.Append ("ACCOUNTMANAGER", LCTYPE_INT)

idata(0) = 100

idata(1) = 200

idata(2) = 300

idata(3) = 400

idata(4) = 500

field.value = idata

Set field = fields.Append ("CONTACTNAME", LCTYPE_TEXT)

data(0) = "Peter Pan"

data(1) = "Big Steel"

data(2) = "R. U. Happy"

data(3) = "Isaac Bernard Mathews"

data(4) = "Paula Falderall"

field.value = data

Set field = fields.append ("COMPANYADDRESS", LCTYPE_TEXT)

data(0) = "One Bit Tree"

data(1) = "Gurder Way"

data(2) = "Daisy Hill Pup Farm"

data(3) = "Big Blue Ave."

data(4) = "Planet Hollywood"

field.value = data

Set field = fields.Append ("COMPANYCITY", LCTYPE_TEXT)


data(0) = "Never Never"

data(1) = "Iron"

data(2) = "Beagle"

data(3) = "New York"

data(4) = "Parthenon"

field.value = data

Set field = fields.Append ("COMPANYSTATE", LCTYPE_TEXT)

data(0) = "Land"

data(1) = "PA"

data(2) = "WI"

data(3) = "NY"

data(4) = "AQ"

field.value = data

' Create new records from the five records in the fieldlist.

Print "Inserted " & Cstr (src.Insert (fields, 1, 5)) & "record(s)."

End Sub

Example OutputInserted 5 record(s).

ListProperty Method for LCConnectionThis method obtains the first or next property information for propertiessupported by this connector.


Syntaxresult = lcConnection.listProperty (list, propertyToken, dataType, propertyFlags,propertyName)


Parameters

String. Output, optional. Name of the property.PropertyName

LCPROPERTYF_TEXTLIST: Property is a text list

LCPROPERTYF_READONLY: Property is read-only

LCPROPERTYF_BOOLEAN: Property is a boolean value

LCPROPERTYF_CONNECT: Property is used for connecting

Long. Output, optional. Property flags for the property; one ormore of the flags below ORed together.

propertyFlags

Long. Output, optional. Data type of the property.dataType

Long. Output, optional. Token assigned to the property.propertyToken

LCLIST_NEXT: Return the next property (or the first propertyif this is the first call to this function for this Connection).

LCLIST_FIRST: Return the first property in the property list.

Long. Constant indicating whether to return the first or nextconnector property.

list


Return Value

Boolean. TRUE if property information was returned, orFALSE if there are no more properties to list.

result

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize




Dim tokenId As Long



' set some connector properties

connect.Server = "Rainbow"




connect.Metadata = "scott.bigtable"

connect.FieldNames = "name, address, city, state, zipcode,phone"

Print "NAME" Tab(20); "ID"; Tab(26); "FLAGS"; _

Tab(32); "TYPE"; Tab(38); "VALUE"

Print "-————————" Tab(20); "-——"; Tab(26); "-——"; _

Tab(32); "——"; Tab(38); "——————"

' all of the parameters are optional and any may be omitted

Call connect.ListProperty (LCLIST_FIRST,_


Do



Tab(32); propType; Tab(38); conFld.Text(0)

Loop While connect.ListProperty (LCLIST_NEXT, _


End Sub

Example OutputNAME ID FLAGS TYPE VALUE

----------------- ----- ----- ---- ------------

Name 30004 4 6 oracle

IsConnected 3000C 6 1 0

Server 10001 1 6 mycyclone

Userid 10003 1 6 scott

Password 10004 1 7

Metadata 10005 0 6 scott.bigtable

Index 10006 0 6

MapByName 10007 2 1 0

Writeback 10008 2 1 0

OrderNames 1000A 8 7


FieldNames 10009 8 7 name, address, city,state, zipcode, phone

Condition 1000B 0 6

StampField 1000C 0 6

BaseStamp 1000D 0 5

MaxStamp 1000E 0 5

TextFormat 1000F 4 1 65535

CharacterSet 30008 4 6 NATIVE

Procedure 10010 0 6

Owner 10011 0 6

AlternateMetadata 10013 2 1 0

CommitFrequency 1 0 1 0

RollbackOnError 2 2 1 0

CreateLongColumn 3 0 6

CreateLongByUser 4 0 1 0

TraceSQL 5 2 1 0

LookupProperty Method for LCConnectionThis method determines if a connector supports a specified property.


Syntaxflag = lcConnection.LookupProperty(propertyToken, dataType, propertyFlags,propertyName)

Parameters

LCPROPERTYF_READONLY: Property is read-only.

LCPROPERTYF_BOOLEAN: Property is a boolean value.

LCPROPERTYF_CONNECT: Property is used for connecting.

Long. Output optional. The property flags from the following list.propertyFlags

Long. Output optional. The property data type.dataType

A token identifying the Connection property. See Appendix B for alist of property tokens.

propertyToken



String. Output optional. The name of the property.propertyName

LCPROPERTYF_TEXTLIST: Property is a text list.


Return Value

Integer. TRUE or FALSE, indicating whether the property issupported for this connection.

flag

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize


' note that a connect is not necessary to list and look upproperties

' the parameters are optional, to text for the existence of aproperty

' simply provide the TOKEN parameter

If (connect.LookupProperty (LCTOKEN_SERVER)) Then

Print "Oracle has a 'Server' property"

Else

Print "Oracle does not have a 'Server' property"

End If

If (connect.LookupProperty (LCTOKEN_DATABASE)) Then

Print "Oracle has a 'Database' property"

Else

Print "Oracle does not have a 'Database' property"

End If

End Sub

Example OutputOracle has a 'Server' property.

Oracle does not have a 'Database' property.


Remove Method for LCConnectionThis method performs either a writeback result set remove or a keyedremove of records in the external system.


Syntaxcount = lcConnection.Remove(keyFieldlist, recordIndex, recordCount)

Parameters

Long, >=1. Optional. Number of keyed remove operations to perform.RecordCount must be 1 for a writeback remove but may be greater toperform multiple keyed updates with different update and keyvalues. The default is 1.

recordCount

Long, >=1. Optional. Starting record index in the fieldlist. The defaultis 1.

recordIndex

LCFieldlist. Fieldlist containing keys for a keyed remove only. Foreach field in the Fieldlist with the flag LCFIELDF_KEY set, onlyrecords in the connection with the same value for that field aredeleted. Use LCFIELDF_KEY_XXX flags as inequality keys, if desired.Zero or more key fields may be supplied, with zero keys resulting inall records in the target being deleted. Fields in the connection andfieldlist are matched by name if the MapByName property is TRUE,by position otherwise.

keyFieldlist


Return Value

Long. Number of records successfully removed. If this number cannotbe determined, the constant LCCOUNT_UNKNOWN is returned.

count

DescriptionValue

Usage NotesYou can achieve optimal performance by using the same fieldlist acrossconsecutive removes from the same target.

The property Writeback indicates whether to perform a writeback or keyedremove:


• Writeback remove: If the Writeback property is set True, this method removes the most recently fetched record from the writebackresult set (the result set produced by LCConnection.Execute,LCConnection.Select or LCConnection.Call with the Writebackproperty set). The key field list and Condition property do not have any effect on a Writeback operation.

• Keyed remove: Removes all records in the supplied metadata with fieldvalues matching all fields in the fieldlist that have the LCFIELDF_KEYfield flag set. If a value is specified for the property Condition, this willbe included in the key search criteria. This value must be in a syntaxvalid for the relevant connector. See the documentation for theconnector for information about its supported syntax.

When using inequality key flags GT, LT, and NE, it is important to remem-ber that the default of no flags is equal. The following combinations arevalid for inequality flags:

• equal to LCFIELDF_KEY

• greater than or equal to LCFIELDF_KEY + LCFIELDF_KEY_GT

• less than or equal to LCFIELDF_KEY + LCFIELDF_KEY_LT

• not equal to LCFIELDF_KEY + LCFIELDF_KEY_NE

• greater than LCFIELDF_KEY + LCFIELDF_KEY_GT +LCFIELDF_KEY_NE

• less than LCFIELDF_KEY + LCFIELDF_KEY_LT + LCFIELDF_KEY_NE

• string pattern matching LCFIELDF_KEY + LCFIELDF_KEY_LIKE

If you supply more than one key field comparison in your keyFieldList,effectively you are “and”ing the tests — LCConnection will remove recordsthat meet all the tests. Likewise if you supply one or more key tests and anadditional test in the Condition property.

LCConnection does not directly support logical “or” operations of multipleconditions. You can, however, execute any query usingLCConnection.Execute, or construct an “or” type query in the Conditionfield, using the query language supported by the connector.

The rules for pattern matching in a “like” comparison vary depending onthe Connector. Consult your database documentation for details.


Uselsx "*lsxlc"

Sub Initialize



Dim keyList As New LCFieldList

Dim key As LCField



src.Userid = "JDoe"



src.MapByName = True


src.Connect

' use a key to find certain records to remove

Set key = keyList.Append ("ACCOUNTMANAGER", LCTYPE_INT)

key.Flags = LCFIELDF_KEY

key.value = 200

' we can perform a keyed delete of the matching record in thetable

Print "Removed " & Cstr (src.Remove (keyList)) & " record(s)"

End Sub

Example OutputRemoved 2 record(s).

Remove Method for LCConnection for DB2This method deletes records from a writeback result set or keyed search inthe METADATA object in DB2.

The LCXRemove method operates in one of two modes, depending if theWRITEBACK property is set and there is a current result set that supportswriteback.

A writeback result set is one in which modifications can be made directly tothe most recently Fetched record. This is often more efficient than a keyedoperation. To support writeback, the WRITEBACK property must be setprior to producing the result set with Execute or Select (Call and Catalog donot support writeback result sets). This produces a writeback result set.Once a record has been Fetched, that record is available for writebackUpdate and Remove operations. When these methods are called with the


WRITEBACK property set, the operation affects the most recently Fetchedrecord. If the WRITEBACK property is not set, these methods operate usingkeys, even if the result set is a writeback result set.

Non-writeback RemovesOne or more keyed removes are performed against the metadata indicatedby the METADATA property. For each record used as key values, a keyedremove constructed from those key values should be performed. Any valuefor the CONDITION property should be included in the search criteria.

Only fields with the flag LCFIELDF_KEY should be used as key values.

The property MAP_NAME indicates whether to map fields in KeyFieldlistand the target metadata by name or position. Handling of both mappingand field flags is implicitly handled by calling LCFieldlistMerge with thetarget metadata field names as NameFieldlist, KeyFieldlist as DataFieldlist,and MergeFlags LCMERGEF_NAME_LOSS, LCMERGEF_REMOVE,LCMERGEF_KEY, and optionally (depending on the MAP_NAMEproperty) LCMERGEF_MAP_NAME.

Writeback RemovesThere must be a current result set which supports writeback operations anda previous LCXFetch from that result set. The last document fetched by themost recent LCXFetch call is deleted.

Select Method for LCConnectionThis method produces a result set from the current METADATA propertyand other properties.


Syntaxcount = lcConnection.Select (keyFieldlist, recordIndex, destFieldlist)

Parameters

LCFieldlist. Selection keys. All fields in KeyFieldlist with theLCFIELDF_KEY flag set are used as the selection keys. Only recordsin the connection with the same value for key fields will be selected.Additional LCFIELDF_KEY_XXX flags (GT — greater than, LT — lessthan, NE — not equal) allow inequality keys to be used. Zero or morekey fields may be supplied to restrict the result set. No keys orNothing will select all records for the result set.

keyFieldlist



LCFieldlist. Fieldlist to contain the metadata of the selected result set.The fields in the result set will be appended to this fieldlist. If theresult set metadata is not required, use Nothing.

destFieldlist

Long, >=1. Record index position in the key fieldlist from which toobtain the record containing key field values.

recordIndex


Return Value

Long. Number of records in the result set. If this number cannot bedetermined by the connector, the constant LCCOUNT_UNKNOWN isreturned.

count

DescriptionValue

Usage NotesIf you supply a key fieldlist, the selection conditions in the fieldlist will be“and”ed together — LCConnection will only select records that match allthe conditions. Only the key list fields with the LCFIELDF_KEY flag set,will be used as selection criteria.

If you set the Condition property of the connection, this search conditionalso will be “and”ed with the conditions in the key list to further limit therecords returned.

LCConnection does not directly support logical “or” operations of multipleconditions. You can, however, compose the query yourself using the backend system’s query language. Either use LCConnection.Execute to executethe custom query, or use the LCConnection.Condition property with Select.See the documentation for the connector for information about itssupported syntax.

Set the Writeback property before using Select to indicate whether youwant the result set to be writeback capable. This does not affect whichrecords are returned in the result set, but it does affect whether you can doa writeback Update or Remove on them as you’re iterating through them.










The rules for pattern matching in a “like” comparison vary depending onthe connector. Consult your database documentation for details.


Uselsx "*lsxlc"

Sub Initialize






src.Userid = "JDoe"




src.Connect

' now connected, we can execute a selection statement

count = src.Select (Nothing, 1, fldLst)

Select Case count

Case LCCOUNT_UNKNOWN

Print "An overview number of records were located."

Case 0

Print "No data were located."

Case Else

Print "The table contains " & Cstr(count) & " records."

End Select

End Sub

Example OutputAn overview number of records were located.


Select Method for LCConnection for DB2This method produces a result set from the defined METADATA object inDB2.


The following properties are used by Select to refine the result set contentsand properties:

If supported, any result set produced should be limited to thismany records. A value of zero (the default) indicates no limit.

RECORD_LIMIT

If supported, determines whether the result set producedshould support backwards movement as well as forwards.

SCROLLABLE

If STAMPFIELD is set, obtains the current datetime from thedata source and sets it as the value of this property. Only selectrecords with STAMPFIELD less than or equal to this value.Ignore this property if STAMPFIELD is not set.

MAXSTAMP

If STAMPFIELD is set, provides the base datetime for theselection. Only select records with STAMPFIELD greater thanBASESTAMP. Ignore this property if STAMPFIELD is not set.

BASESTAMP

Provides a field name to be used as a timestamp/boundary. Ifthis value is set, then the Connector should check BASESTAMPfor a minimum datetime value. In addition, the Connectorshould request the current time from the data provider, set theMAXSTAMP property to this value, and include it as an uppertime bound.

STAMPFIELD

Provides a conditional clause to be embedded in the internalstatement produced. This value is supplied in a syntax definedby each individual Connector.

CONDITION

Provides a text list of fields by which to order the result setdata in ascending order, from first to last. Specify no value foran unordered result set. Multiple fields can be specified with atext list or as text with comma or semicolon separated values.

ORDERNAMES

Provides a list of fields to include in the result set. Only fieldsin this text list should be included in the result set, in the orderprovided. The fields in the fieldlist will be in the order in thislist (to order the actual record values, use ORDERNAMES).Specify no value to include all metadata fields. Multiple fieldscan be specified with a text list or as text with comma orsemicolon separated values.

FIELDNAMES

If supported, determines whether to produce a writeback resultset or not. If TRUE, the result set produced should supportwriteback versions of LCXUpdate and LCXRemove. Awriteback result set generally locks the source metadata.

WRITEBACK

Indicates the metadata in the connection containing the targetrecords.

METADATA

DescriptionProperties


Key Flag RulesKeys in the key fieldlist provide conditional key values. The default condi-tion is equality, but field flags allow other options.

When checking inequality key flags GT, LT, and NE, the default of no flagsis equal.

The following combinations are valid for inequality flags:







In addition, the flag LCFIELDF_KEY_LIKE may be combined withLCFIELDF_KEY to perform a similarity comparison. Support for and thebehavior of a LIKE comparison depends on the Connector being used.

Note The LIKE key flag may not be used in conjunction with anyinequality key flags.

SetProperty Method for LCConnectionThis method assigns the value for a connection property. For DB2, allproperties are supported.


SyntaxCall thisConnection.SetProperty(propertyToken, srcField)

Parameters

LCField. New value for the connector property. If the propertyvalue is of a different type than this field, then data conversion willoccur. The property value will be assigned from the first value inthe field.

srcField

Long. Token representing the connector property for which thevalue is to be assigned. See Appendix B for a list of tokens.

propertyToken



Usage NotesIt’s more efficient, as well as easier, to use the dynamic properties, forexample:

thisConnection.Metadata = “adm1.customers”

The SetProperty syntax is useful if the information you need is already inLCField objects, or if you don’t know what properties you’ll set at the timeyou write the program.


Uselsx "*lsxlc"

Sub Initialize


Dim conFld As New LCField (LCTYPE_TEXT, 1)

' set appropriate properties to connect to oracle

conFld.text = "Barker"

Call connect.SetProperty (LCTOKEN_SERVER, conFld)

' example of using the expanded property

Print "Here is the server property value: " & connect.Server

End Sub

Example OutputHere is the server property value: Barker

SetProperty<Type> methods for LCConnectionThese methods assign a Connection property value as a specific data type.Datatypes supported include: Boolean, Currency, Datetime, Float, Int,Numeric, and Text.


SyntaxCall lcConnection.SetPropertyBoolean(propertyToken, srcBoolean)

Call lcConnection.SetPropertyCurrency(propertyToken, srcCurrency)

Call lcConnection.SetPropertyDatetime(propertyToken, srcDatetime)

Call lcConnection.SetPropertyFloat(propertyToken, srcFloat)


Call lcConnection.SetPropertyInt(propertyToken, srcInt)

Call lcConnection.SetPropertyNumeric(propertyToken, srcNumeric)

Call lcConnection.SetPropertyStream(propertyToken, srcStream)

Parameters

Value to assign to the Connection property.src<Type>

Long. Token identifying the Connection property. See Appendix Bfor a list of tokens.

propertyToken



Uselsx "*lsxlc"

Sub Initialize


Dim conFld As New LCField (LCTYPE_TEXT,1)


Dim propDate As New LCDateTime

Dim propNumeric As New LCNumeric

Dim propStrm As New LCStream (0, 0, LCTYPE_TEXT)

Dim propCurr As New LCCurrency

Dim propFloat As Double

Dim propInt As Long

Dim tokenId As Long



' set the appropriate properties to connect to DB2,

' note that you can also use dynamic properties to do this




Call connect.ListProperty (LCLIST_FIRST,_



Do


If (propFlags And LCPROPERTYF_READONLY) <>LCPROPERTYF_READONLY Then

' match the property to a datatype and set it

Select Case propType

Case LCTYPE_DATETIME:

propDate.SetCurrent

Call connect.SetPropertyDatetime (tokenId, propDate)

Print propName & " is now a datetime and contains " &propDate.text

Case LCTYPE_NUMERIC:

propNumeric.text = "100.0123456789"

Call connect.SetPropertyNumeric (tokenId, propNumeric)

Print propName & " is now a numeric and contains " & _ propNumeric.text

Case LCTYPE_TEXT:

propStrm.text = "a beautiful day"

Call connect.SetPropertyStream (tokenId, propStrm)

Print propName & " is now text and contains " &propStrm.text

Case LCTYPE_CURRENCY:

propCurr.text = "140.10"

Call connect.SetPropertyCurrency (tokenId, propCurr)

Print propName & " is now currency and contains " &propCurr.text

Case LCTYPE_FLOAT:

Call connect.SetPropertyFloat (tokenId, 30000.456)

Print propName & " is now a float and contains " & Cstr(30000.456)

Case LCTYPE_INT:

If (propFlags And LCPROPERTYF_BOOLEAN) Then

Call connect.SetPropertyBoolean (tokenId, True)


Print propName & " is now an int and contains " &Cstr(True)

Else

Call connect.SetPropertyInt (tokenId, 123)

Print propName & " is now an int and contains " &Cstr(123)

End If

End Select

End If

Loop _

While connect.ListProperty (LCLIST_NEXT, _


End Sub

Example OuputDatabase is now text and contains a beautiful day

Userid is now text and contains a beautiful day

Metadata is now text and contains a beautiful day

Index is now text and contains a beautiful day

MapByName is now an int and contains True

Writeback is now an int and contains True

Condition is now text and contains a beautiful day

StampField is now text and contains a beautiful day

BaseStamp is now a datetime and contains 09/08/199805:24:33.65 PM

MaxStamp is now a datetime and contains 09/08/1998 05:24:33.65PM

Procedure is now text and contains a beautiful day

Owner is now text and contains a beautiful day

AlternateMetadata is now an int and contains True

CommitFrequency is now an int and contains 123

RollbackOnError is now an int and contains True

CreateMaxLogged is now an int and contains 123

NoJournal is now an int and contains True


CreateInDatabase is now text and contains a beautiful day

TraceSQL is now an int and contains True

Update Method for LCConnectionThis method updates selected records in the connection metadata.


Syntaxcount = lcConnection.Update(srcFieldlist, recordIndex, recordCount)

Parameters

Long, >= 1. Optional. The number of records in the fieldlist to use toperform the update. The default is 1.

recordCount

Long, >= 1. Optional. The starting record in the fieldlist from whichto read data. The default is 1.

recordIndex

LCFieldlist. The fieldlist that contains the fields to be changed.srcFieldlist


Return Value

Long. Number of records successfully updated. This may beLCCOUNT_UNKNOWN.

count

DescriptionValue

Usage NotesYou can achieve optimal performance by using the same fieldlist acrossconsecutive updates to the same target.

The property Writeback indicates whether to perform a writeback or keyedupdate:

• Writeback update: If the Writeback property is set True, this methodupdates fields in the most recently fetched record from the writebackresult set (the result set produced by LCConnection.Execute,LCConnection.Select or LCConnection.Call with the Writebackproperty set). Fields that have the NO_UPDATE field flag set are notupdated.


• Keyed update: Updates all records in the supplied metadata with fieldvalues matching all fields in the fieldlist that have the LCFIELDF_KEYfield flag set. Fields with the NO_UPDATE field flags set are notaffected. If a value is specified for the property Condition, this will beincluded in the key search criteria. This value must be in a syntax validfor the relevant connector. See the documentation for the connector forinformation about its supported syntax.









If you supply more than one key field comparison in your keyFieldList,effectively you are “and”ing the tests — LCConnect will update recordsthat meet all the tests. Likewise if you supply one or more key tests and anadditional test in the Condition property.

LCConnect does not directly support logical “or” operations of multipleconditions. You can, however, execute any query usingLCConnection.Execute, or construct an “or” type query in the Conditionfield, using the query language supported by the connector.

The rules for pattern matching in a “like” comparison vary depending onthe connector. Consult your database documentation for details.

Example 1Option Public

Option Explicit

Uselsx "*lsxlc"

Sub Initialize


Dim fldList As New LCFieldList

Dim fld As LCField


' set the appropriate properties to connect to the datasource


src.Userid = "JDoe"



src.Connect

' use a key to find certain records to update

Set fld = fldList.Append ("ACCOUNTMANAGER", LCTYPE_INT)

fld.Flags = LCFIELDF_KEY

fld.value = 200

' set the field which will be changed, and set the new value

Set fld = fldList.Append ("CONTACTNAME", LCTYPE_TEXT)

fld.text = "Me"

src.MapbyName = True

' The fieldlist contains ACCOUNTMANAGER=200 as a key field,and

' CONTACTNAME="Me", which is not a key field. Calling Updatenow

' will find all records where ACCOUNTMANAGER=200 and changetheir

' CONTACTNAME to "Me".

Print "The update affected " & Cstr (src.Update (fldList)) &" records"

End Sub

Example 1 OutputThe update affected 2 records.

Example 2 ' This example shows how to use the Writeback property

' to update records from the result set.

Option Public

Option Explicit

Uselsx "*lsxlc"


Sub Initialize

On Error Goto trap

Dim ses As New Lcsession



Dim con As New Lcconnection("oledb")

con.provider = "Microsoft.Jet.OLEDB.4.0" ' use Access 2000database

con.server = "C:\AccessData\DogData.mdb"

con.metadata = "DogDob" ' Contains dog's name and date ofbirth.

con.Connect

Dim confldlst As New Lcfieldlist, count As Long

Dim nameFld As LCField, dateOfBirth As LCField

con.writeback = True

count = con.Select(Nothing, 1, confldlst)

' Get a "handle" to each of the fields in the list returnedby Selection.

Set nameFld = confldlst.GetField(1) ' locate field byposition

Set dateOfBirth = confldlst.Lookup("DateOfBirth") ' locatefield by name.

' Either works.

While (con.Fetch (conFldLst) > 0)

Print "Name=" & nameFld.Text(0) & ", " _

"DateOfBirth=" & dateOfBirth.Text(0)

' If this dog's name is Tracy, change it to Tyler.

If nameFld.text(0) = "Tracy" Then

nameFld.text = "Tyler"

' Now write the change back to the database.

Call con.Update(confldlst)


Print "Changed name to Tyler."

End If

Wend

con.Action(LCACTION_COMMIT)

Exit Sub

trap:

Dim stat$, errcode As Long, msg$

If ses.Status <> LCSUCCESS Then

ses.Getstatus stat, errcode, msg

If (ses.Status = LCFAIL_EXTERNAL)Then

Messagebox "ODBC message: " & msg & " code #" &Cstr(errcode), 0, _

"error number " & Err & " line " & Erl

Else

Messagebox "Connector message: " & text, 0, "error number "& _ Err & " line " & Erl

End If

Else

Messagebox Error, 0, "error number " & Err & " line " & Erl

End If

Exit Sub

End Sub

Example 2 OutputName=Margot, DateOfBirth=12/02/1995

Name=Rex, DateOfBirth=06/12/1998

Name=Tracy, DateOfBirth=09/19/2001

Changed name to Tyler.

Name=Yaller, DateOfBirth=03/30/1987

Update Method for LCConnection for DB2 ConnectorThis method updates records in a writeback result set or a keyed search inthe defined METADATA object in DB2.


The LCXUpdate method operates in one of two modes, depending if theWRITEBACK property is set and there is a current result set that supportswriteback.

Non-writeback UpdatesOne or more keyed updates are performed against the metadata indicatedby the METADATA property. For each record used as key values, a keyedupdate constructed from those key values should be performed. Any valuefor the CONDITION property should be included in the search criteria.Only fields with the flag LCFIELDF_KEY should be used as key values. Theproperty MAP_NAME indicates whether to map fields in KeyFieldlist andthe target metadata by name or position.

Writeback UpdatesThere must be a current result set which supports writeback operations anda previous Fetch from that result set. The last document fetched by the mostrecent Fetch call is updated.

Only fields without the flag LCFIELDF_NO_UPDATE should be updated.The current fieldlist value for each field to update should replace any valuefor the field in the target metadata.

Handling of both mapping and field flags is implicitly done by callingLCFieldlistMerge with the target metadata field names as NameFieldlist,SrcFieldlist as DataFieldlist, and MergeFlags LCMERGEF_NAME_LOSS,LCMERGEF_UPDATE, (for keyed updates only) LCMERGEF_KEY, andoptionally (depending on the MAP_NAME property)LCMERGEF_MAP_NAME.


Chapter 3LCCurrency Class

This chapter provides information about the Lotus Connectors LCCurrencyclass methods and properties.

OverviewThe LCCurrency class represents a currency value and has the same formatand restrictions as the LotusScript currency data type. The value is an8-byte integer with a fixed scale of 4 decimal places, providing 19 digits ofprecision. Currency is commonly used when higher precision is required,such as for monetary amounts. A currency is much more precise than aninteger, more precise than a float, and more efficient (but less precise) thana numeric. Note that during any currency overflow, the maximum orminimum valid currency value is assigned in addition to the errorgenerated.



Uselsx "*lsxlc"

Sub Initialize





91

Type CURRENCY Format and ValuesThe following table shows CURRENCY format and values.

Maximum Value (LCMAX_CURRENCY_VALUE) =922,337,203,685,477.5807

Minimum Value (LCMIN_CURRENCY_VALUE) =

-922,337,203,685,477.5807

Scale (LCMAX_CURRENCY_SCALE) = 4

Precision (LCMAX_CURRENCY_PREC) = 19Other

8-byte integer with a fixed scale of 4Description

LCTYPE_CURRENCYType constant

ValueDescription

LCCurrency Class Methods SummaryThe following are the LCCurrency class methods:

Subtracts one currency value from another, and returns theresult to the object making the call.

LCCurrency.Subtract

Makes a copy of a currency.LCCurrency.Copy

Compares two currency values returning a value indicatingthe relationship between them.

LCCurrency.Compare

Adds two currency values and deposits the result in theobject making the call.

LCCurrency.Add

DescriptionMethod

LCCurrency PropertiesLCCurrency has two properties: Text and Value.

• Text — String, read/write: The string representation of the currencyamount. This is expressed to four places following the decimal, anddoes not include a currency symbol.

• Value — LotusScript currency data type, read/write.

New Method for LCCurrencyThis is the constructor for LCCurrency. It initializes a currency object.

Defined InLCCurrency


SyntaxDim variableName As New LCCurrency


Uselsx "*lsxlc"

Sub Initialize

Dim num1 As New LCCurrency

num1.Value = 1700.23

Print num1.Text

End Sub

Example Output1700.2300

Add Method for LCCurrencyThis method adds two LCCurrency values, producing the sum. The sum isreturned to the object that is making the call.


SyntaxCall currencyTotal.Add(currency1, currency2)

Parameters

LCCurrency. The second of the two LCCurrencies to add.currency2

LCCurrency. The first of the two LCCurrencies to add.currency1


Usage NotesCurrencyTotal may be the same object as one of the arguments, for example:

Call runningTotal.Add(runningTotal, newAmount)

CurrencyTotal must have been initialized prior to the call, that is, it cannotbe Nothing.


Uselsx "*lsxlc"

Chapter 3: LCCurrency Class 93

Sub Initialize



Dim sum As New LCCurrency

num1.Value = 12345.6789

num2.Value = 12345.6789

Call sum.Add (Num1, Num2)

Print "The sum of the two currencies is " & sum.Text

End Sub

Example OutputThe sum of the two currencies is 24691.3578

Compare Method for LCCurrencyThis method compares two currency values and returns the relationship.


SyntaxResult = thisCurrency.Compare(baseCurrency)

Parameters

LCCurrency. The base currency value to which to comparethisCurrency.

baseCurrency


Return Value

Result = 0: thisCurrency is equal to baseCurrency

Result < 0 (negative): thisCurrency is less than baseCurrency.

Result > 0 (positive): thisCurrency is greater than baseCurrency.

Long. Result of the comparison:Result

DescriptionValue


Uselsx "*lsxlc"


Sub Initialize

Dim num1 As New LCCurrency //For LEI


num1.Value = 123.456789

num2.Value = 123

If (num1.Compare (num2) = 0) Then

Print "The first number is the same as the second."

Elseif (num1.Compare (num2) > 0) Then

Print "The first number is greater than the second."

Else

Print "The first number is less than the second."

End If

End Sub

Example OutputThe first number is greater than the second.

Copy Method for LCCurrencyThis method makes a copy of an LCCurrency object.


SyntaxSet newCurrency = srcCurrency.Copy

Parameters

LCCurrency. The source currency value to be copied.srcCurrency


Return Value

LCCurrency. The copy of the srcCurrency object.newCurrency

DescriptionValue


Uselsx "*lsxlc"


Sub Initialize


Dim num2 As LCCurrency

num1.Value = 12345.6789

Set num2 = num1.Copy

Print "The copy has a value of " & num2.Text

End Sub

Example OutputThe copy has a value of 12345.6789.

Subtract Method for LCCurrencyThis method subtracts one LCCurrency value from another, producing theresult. The result is stored in the object that is making the call.


SyntaxCall currencyResult.Subtract(currency1, currency2)

Parameters

LCCurrency. The amount to be subtracted from currency1.currency2

LCCurrency. This is the initial LCCurrency from which you wantto subtract the second currency.

currency1


Usage NotesThe currencyResult may be the same object as one of the arguments, forexample:

Call remainingAmt.Subtract(remainingAmt, deduction)

CurrencyResult must have been initialized prior to the call, that is, it cannotbe Nothing.


Uselsx "*lsxlc"

Sub Initialize




Dim diff As New LCCurrency

num1.Value = 98765.4321

num2.Value = 12345.6789

Call diff.Subtract (Num1, Num2)

Print "The difference of the two currencies is " & diff.Text

End Sub

Example OutputThe difference of the two currencies is 86419.7532.

Example: LCCurrency with LCFieldlist and LCFieldThis example illustrates the use of LCCurrency in conjunction with theLCFieldlist and LCField options.

Option Public

Option Declare

Uselsx "*lsxlc"

Sub Initialize

' Find all account records that meet certain criteria and

' add $170.90 (or £, ¥, or whatever the unit of currencyis)

' to the balance.

Dim con As New LCConnection("db2")

con.Database = "..."

' and so on...

con.Metadata = "ACCOUNTS"

con.Connect

con.MapByName = True

Dim addlAmount As New LCCurrency( )

addlAmount.Value = 170.90


' or addlAmount.Text = "170.90" (useful whenworking with values

' that might be too large for LotusScript tohandle).

' If you use the Text property, know whether "." or"," is

' the decimal point locally.

Dim newComment As New LCStream( )

newComment.Text = "Just because we like him..."

Dim one As New LCNumeric( )

one.Value = 1

' Construct a key list that contains the query to findthe records

' that need updating.

Dim keyFields As New LCFieldList(1, LCFIELDF_KEY) ' allfields in

' this list are part of the query by default.

Dim firstname As LCField, lastname As LCField

Set firstname = keyFields.Append("FIRSTNAME",LCTYPE_TEXT)

firstname.Value = "Andres"

Set lastname = keyFields.Append("LASTNAME", LCTYPE_TEXT)

lastname.Value = "Guirardes"

Dim count As Long

Dim results As New LCFieldList

con.Writeback = True ' enable record locking andwriteback,

' to efficiently update a record once we find it.

count = con.Select(keyFields, 1, results)

If count <> 0 Then

' Some records were found (or else the connectordoesn't

' supply this information on a Select).


Dim fldBalance As LCField

Dim fldTransCt As LCField

Dim fldRemark As LCField

Dim fldTransTime As LCField

Dim cur As LCCurrency

Dim transCt As LCNumeric

Dim remark As LCStream

Dim transTime As New LCDatetime

' In case you're processing multiple records, it'smore efficient

' to look up the fields by name once and storepointers to the

' fields in separate variables.

Set fldBalance = results.Lookup("BALANCE")

Set fldTransCt = results.Lookup("TRANSCOUNT")

Set fldTransTime =results.Lookup("LASTTRANSACTIONTIME")

Set fldRemark =results.Lookup("TRANSACTIONCOMMENT")

' A text string in US-ASCII format, stored inbinary (CLOB)

' in the database.

While con.Fetch(results)

' fetch the field value for the currentbalance.

Set cur = fldBalance.GetCurrency(1)

Print "old balance: " & cur.Text

' Add the amount by which we're increasing thebalance.

' Note: in some countries with highly inflatedcurrencies, we

' are very glad to have the full precision ofthe


' LCCurrency datatype to do our math with, ascompared to

' a Double in LotusScript. Also, sinceLCCurrency

' is a decimal type, fractional currency unitscan be

' represented exactly, whereas 0.10, forinstance, can't

' be represented exactly by a floating pointdatatype.

Call cur.Add(addlAmount, cur)

' write that back into the field.

Print "new balance: " & cur.Text

Call fldBalance.SetCurrency(1, cur)

' Get the current transaction count. This maypotentially

' exceed the precision of a Long,' but using the LC we can handle it without a

problem.

Set transCt = fldTransCt.GetNumeric(1)

' increment the count.

Print "old transaction count: " &transCt.Value

Call transCt.Add(one, transCt)

Print "new transaction count: " &transCt.Value

' write that back into the field.

Call fldTransCt.SetNumeric(1, transCt)

' Write a value into the comment field,translating it from

' Unicode to the US-ASCII which is used in thedatabase.

' DB2 doesn't know this is ASCII data; it'sjust a CLOB. The

' knowledge about what character set is usedis resident in

' this application (and others that use thesame DB2 table).


' Since LotusScript doesn't support fullpointer operations

'(for example mapping a structure onto astring of bytes),

' you don't have easy access via LotusScriptto the binary

' data in a Stream object, except if you treatit as a

' string of characters. But conversions fromone character set

' to another are quite simple. There are alsomethods to

' extract and replace substrings, merge andtruncate string data.

Set remark = fldRemark.GetStream(1,LCSTREAMFMT_ASCII)

Print "old remark: " & remark.Text

Call remark.Convert(newComment,LCCONVERTF_PRESERVE, LCSTREAMFMT_ASCII)

Print "new remark: " & remark.Text

Call fldRemark.SetStream(1, remark)

' Write the current date and time into thelast

' transaction field.

Call transTime.SetCurrent( )

Print "transaction time: " & transTime.Text

Call fldTransTime.SetDatetime( 1, transTime )

Call con.Update(results)

Wend

End If

End Sub

Example Outputold balance: 31229.7000

new balance: 31470.6000

old transaction count: 30


new transaction count: 31

old remark: auto-pay AT&T

new remark: Just because we like him...

transaction time: 05/29/2002 02:17:15.14 PM


Chapter 4LCDatetime Class

This chapter provides information about the Lotus Connectors LCDatetimeclass methods and properties.

OverviewThe LCDatetime class represents a specific date and time, including timezone and daylight savings time information. A datetime value may haveeither its date or time component unavailable, indicated by special constantvalues for date (LCDTNULL_DATE) or time (LCDTNULL_TIME) compo-nents. Flags control the behavior for the existence/absence of the date ortime portion. During any datetime overflow, the maximum or minimumvalid datetime value is assigned in addition to the error return.

The time portion of the datetime is precise to hundredths. Some datasources do not support this precision, or support greater precision. Forthese systems it may be necessary to set the field flags for all datetime datatype fields to LCFIELDF_TRUNC_PREC, to avoid a precision loss error.

Exercise care in converting LCDatetime values to and from LotusScriptdatetime variants. LotusScript does not represent time zone and DST, nordoes it distinguish between a “null time” and midnight. So, you lose information when you use the Value property to copy a date/time valueinto a LotusScript datetime variant. If you need to do math with thesevalues, it is generally better to use the GetDiff, Adjust and Comparemethods as opposed to using the LotusScript operators +, -, < or > on the Value property.


103


Uselsx "*lsxlc"

Sub Initialize





Type DATETIME Format and ValuesThe following table lists DATETIME formats and values.

Maximum Year Value (LCMAX_DATETIME_YEAR) = 32767

Minimum Year Value (LCMIN_DATETIME_YEAR) = 1

Precision = 0.01 secondOther

Date and time value with time zone and Daylight Savings Time(DST)

Description

LCTYPE_DATETIMEType constant

DescriptionValue

LCDatetime Class Methods SummaryThe following table summaries LCDatetime class methods.

Set the LCDatetime to the current date and time.LCDatetime.SetCurrent

Set the LCDatetime to one of three special “constant”values.

LCDatetime.SetConstant

Find the difference between two LCDatetimes in units of aspecified time interval.

LCDatetime.GetDiff

Create a new LCDatetime by copying an existing one.LCDatetime.Copy

Compare two LCDatetime objects to see which representsthe later time.

LCDatetime.Compare

Set the LCDatetime to the default value of a newLCDatetime.

LCDatetime.Clear

Add or subtract a given number of years, months, or daysfrom a date and time.

LCDatetime.Adjust

DescriptionMethod


LCDatetime Properties SummaryThe following table summarizes LCDatetime properties.

LotusScript Variant containing a datetime. The value isreturned in the time zone specified by the Zone property(not the user’s local time).

Note The LotusScript variant does not contain informationabout time zone and Daylight Savings Time. To copy avalue from one LCDatetime to another without losinginformation, use the LCDatetime.Copy method.

LCDatetime.Value

String representation. The date and time will be expressedusing the local datetime settings of the computer executingthe code. For example, U.S. computers will typically list themonth number first, while Europe will list the day of themonth first. Zone and DST information are not included inthis output. If the time is in a different zone, the value isdisplayed in the time of that zone, not the correspondinglocal time.

LCDatetime.Text

Long. Integer representing the Julian date by indicating thenumber of days since January 1, 4713 BC. If the objectcontains a time value only, returns -1.

LCDatetime.Julian

Long. Tick count representing hundredths of a second sincemidnight. Returns -1 if the object contains a date only.

LCDatetime.Ticks

Boolean. Indicates whether Daylight Savings Time is ineffect.

LCDatetime.DST

Long. Integer indicating the time zone (-12 to 12).

Note While Zone is a writeable property, assigning theZone property does not change the Hour to thecorresponding time in the new zone. If you want this done,you must do it yourself.

LCDatetime.Zone

Long, read-only. Integer indicating the day of the week (1-7,Sunday = 1), or -1 if the object contains a time only.

LCDatetime.Weekday

Long. Integer indicating the year (1-32767), or -1 if the objectcontains a time only.

LCDatetime.Year

Long. Month (1-12), or -1 if the object contains a time only.LCDatetime.Month

Long. Hour (0-23), or -1 if the object contains a date only.LCDatetime.Hour

Long. Day of month (1-31), or -1 if the object contains a timeonly.

LCDatetime.Day

Long. Hundredths of second (0-99), or -1 if the objectcontains a date only.

LCDatetime.Hundredth

Long. Second (0-59), or -1 if the object contains a date only.LCDatetime.Second

Long. Minute (0-59), or -1 if the object contains a date only.LCDatetime.Minute

DescriptionProperty

Chapter 4: LCDatetime Class 105

New Method for LCDatetimeThis is the constructor for LCDatetime. It initializes a new LCDatetimeobject.

Defined InLCDatetime

SyntaxDim variableName As New LCDatetime(Year, Month, Day, Hour, Minute,Second, Hundredth, Zone, DST)

ParametersAll parameters are optional. If you omit all of them, the object will have aspecial “null” value, whose Text property returns “”.

Variant. Boolean. Daylight savings time is in effect when true.Default is False.

DST

Long. A value representing the time zone in the range -11 to 11.Default is GMT.

Zone

Long. A value in the range 0-99. Default is 0.Hundredth

Long. A value in the range 0-59. Default is 0.Second

Long. A value in the range 0-59. Default is 0.Minute

Long. A value in the range 0-23. Default is 0.Hour

Long. A value in the range 1-31. Default is 0.Day

Long. A value in the range 1-12. Default is 0.Month

Long. Value in the range 1-32767. Default is 0.Year


ExampleUselsx "*lsxlc"

Sub Initialize

Dim clock As New LCDatetime ' default null time value

Dim cutoff As New LCDatetime(2002, 4, 15, 23, 59, 59, 99)

Print "U.S. Income Tax Mailing last minute deadline is " &cutoff.Text

Print "clock = " & clock.Text

Call clock.SetCurrent

Print "now clock = " & clock.Text


End Sub

Example OutputU.S. Income Tax Mailing last minute deadline is 04/15/200211:59:59.99 PM

clock =

now clock = 03/13/2002 05:11:24.56 PM

Adjust Method for LCDatetimeThis method alters a datetime by specified datetime units.


SyntaxCall changeDatetime.Adjust(Units, Amount)

Parameters

Long. The amount to adjust the datetime unit. Positive means laterin time; negative means earlier.

Amount

LCDTUNIT_HUNDREDTH — Hundredth of second units.

LCDTUNIT_SECOND — Second units.

LCDTUNIT_MINUTE — Minute units.

LCDTUNIT_HOUR — Hour units.

LCDTUNIT_DAY — Day units.

LCDTUNIT_MONTH — Month units.

LCDTUNIT_YEAR — Year units.

Long. The unit to adjust. Units are in the order listed in theconstructor: Year, Month, Day, Hour, Minute, Second, Hundredth,Zone, DST. Use the following constants:

Units


Usage NotesThe LCDatetime.Adjust method does not support time zone adjustment.You have to do this yourself by setting the Zone property and adjusting thetime by an appropriate number of hours.

LCDatetime is limited to the capabilities of time representation in relationaldatabase systems. This representation is not as rich as the NotesDateTimeobject and Notes datetime fields. If you need to do much math with datesand times, it is probably better to create NotesDateTime objects, which


allow easier time zone conversions and control of whether Daylight SavingsTime should be applied when adjusting.


Uselsx "*lsxlc"

Sub Initialize

Dim clock As New LCDateTime

clock.SetCurrent

Print "The time is " & clock.Text

Call clock.Adjust (LCDTUNIT_HOUR, -100)

Print "100 hours ago, the time was " & clock.Text

End Sub

Example OutputThe time is 09/08/1998 05:22:07.18 PM

100 hours ago, the time was 09/05/1998 02:37:52.82 AM

Clear Method for LCDatetimeThis method clears a previously set Datetime value to. This gives it thesame value as a new LCDatetime created without any constructorarguments.


SyntaxCall dateTimeObject.Clear


Uselsx "*lsxlc"

Sub Initialize

Dim Clock As New LCDateTime (1999, 12, 31, 23, 59, 59, 99)

Clock.Clear

If (Clock.Text = "") Then

Print "The time has been cleared."


Else

Print "The time is " & Clock.Text

End If

End Sub

Example OutputThe time has been cleared.

Compare Method for LCDatetimeThis method compares two Datetime values and returns the relationship.


SyntaxResult = thisDatetime.Compare(baseDatetime)

Parameters

The Datetime to which to compare thisDatetime.baseDatetime


Return Value

Certain datetime “constants” will always return greater, less orequal to any valid date. See the SetConstant method for details.

The comparison takes into account time zones and DaylightSavings time; for instance, 1:30 PM CST is considered earlier than1:00 PM EST on the same date.

Note For control over whether time zones and Daylight SavingsTime are taken into account, or to test for equality only to thenearest second (as opposed to hundredth of a second), useLCField.Compare instead.

Result = 0: thisDatetime is equal to baseDatetime.

Result < 0 (negative): thisDatetime is less than baseDatetime.

Result > 0 (positive): thisDatetime is greater than baseDatetime.


DescriptionValue


Uselsx "*lsxlc"


Sub Initialize


Dim Match As New LCDatetime

Match.SetCurrent

If (Clock.Compare (Match) = 0) Then

Print "The current time matches " & Clock.Text

Elseif (Clock.Compare (Match) > 0) Then

Print "The current time is before " & Clock.Text

Else

Print "The current time is after " & Clock.Text

End If

End Sub

Example OutputThe current time is before 12/31/1999 11:59:59.99 PM

Copy Method for LCDatetimeThis method makes a copy of an LCDatetime object.


SyntaxSet newDatetime = srcDatetime.Copy

Parameters

LCDatetime. The datetime object that you want to copy. srcDatetime


Return Value

LCDatetime. The copy of the srcDatetime object. newDatetime

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize





Dim StopTime As New LCDateTime

Dim StartTime As LCDatetime

StopTime.SetCurrent

Set StartTime = StopTime.Copy

session.Sleep (100) ' 100 milliseconds

StopTime.SetCurrent

Print "The difference between start and stop is:"

Print StopTime.GetDiff (StartTime, LCDTUNIT_HUNDREDTH) & _

" hundredths of a second."

End Sub

Example OutputThe difference between start and stop is:10 hundredths of a second

GetDiff Method for LCDatetimeThis method gets the difference between the values of two LCDatetimeobjects.


Syntaxdifference = lcDatetime.GetDiff(baseDatetime, Units)

Parameters

LCDTUNIT_YEAR — Year units.

Long. The units to compare. Units are in the order listed in theconstructor: Year, Month, Day, Hour, Minute, Second, Hundredth,Zone, DST. Use the following constants:

Units

LCDatetime. The datetime object to which you want to comparethe lcDatetime object.

baseDatetime



continued



LCDTUNIT_ZONE — Time zone units.

LCDTUNIT_HUNDREDTH — Hundredth of second units.

LCDTUNIT_SECOND — Second units.

LCDTUNIT_MINUTE — Minute units.

LCDTUNIT_HOUR — Hour units.

LCDTUNIT_WEEKDAY — Weekday units.

LCDTUNIT_DAY — Day units.

LCDTUNIT_MONTH — Month units.


Return Value

The difference between the two LCDatetime objects, in the unitsspecified.

difference

DescriptionValue

If the objects are incompatible for comparison (that is, if one contains only adate and one contains only a time), or if they are date-only values and youask for a difference in units less than days, the value will be zero.


Uselsx "*lsxlc"

Sub Initialize

Dim Boston As New LCDateTime _

(1998, 1, 25, 08, 50, 00, 00, -5, True)

Dim Singapore As New LCDateTime _

(1998, 1, 27, 1, 10, 00, 00, 8, False)

Print "A flight taking off from Boston at 8:50am"

Print "and landing in Singapore at 1:10am"

Print "will take " & Singapore.GetDiff (Boston,LCDTUNIT_HOUR) & " hours."

End Sub

Example OutputA flight taking off from Boston at 8:50am and landing inSingapore at 1:10am will take 27 hours.


SetConstant Method for LCDatetimeThis method produces a special constant Datetime object.


SyntaxCall lcDatetime.SetConstant(datetimeConstant)

Parameters

LCDTCONST_WILDCARD: A datetime that matches any otherdatetime. The date value is LCDTNULL_DATE and the timevalue is LCDTNULL_TIME.

LCDTCONST_MAXIMUM: A datetime that is greater than anyother datetime (except another maximum).

LCDTCONST_MINIMUM: A datetime which is less than anyother datetime (except another minimum).

One of the following Datetime Constants:datetimeConstant



Uselsx "*lsxlc"

Sub Initialize


Dim Match As New LCDatetime

Call Match.SetConstant (LCDTCONST_WILDCARD)

If (Clock.Compare (Match) = 0) Then

Print "The current time matches the wild card constant."

Else

Print "The current time does not match the wild cardconstant."

End If

End Sub

Example OutputThe current time matches the wild card constant.


SetCurrent Method for LCDatetimeThis method sets the Datetime value to the current system datetime, includ-ing time zone and Daylight Savings Time setting.


SyntaxCall lcDatetimeObject.SetCurrent


Uselsx "*lsxlc"

Sub Initialize

Dim stopWatch As New LCDateTime

stopWatch.setcurrent

Print "The time is " & stopWatch.text

End Sub

Example OutputThe time is 09/08/1999 05:22:02.85 PM


Chapter 5LCField Class

This chapter provides information about the LCField class methods andproperties.

OverviewThe LCField class represents a data object containing one or more datavalues of a designated data type. Most of the methods in the LCField classhave an “index” argument, specifying which of the potentially multiplevalues in the field to operate on. Index values start at 1.

In repetitive operations such as data fetch — insert loops, it is more efficientto get a reference field from a fieldlist prior to the loop, and act on the datathrough the reference than to locate the data field in each iteration of theloop. See the “Performance” section in Chapter 1 for an example.

In addition, an LCField can contain an LCFieldlist as its value. Since anLCFieldlist contains LCFields, this lets you nest a fieldlist inside anotherfieldlist. This lets you use LCFields and LCFieldlists together as a means ofmaintaining structured data in memory. However, there is no way toemploy these complex structures to read or write data in a single operation.



Uselsx "*lsxlc"

Sub Initialize



117



LCField Class Methods and Properties SummaryThe methods for the LCField class are summarized below.

AllocationThe following methods create and free Field instances.

(Destructor) Frees a Field object instance allocated with theconstructor or LCField.Copy. This method does not free fieldscreated as part of a fieldlist.

Delete LCField

Creates a new Field object instance as a copy of another field.The field data is also copied.

LCField.Copy

(Constructor) Allocates a new Field object instance.New LCField

DescriptionMethod

Field PropertiesThe following methods support retrieval of field properties and assignmentof mutable field properties.

Sets a virtual code for a field.LCField.SetVirtualCode

Lists the virtual code(s) for a field.LCField.ListVirtualCode

Checks if a field has this virtual code set.LCField.GetVirtualCode

DescriptionMethod

Field FormatThe following methods support retrieval of field format information.Setting the format for a field clears all current data values for that field.

Assigns the current format settings for a stream field.LCField.SetFormatStream

Retrieves the current format settings for a stream field.LCField.GetFormatStream

Assigns the current format settings for a datetime field.LCField.SetFormatDatetime

Retrieves the current format settings for a datetimefield.

LCField.GetFormatDatetime

Assigns the current format settings for a number field.LCField.SetFormatNumber

Retrieves the current format settings for a numberfield.

LCField.GetFormatNumber

DescriptionMethod


Field DataThe following methods support access to and modification of field data andNULL indicators.

Assigns a specific field data value from a particular datatype, converting the data if necessary.

LCField.Set<Type>

Retrieves a specific field data value as a particular datatype, converting the data if necessary.

LCField.Get<Type>

Assigns the NULL indicator for a specific field datavalue.

LCField.SetNull

Queries whether a specific field data value is NULL.LCField.IsNull

DescriptionMethod

MiscellaneousThe following methods provide compare and conversion functionality.

Convert data values between two fields.LCField.Convert

Compare data values between two fields.LCField.Compare

DescriptionMethod

LCField PropertiesThe following are the properties for the LCField class:

continued LCFIELDF_NO_REMOVE — Do not REMOVE this field.

LCFIELDF_NO_UPDATE — Do not UPDATE this field.

LCFIELDF_NO_INSERT — Do not INSERT this field.

LCFIELDF_NO_FETCH — Do not FETCH this field.

LCFIELDF_TRUNC_DATA — Allow data truncation.

LCFIELDF_TRUNC_PREC — Allow precision truncation.

LCFIELDF_NO_NULL — Field cannot be NULL.

Long. Zero or more of the following field flags ORed together.Flags

Long. One of the Lotus Connector data type. Assigned at creationand Read-Only.

Datatype

Long. One or greater. Data space for this many data values andNULL indicators will be allocated. The value count is automaticallyassigned for fields in a fieldlist based on the fieldlist record count (seeFieldlist description). Assigned at creation and Read-Only.

Count

DescriptionProperty

Chapter 5: LCField Class 119

StringLCTYPE_BINARY

StringLCTYPE_TEXT

DoubleLCTYPE_NUMERIC

DoubleLCTYPE_FLOAT

LongLCTYPE_INT

Variant (Date/Time)LCTYPE_DATETIME

CurrencyLCTYPE_CURRENCY

Value Return TypeField Type

Array of LotusScript data types. The value or values containeddepend on the data type of the field, as listed below. As for the Textmethod, the array begins with index 0. The value returned is an arrayeven if the field is not multi-valued. Like Text, the Value property canbe assigned to set the value of all field elements. To assign one at atime, see the Set<type> methods in this chapter.

Value

Array of string representations.

Note Though an LCField’s values are indexed from 1 to Count forpurposes of the method calls, the Text property returns an arrayindexed from 0 to Count-1, consistent with the LotusScript default forarray representations. The value returned is an array even if the fieldis not multi-valued. This is a read/write property, so you can assignthe field by assigning the property, much the same as you can aNotes document field. However, you must assign the entire property,that is, fld.Text = var, not field.Text(0) = var.

Text

Boolean. True or False.IsNull

Key condition is like (native pattern match).LCFIELDF_KEY_LIKE

LCFIELDF_KEY_NE — Key condition is not equal to.

LCFIELDF_KEY_LT — Key condition is less than.

LCFIELDF_KEY_GT — Key condition is greater than.

LCFIELDF_KEY — Field is a KEY for keyed operations.

LCFIELDF_NO_DROP — Do not DROP this field.

LCFIELDF_NO_CREATE — Do not CREATE this field.

DescriptionProperty

Field FormatThe format of a field is specific to its general class of type: number (int,float, currency, numeric), datetime, or stream (text and binary). For allformat values, zero indicates that the specified information is not used forthis field. The information for each data type is given below.


Note Number and Datetime formats do not affect the actual data, but areused for data creation only. Stream format does affect the actual data.

Number (INT, FLOAT, CURRENCY, NUMERIC)Flags: zero or more of the following constants. Multiple constants can beORed together:

Source type is a bit.LCNUMBERF_BIT

Source numeric/decimal data is packed.LCNUMBERF_PACKED

Source type is DECIMAL.LCNUMBERF_DECIMAL

Source type is NUMERIC (unnecessary withLCTYPE_NUMERIC).

LCNUMBERF_NUMERIC

Source type is unsigned.LCNUMBERF_UNSIGNED

DescriptionConstant

Size: size, in bytes, of this number value. Zero indicates to default to the sizeof the type for this field.

Precision: digits of precision for this value. Zero indicates not used.

Scale: numeric scale. A true scale of zero uses the constantLCSCALE_ZERO. Zero indicates not used.

Datetime (DATETIME)Size: size, in bytes, of this datetime value. Zero indicates to default to thesize of the type for this field.

Flags: zero or more of the following constants. Multiple constants can beORed together:

Source type is date only.LCDATETIMEF_NO_TIME

Source type is time only.LCDATETIMEF_NO_DATE

DescriptionConstant

Stream (TEXT, BINARY)Flags: zero or more of the stream flags LCSTREAMF_xxx. Multiple flags canbe ORed together. See the LCStream class description.

MaxLength: maximum length, in bytes, of this stream value. Zero indicatesno maximum length. See the LCStream class description.

StreamFormat: default stream format for this stream value. Zero indicates nodefault stream format. Use one of the LCSTREAMFMT_xxx constants.


Field Virtual Codes — Advanced UsageVirtual codes allow specific fields to be interpreted differently for Connec-tors which support virtual fields. For example, a Connector could support avirtual field named “RecordId,“ which holds a special internal recordindicator for that Connector. This Connector would interpret this fielddifferently than normal data, while other Connectors would consider thisfield a standard data field. While the virtual code indicates specialhandling, the field name determines the type of handling on a Connector-specific basis.

To achieve this functionality, the virtual code for a field is set to matcheither a Connector code or a Connection code. A Connector code is a codewhich is the same for all connections to a particular Connector in a Session.The Connector code can be obtained by retrieving the propertyLCTOKEN_CONNECTOR_CODE with LCConnection.GetProperty or asthe code returned by LCSession.ListConnector or LCSession.LookupCon-nector. Using a Connector code as a virtual code causes all connections tothat Connector to interpret the field as a virtual field. A connection code is acode which is different for all connections. The Connect code can beobtained by retrieving the property LCTOKEN_CONNECTION_CODEwith LCConnection.GetProperty. Using a Connection code as a virtual codecauses only that specific Connection to interpret the field as a virtual field.The Connector code can also be determined by taking the Connection codeand zeroing the low two bytes (OR with LCMASK_CONNECTOR_CODE).Note that these codes are dynamically assigned and must be obtained foreach execution of a script.

Processing Attachments Stored in RTF FieldsNotes 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. It stores theattachment data separately from the Rich Text field data. Currently you canonly transfer attachments from Notes to Notes; Rich Text fields with attach-ments do not store correctly in the target RDBMS such as DBA and Oracle.

To work around this constraint, you can use the Notes Connector optionExtract File Attachments to save attachments to files on disk. You can thenuse LotusScript to read the files, store their contents in LCFields, and savethe LCFields to binary fields in a RDBMS. This level of scripting requiresLotusScript expertise.


New Method for LCFieldThis is the constructor method for LCField. It initializes an LCField object.

Defined InLCField

SyntaxDim variablename As New LCField(type, count)

Parameters

Long. Optional, >=1. Number of data values to be allocated for thisfield. The default is 1. Using a higher number essentially creates anarray of values, indexed from 1 to count, letting you store multiplevalues of the same type in the field. This is useful as an element of anLCFieldlist that is also allocated to the same number of elements (seethe New method of LCFieldlist), allowing you to fetch or updatemultiple records in a single operation.

count

LCTYPE_BINARY

LCTYPE_TEXT

LCTYPE_NUMERIC

LCTYPE_FLOAT

LCTYPE_INT

LCTYPE_DATETIME

LCTYPE_CURRENCY

Long. Data type of the field object, one of the following constants:type



Uselsx "*lsxlc"

Sub Initialize




Dim person As New LCField(LCTYPE_TEXT, 10) ' sufficient spaceto

'store 10 "rows" of name information.


Dim dateOfBirth As New LCField(LCTYPE_DATETIME, 10) ' tendates

Dim outputFields As New LCFieldlist(10, LCFIELDF_KEY) ' afield list

'for 10-element fields.

Call outputFields.IncludeField(1, person, "PERSON")

Call outputFields.IncludeField(2, dateOfBirth, "BIRTH_DATE")

' outputFields is ready to be used to "insert" or "update"

' up to 10 records of name/birthdate simultaneously

' (once you put data in the fields). This could instead

' have been done using the LCFieldlist.Append method,making

' it unnecessary to use the New method of LCField.

ClearVirtualCode Method for LCFieldThis method clears the specified virtual code for the field. Virtual codes flagfields as special system properties recognized by different systems. Refer tothe connector documentation for specific codes supported by eachconnection.

Defined InLCField

SyntaxCall field.ClearVirtualCode(code)

Parameters

The code to clear. Zero (0) clears all codes.code



Uselsx "*lsxlc"

Sub Initialize





Dim field As New LCField (LCTYPE_INT)

Dim Code As Long

Dim text As String

Call session.ListConnector (LCLIST_FIRST, , Code)

Call field.SetVirtualCode (Code)

While session.ListConnector (LCLIST_NEXT, , Code)


Wend

' use the value to clear an individual connector's virtualcode

' use 'zero' to clear all connectors' virtual codes

Call field.ClearVirtualcode (0)

Print "All of the virtual codes have been cleared."

End Sub

Example OutputAll of the virtual codes have been cleared.

Compare Method for LCFieldThis method compares data values between two fields and returns therelationship.

Defined InLCField

Syntaxresult = thisField.Compare(thisIndex, baseField, baseIndex, valueCount,compareFlags)

ParametersAll parameters are required.

continued

LCField. Base field for comparison.baseField

Long, >= 1. Index identifying the first value to be compared fromthisField.

thisIndex



In addition, the following composite flag is supplied:

LCCOMPAREF_LOW_PREC — Composite of all low-precisionLCCOMPAREF flags.

LCCOMPAREF_FLOAT_PREC — Compare floating point values toonly ten digits of precision.

LCCOMPAREF _SECOND — Do not consider fractions of secondsin datetime comparisons.

LCCOMPAREF_NO_ZONE — Do not consider time zone ordaylight savings time information in datetime comparisons.

Long. Zero or more of the following values, ORed together:compareFlags

Long. Number of field values to be compared. Starting at theindicated index in each field, ValueCount consecutive values fromeach field will be compared until all are compared or until there is amismatch.

valueCount

Long, >= 1. Index identifying the first base value in baseField.baseIndex


Return Value

Result = 0: Each compared value in thisField is equal to thecorresponding value in baseField.

Result < 0 (negative): The first mismatch that the functionencountered in thisField is less than the corresponding value inbaseField.

Result > 0 (positive): The first mismatch that the function encounteredin thisField is greater than the corresponding value in baseField. Fordatetime fields, greater means later.


DescriptionValue


Uselsx "*lsxlc"

Sub Initialize

Dim field1 As New LCField (LCTYPE_INT, 3)

Dim field2 As New LCField (LCTYPE_INT, 2)

Call field1.SetInt (1, 100)






If (field1.Compare(2, field2, 1, 2, 0) <> 0) Then

Print "the 2nd and 3rd values of field1 " & _

"do not match the 1st and 2nd values of field2."

Else

Print "the 2nd and 3rd values of field1 " & _

"match the 1st and 2nd values of field2."

End If

End Sub

Example OutputThe 2nd and 3rd values of field1 match the 1st and 2nd valuesof field2.

Convert Method for LCFieldThis method converts data values to the data type of a destination field.

Defined InLCField

SyntaxCall destField.Convert(destIndex, srcField, srcIndex, valueCount)

ParametersAll parameters are required.

Long. Number of field values to be converted. If the end of eitherfield is encountered before converting this number of data values,then the function stops at that point.

valueCount

Long, >= 1. Index in srcField of the first data value to be convertedand copied into destField.

srcIndex

LCField. Source field for the data values. Values will be converted tothe data type of destField.

srcField

Long, >= 1. Index of the first value in destField to be assigned.destIndex




Uselsx "*lsxlc"

Sub Initialize

Dim f_field As New LCField (LCTYPE_FLOAT)

Dim c_field As New LCField (LCTYPE_CURRENCY)

f_field.value = 12345.123456789

Call c_field.Convert (1, f_field, 1, 1)

Print "The float field is " & f_field.text(0) & "and it was"

Print "converted to a currency field as " & c_field.text(0)

End Sub

Example OutputThe float field is 12345.123456789 and it was converted to acurrency field as 12345.1235.

Copy Method for LCFieldThis method creates a field with the settings and values of a source field.The new field contains the same number of data values of the same datatype as the source field. The new values are copies of, rather than referencesto, the original data.

Defined InLCField

SyntaxSet newField = origField.Copy

Parameters

LCField. The field object that you want to copyorigField


Return Value

LCField. The copy of the original field.newField

DescriptionValue


Usage NotesYou must explicitly use the copy method. If instead, you use the statement:

Set newField = origField

you have not copied the value of the field — you have merely createdanother “pointer” to the same LCField object. If you then change the valuestored in newField, the value in origField will also change (and vice versa)because they are in reality the same field.


Uselsx "*lsxlc"

Sub Initialize

Dim field As New LCField (LCTYPE_FLOAT)

Dim c_field As LCField

field.value = 12345.123456789

Set c_field = field.Copy

Print "The float field is " & field.text(0)

Print "and its copy is " & c_field.text(0)

End Sub

Example OutputThe float field is 12345.123456789 and its copy is12345.123456789.

GetCurrency Method for LCFieldThis method retrieves a Currency data type from a value in a field. If therequested data type is different from the field data type, conversion isautomatically performed. If conversion is not possible, errorLCFAIL_INVALID_CONVERT occurs.

Defined InLCField

SyntaxSet newCurrency = lcField.GetCurrency(index)


Parameters

Long, >= 1. Index of the field data value to be retrieved.index


Return Value

LCCurrency. The value of the retrieved data type.newCurrency

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize

On Error LCFAIL_INVALID_CONVERT Goto InvalidCurrency

Dim Fld As New LCField (LCTYPE_TEXT)

Fld.Text = "1234.56789"

Dim vCurr As LCCurrency

Set vCurr = Fld.GetCurrency (1)

Print "The Currency representation of the field is " &vCurr.Text

Exit Sub

InvalidCurrency:

Print "Cannot convert " & Fld.Text & " to type Currency."

Exit Sub

End Sub

Example OutputThe Currency representation of the field is 1234.5678.

GetDatetime Method for LCFieldThis method retrieves a Datetime data type from a value in a field. If therequested data type is different from the field data type, conversion isautomatically performed. If conversion is not possible, errorLCFAIL_INVALID_CONVERT occurs.

Defined InLCField


SyntaxSet newDatetime = lcField.GetDatetime(index)

Parameters



Return Value

LCDatetime. The value of the retrieved data type.newDatetime

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize


Dim vDate As LCDateTime

Fld.Text = "10/12/1998"

Set vDate = Fld.GetDatetime (1)

Print "The Datetime representation of the field is " &vDate.Text

End Sub

Example OutputThe Datetime representation of the field is 10/12/1998.

GetFieldlist Method for LCFieldThis method retrieves a fieldlist from a field. The resulting fieldlist is areference to the original inside the field. If the field doesn’t contain anLCFieldlist as its value, an LCFAIL_INVALID_CONVERT error will occur.

An LCField object can contain a reference to an LCFieldList, allowing youto nest a fieldlist inside another fieldlist. This lets you manage informationin memory that includes records that contain multi-valued information. Anexample of this is an order processing application where a single order ID isthe key field for a table containing multiple line item entries per order. Youcan create a field list that contains the order key (and any other informationthat appears only once in the record) and a field that contains an LCFieldlistgiving the order rows, which may have multiple occurrences.


The LC does not contain any methods that support reading or writingcomplex records such as this in a single step, but this feature may be helpfulin organizing your data and code.

Defined InLCField

SyntaxSet newFieldList = lcField.GetFieldList(index)

Parameters



Return Value

LCFieldList. The value of the retrieved data type.newFieldList

DescriptionValue


Option Explicit

Uselsx "*lsxlc"

Sub Initialize

Dim Record As New LCFieldlist

Dim SubRecord As New LCFieldlist


' start building FieldList

Set field = Record.Append ("group", LCTYPE_INT)

field.Value = 4200

' Build SubFieldList

Set field = SubRecord.Append ("category", LCTYPE_TEXT)

field.Value = "potato"

Set field = SubRecord.Append ("description", LCTYPE_TEXT)


field.Value = "russet"

Set field = SubRecord.Append ("sku", LCTYPE_INT)

field.Value = 4207

' return to building the FieldList

Set field = Record.Append ("item", LCTYPE_FIELDLIST)

' now assign the SubRecord to the Record

Call field.SetFieldList (1, SubRecord)

Delete SubRecord

Set SubRecord = field.getFieldList (1)

Print "The first field of the field's fieldlist is " &SubRecord.Names(0)

End Sub

Example OutputThe first field of the field's fieldlist is category.

GetFloat Method for LCFieldThis method retrieves a LotusScript double data type from a value in afield. If the requested data type is different from the field data type, conver-sion is automatically performed.

Defined InLCField

SyntaxnewFloat = lcField.GetFloat(index)

Parameters



Return Value

Double. The value of the retrieved data type.newFloat

DescriptionValue


Uselsx "*lsxlc"


Sub Initialize


Fld.Text = "1234.56789"

Dim vFloat As Double

vFloat = Fld.GetFloat (1)

Print "The Float representation of the field is " & vFloat

End Sub

Example OutputThe Float representation of the field is 1234.56789.

GetFormatDatetime Method for LCFieldThis method retrieves the format of a Datetime type field. It is only valid forfields of type Datetime.

Use the LCField.SetFormatDatetime method to assign stream format infor-mation. Refer to the Field Format section for a description of format values.

Defined InLCField

SyntaxCall thisField.GetFormatDatetime(dateTimeFlags, size)

ParametersAll GetFormat<type> parameters are outputs.

Long. Optional. Size in bytes of the datetime field. Zero indicatesthe size of a Lotus Connector Datetime (8bytes).

size

Long. Optional. Datetime flags of the field. Refer in this chapterto “LCField Class Methods and Properties Summary,” FieldFormat Datetime section for a description of the flags.

dateTimeFlags



Uselsx "*lsxlc"

Sub Initialize

Dim field As New LCField (LCTYPE_DATETIME, 1)


Dim flags As Long

Dim size As Long

Call field.SetFormatDatetime (LCDATETIMEF_NO_TIME, 0)

Call field.GetFormatDateTime (flags, size)

Print "The datetime format flag setting is " & Hex(flags) & _

"h, size = " & size & " bytes."

End Sub

Example OutputThe datetime format flag setting is 2h, size = 0 bytes.

GetFormatNumber Method for LCFieldThis method retrieves the format of a number type field. It is only valid forfields of type int, currency, float or numeric.

Use the LCField.SetFormatNumber method to assign stream format infor-mation. Refer to the Field Format section for a description of format values.

Defined InLCField

SyntaxCall thisField.GetFormatNumber(numberFlags, size, precision, scale)

ParametersAll GetFormatNumber<type> parameters are outputs.

Long. Optional. Scale of the number field. Zero indicates not usedfor this field. Since zero is also a valid scale value, a constantLCSCALE_ZERO is defined which can be used to indicate a zeroscale.

scale

Long. Optional. Precision of the number field. Zero indicates notused for this field.

precision

Long. Optional. Size in bytes of the number field. Zero indicatesthe size of the corresponding number object (LONG, DOUBLE,LCCURRENCY, or LCNUMERIC).

size

Long. Optional. Formatting flags of the number field. Refer in thischapter to “LCField Class Methods and Properties Summary,”Field Number Format section for a description of the flags.

numberFlags



Usage Notes“Precision” refers to the total number of digits that may be stored in thefield. “Scale” refers to the number of digits precision to store after thedecimal point.

The size, precision, and scale values are ignored with the LCTYPE_FLOATand LCTYPE_INT types. These are system data types, whose operation isnot customizable.


Uselsx "*lsxlc"

Sub Initialize

Dim field As New LCField (LCTYPE_NUMERIC)

Dim flags As Long

Call field.SetFormatNumber (LCNUMBERF_UNSIGNED, , 10, 4)

Call field.GetFormatNumber (flags)

Print "The number flag setting is " & Hex(flags) & "h"

End Sub

Example OutputThe number flag setting is 1h.

GetFormatStream Method for LCFieldThis method retrieves the format of a stream type field. It is only valid forfields of type text or binary.

Use the LCField.SetFormatStream method to assign stream format informa-tion. Refer to the Field Format section for a description of format values.

Defined InLCField

SyntaxCall thisField.GetFormatStream(streamFlags, maxLength, streamFormat)


ParametersAll GetFormatStream parameters are outputs.

Long. Optional. Stream format of the stream field. A value ofzero indicates no specified stream format.

streamFormat

Long. Optional. Maximum length of the stream field. A value ofzero indicates no maximum length.

maxLength

Long. Optional. Stream flags for the field. Refer in this chapter to“LCField Class Methods and Properties Summary,” Stream Classsection for a description of the flags.

streamFlags

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize

Dim field As New LCField (LCTYPE_BINARY)

Dim fmt As Long

Dim flags As Long

Call field.SetFormatStream (LCSTREAMF_NO_CASE, 256,LCSTREAMFMT_BIG5)

Call field.GetFormatStream (flags, , fmt)

Print "The stream format and flag settings are:"

Print "format=" & fmt & " flags=" & Hex(flags) & "h"

End Sub

Example OutputThe stream format and flag settings are:

format=26 flags=10h

GetInt Method for LCFieldThis method retrieves an integer from a value in a field. If the requesteddata type is different from the field data type, conversion is automaticallyperformed. If conversion is not possible, errorLCFAIL_INVALID_CONVERT occurs.

Defined InLCField


SyntaxnewInt = thisField.GetInt(index)

Parameters



Return Value

Long. The indexth value in thisField, converted to an integer value.newInt

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize


Fld.Text = "1234.56789"

Dim vInt As Long

vInt = Fld.GetInt (1)

Print "The Int representation of the field is " & vInt

End Sub

Example OutputThe Int representation of the field is 1234

GetNumeric Method for LCFieldThis method retrieves a numeric value from a value in a field. If therequested data type is different from the field data type, conversion isautomatically performed. If conversion is not possible, errorLCFAIL_INVALID_CONVERT occurs.

Defined InLCField

SyntaxSet newNumeric = thisField.GetNumeric(index)


Parameters



Return Value

LCNumeric. The index th value in thisField, converted to a numerictype.

newNumeric

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize


Fld.Text = "1234.56789"

Dim vNumr As LCNumeric

Set vNumr = Fld.GetNumeric (1)

Print "The Numeric representation of the field is " &vNumr.Text

End Sub

Example OutputThe Numeric representation of the field is 1234.56789

GetStream Method for LCFieldThis method retrieves a stream value from a field. If the requested data typeis different from the field data type, conversion is automatically performed.If conversion is not possible, error LCFAIL_INVALID_CONVERT occurs.

Defined InLCField

SyntaxSet newStream = thisField.GetStream (index, streamFormat)


Parameters

Long. Stream format to obtain the data in. For a list of valid values,refer in this chapter to “LCField Class Methods and PropertiesSummary,” Stream Formats section. Any stream format is allowed.In addition, a value of zero will either use the stream format of thefield (if this Field is TEXT or BINARY), or convert to native textformat LCSTREAMFMT_NATIVE (if thisField is not a local type).

streamFormat



Return Value

LCStream. The value of the index th data element of thisField.newStream

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize


Fld.Text = "1234.56789"

Dim vStrm As LCStream

Set vStrm = Fld.GetStream (1, LCSTREAMFMT_ASCII)

Print "The Stream representation of the field is " &vStrm.Text

End Sub

Example OutputThe Stream representation of the field is 1234.56789.

IsNull Method for LCFieldThis method returns true or false depending on whether the specified fielddata is NULL. A field may potentially contain multiple values, some ofwhich are null and others not.

Defined inLCField

Syntaxflag = thisfield.IsNull(index)


Parameters

Long. Index identifying the field.index


Return Value

Boolean value, either TRUE or FALSE. flag

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize

Dim field As New LCField (LCTYPE_INT, 4) ' four values in onefield.

Dim i%

Call field.SetInt(1, 2020)

Call field.SetInt(4, 12)

For i = 1 To 4

If field.IsNull(i) Then

Print "value " & i & " is null"

Else

Print "value " & i & " = " & field.GetInt(i)

End If

Next

End Sub

Example Outputvalue 1 = 2020

value 2 is null

value 3 is null

value 4 = 12


LookupVirtualCode Method for LCFieldThis method checks if a specific VirtualCode has been set for a field. Virtualcodes flag fields as special system properties recognized by differentsystems. Refer to the connector documentation for specific codes supportedby each connection.

Defined InLCField

SyntaxFlag = field.LookupVirtualCode(virtualCode)

Parameters

The virtual code to look for on the list of codes for this field.virtualCode


Return Value

Boolean. TRUE if this virtual code is set for the field; FALSE otherwise.Flag

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize





Dim Code As Long





Wend

If (field.LookupVirtualCode (&H10000)) Then

Print "The field has virtual code 10000h set."


Else

Print "The field does not have virtual code 10000h set."

End If

End Sub

Example OutputThe field has virtual code 10000h set.

SetCurrency Method for LCFieldThis method sets a field value to a supplied LCCurrency value. If the fieldis not of a Currency data type, Notes will attempt to convert the suppliedvalue to the data type of the field. If conversion fails, errorLCFAIL_INVALID_CONVERT will occur.

The data type of the field will not change to Currency because of this opera-tion. It will stay the same type but its value will change.

Defined InLCField

SyntaxCall thisField.SetCurrency(index, srcCurrency)

Parameters

LCCurrency. Value to be assigned to the field data value.srcCurrency

Long, >=1. Index of the value to be assigned.index



Uselsx "*lsxlc"

Sub Initialize

Dim field As New LCField (LCTYPE_TEXT)

Dim number As New LCCurrency

number.value = 1234567890.1234

Call field.SetCurrency (1, number)

Print "The field's value is " & field.text(0)

End Sub


Example OutputThe field's value is 1234567890.1234.

SetDatetime Method for LCFieldThis method sets a field value to a supplied LCDatetime value. If the field isnot of a datetime data type, Notes will attempt to convert the suppliedvalue to the data type of the field. If conversion fails, errorLCFAIL_INVALID_CONVERT will occur. Datetimes can only be convertedto Stream data types.

The data type of the field will not change to date/time because of thisoperation. It will stay the same type but its value will change.

Defined InLCField

SyntaxCall thisField.SetDateTime(index, srcDateTime)

Parameters

LCDatetime. Value to be assigned to the field data value.srcDateTime

Long. Index identifying the value that is to be assigned.index



Uselsx "*lsxlc"

Sub Initialize


Dim clock As New LCDatetime

clock.SetCurrent

Call field.SetDatetime (1, clock)


End Sub

Example OutputThe field's value is 09/08/1999 05:22:30.86 PM


SetFieldlist Method for LCFieldThis method assigns the fieldlist value to the specified index of the field. Ifthe field data type is different, an LCFAIL_INVALID_CONVERT error willoccur.

Refer to the GetFieldList method for an explanation of fields that containfieldlists as values.

Defined InLCField

SyntaxCall thisField.SetFieldlist(index, srcFieldlist)

Parameters

LCFieldlist. Value to be assigned to the field data value.srcFieldlist




Option Explicit

Uselsx "*lsxlc"

Sub Initialize

Dim Record As New LCFieldList

Dim SubRecord As New LCFieldList


' start building FieldList

Set field = Record.Append ("group", LCTYPE_INT)

field.Value = 4200

' Build SubFieldList

Set field = SubRecord.Append ("category", LCTYPE_TEXT)

field.Value = "potato"

Set field = SubRecord.Append ("description", LCTYPE_TEXT)

field.Value = "russet"

Set field = SubRecord.Append ("sku", LCTYPE_INT)

field.Value = 4207


' return to building the FieldList

Set field = Record.Append ("item", LCTYPE_FIELDLIST)

' now assign the SubRecord to the Record

Call field.SetFieldList (1, SubRecord)

' Take a look at the Record while debugging the LotusScript

Print "The sub fieldlist has successfully been appended toparent fieldlist as another field."

End Sub

Example OutputThe sub fieldlist has successfully been appended to parentfieldlist as another field.

SetFloat Method for LCFieldThis method assigns a value to a field of type float. If the field data type isdifferent, conversion will be attempted. If conversion fails, errorLCFAIL_INVALID_CONVERT will occur.

Defined InLCField

SyntaxCall thisField.SetFloat(index, srcFloat)

Parameters

LCFieldlist. Value to be assigned to the field data value.srcFieldlist

Long, >= 1. Index of the value to be assigned.index



Uselsx "*lsxlc"

Sub Initialize


Dim number As Double

number = Pi

Call field.SetFloat (1, number)



End Sub


SetFormatDatetime Method for LCFieldThis method changes the format setting for a datetime field. Calling thismethod clears all values for this field. The field must be of a datetime type,or error LCFAIL_TYPE_MISMATCH will occur.

Defined InLCField

SyntaxCall thisField.SetFormatDatetime(datetimeFlags, size)

Parameters

Long. Optional, >= 1. Size in bytes assigned to the datetime field.Zero indicates the size of an Lotus Connector Datetime (8 bytes).The default is 0.

The size value is used for metadata creation by data systemswhich support datetime data types of different sizes. For systemswhich support only a single datetime data type, the value of sizeis ignored. The default value for size is zero.

For example, Sybase supports both a 4-byte datetime and an8-byte version. When building up a fieldlist that will be used tocreate a Sybase table (see LCConnection.Create for an example),use the SetFormatDatetime method to indicate which sizedatetime data type should be used.

size

The datetimeFlags do not affect the data. As with the size value, itis only relevant when interacting with the external system. Theflags will have no effect on the conversion of a field’s value to orfrom a stream or text.

Source type is date only.LCDATETIMEF_NO_TIME

Source type is time only.LCDATETIMEF_NO_DATE

DescriptionFlag

Long. Formatting flags that govern how the data is written to orread from an external system.

dateTimeFlags




Uselsx "*lsxlc"

Sub Initialize

Dim field As New LCField (LCTYPE_DATETIME, 1)

Dim flags As Long

Dim size As Long

Call field.SetFormatDatetime (LCDATETIMEF_NO_TIME, 0)

Call field.GetFormatDateTime (flags, size)

Print "The datetime format flag setting is " & Hex(flags) & "h"

End Sub

Example OutputThe datetime format flag setting is 2h.

SetFormatNumber Method for LCFieldThis method assigns the current format setting for a number field. Callingthis method clears all values for this field.

Defined InLCField

SyntaxCall thisField.SetFormatNumber (numberFlags, size, precision, scale)

Parameters

continued

Long. Optional, >= 0. Size in bytes assigned to the number field. Zeroindicates the size of the corresponding number object (LONG,DOUBLE, LCCURRENCY, or LCNUMERIC). The default is 0. Thesize setting doesn’t affect the behavior of the field within yourprogram; it is only relevant when interacting with an externalsystem.

size

Long. Optional. Number flags assigned to the number field. Refer tothe Field Number Format section for a description of the flags. Thedefault is 0.

numberFlags



Long. Optional, >= 0. Scale assigned to the number field. Zeroindicates not used for this field. Since zero is also a valid scale value,a constant LCSCALE_ZERO is defined which can be used to indicatea zero scale. The default is LCMAX_NUMERIC_PREC / 2.

scale

Long. Optional, >= 0. Precision assigned to the number field. Zeroindicates not used for this field. The default isLCMAX_NUMERIC_PREC.

precision


Usage Notes“Precision” refers to the total number of digits that may be stored in thefield. “Scale” refers to the number of digits precision to store after thedecimal point.

The size, precision, and scale values are ignored with the LCTYPE_FLOATand LCTYPE_INT types. These are system data types, whose operation isnot customizable.


Uselsx "*lsxlc"

Sub Initialize

Dim field As New LCField (LCTYPE_NUMERIC)

Dim flags As Long

Call field.SetFormatNumber (LCNUMBERF_UNSIGNED, , 10, 4)

Call field.SetFloat(3045.093657)

Call field.GetFormatNumber (flags)

Print "The number flag setting is " & Hex(flags) & "h."

Print "Value = " & field.Text(0)

End Sub

Example OutputThe number flag setting is 1h.

Value = 3045.0936


SetFormatStream Method for LCFieldThis method assigns the current format setting for a stream field. Callingthis method clears all values for this field.

Defined InLCField

SyntaxCall thisField.SetFormatStream(streamFlags, maxLength, streamFormat)

Parameters

Long. Optional. Stream format assigned to the stream field. Thismay be either a character set selection from Appendix D or one ofseveral special formats listed in the “LCStream Class” Chapter, inthe “Stream Format” section . A value of zero indicates no specifiedstream format. The default is LCSTREAMFMT_UNICODE.

streamFormat

Long, >= 0. Optional. Maximum length assigned to the streamfield. A value of zero indicates no maximum length. The default is0.

maxLength

Long. Optional. Stream flags assigned to the field. In this chapterrefer “LCField Class Methods and Properties Summary”, under“Stream” for a description of the flags. The default is 0.

streamFlags



Uselsx "*lsxlc"

Sub Initialize

Dim field As New LCField (LCTYPE_BINARY)

Dim fmt As Long

Dim flags As Long

Call field.SetFormatStream (LCSTREAMF_NO_CASE, 256,LCSTREAMFMT_BIG5)

Call field.GetFormatStream (flags, , fmt)

Print "The stream format and flag settings are: format=" &fmt & _ " flags=" & Hex(flags) & "h"

End Sub


Example OutputThe stream format and flag settings are:

format=26 flags=10h

SetInt Method for LCFieldThis method sets the value of the field to a specified long integer value. Ifthe field is not of type LCTYPE_INT, Notes tries to convert the value to thefield’s type. If this fails, error LCFAIL_INVALID_CONVERT will occur.

The data type of the field will not change from this operation — only thefield’s value.

Defined InLCField

SyntaxCall thisField.SetInt (index, srcInt)

Parameters

Long. Value to be assigned to the field data value.srcInt

Long, >=1 . Indexof the value to be assigned.index



Uselsx "*lsxlc"

Sub Initialize


Dim number As Long

number = Pi

Call field.SetInt (1, number)


End Sub

Example OutputThe field's value is 3.


SetNumeric Method for LCFieldThis method sets the value of the field to a specified LCNumeric value. Ifthe field is not of type LCTYPE_NUMERIC, Notes tries to convert the valueto the field’s type. If this fails, error LCFAIL_INVALID_CONVERT willoccur.


Defined InLCField

SyntaxCall thisField.SetNumeric(index, srcNumeric)

Parameters

LCNumeric. Value to be assigned to the field data value.srcNumeric

Long, >= 1. Index of the value to be assigned.index



Uselsx "*lsxlc"

Sub Initialize


Dim number As New LCNumeric

number.value = 1234567890.12345678

Call field.SetNumeric (1, number)


End Sub


SetStream Method for LCFieldThis method sets the value of the field to a specified LCStream value (textor binary). If the field is not of type LCTYPE_STREAM, or is of that type butuses a format that does not match the supplied value (text as opposed to


binary, for instance), Notes tries to convert the value to the field’s type. Ifthis fails, error LCFAIL_INVALID_CONVERT will occur.


Defined InLCField

SyntaxCall thisfield.SetStream(index, srcStream)

Parameters

LCStream. Value to be assigned to the field data value.srcStream




Uselsx "*lsxlc"

Sub Initialize


Dim msg As New LCStream

msg.Text = "Hello World"

Call field.SetStream (1, msg)


End Sub

Example OutputThe field's value is Hello World.

SetVirtualCode Method for LCFieldThis method adds a virtual code to the list of virtual codes for a field.Virtual codes flag fields as special system properties recognized by differentsystems. Refer to the connector documentation for specific codes supportedby each connection.

Defined InLCField


SyntaxCall thisField.SetVirtualCode(virtualCode)

Parameters

Long. VirtualCode value to assign to this Field.virtualCode



Uselsx "*lsxlc"

Sub Initialize





Dim Code As Long

Dim text As String



text = Hex(Code) & "h"



text = text & ", " & Hex(Code) & "h"

Wend

Print "The field virtual codes (one per connector) are " &text

End Sub

Example OutputThe field virtual codes (one per connector) are 10000h,20000h, 30000h, 40000h, 50000h.


Chapter 6LCFieldlist Class

This chapter provides information about the LCFieldlist class methods andproperties.

OverviewThe LCFieldlist class represents metadata (the description of data from adata source) for a record and may reference data, in the form of LCFields,for one or more record values. A fieldlist is a list of fields and field nameswith a represented order. Fields within a fieldlist can be added, modified,retrieved, or listed in multiple ways. The fields, field names, and order areseparate entities and only have relation within an individual fieldlist.

Many situations exist where the names or order must be changed to accom-modate different connections, but the data needs to remain constant. Inthese situations, more than one fieldlist can be created, each referenced bythe same fields using the Map, MapName, or Merge methods.

An LCFieldlist can be dimensioned to contain one row of fields (the default)or multiple rows, allowing array operations that fetch or update multipleentries in a result set in a single operation. If your external system datasource supports array operations, this can substantially enhance perform-ance. If it does not support array operations, you can still do multiple-rowfetches and updates, but you get no performance gain from doing so.

In addition to regular LCField items, an LCFieldList can also contain one ormore other LCFieldlists nested inside. This is done by using an LCFielditem containing a data value of type LCFIELDLIST. Refer to theLCField.SetFieldList and GetFieldList methods for examples. This is usefulin situations where a one-to-many relationship exists between data indifferent tables. For example, suppose you have an order entry system withan order number and multiple line items in the order. You can create anLCFieldlist to work with these tables that contains the order number (astream field) and a sublist that contains all the line items for that order.

155

This ability is just a convenience for maintaining data in memory; it’s notcurrently possible to use these nested lists to read or update structuredinformation in a single operation.



Uselsx "*lsxlc"

Sub Initialize



Dim MyOracleConnection as NewLCConnection("MyOracleConn")


Accessing Field DataField data within an LCFieldlist object may be accessed as a property byname. The data type of the property depends on the data type of the field.The property is an array of LotusScript data types, as shown in the tablebelow. For example, if a fieldlist has a field named OrderID, its first valuemay be obtained with the following script:

Identification = fieldlist.OrderID(0)

The field may be set with the following syntax:

fieldlist.OrderID = "Bart-001"

The LCFieldlist object may contain one or more values for each fieldcontained within, depending on the parameters to the constructor. If theobject is constructed for more than a single value, subsequent values maybe accessed through the field names by changing the subscript. Multiplevalues may be set by assigning an array.

The value is an array even if the field contains just a single value (as iscommonly the case). The array index always starts at zero, as is usual for aLotusScript array, whereas the index value supplied as a parameter tovarious methods, starts at one. When using the fieldlist.fieldname format,you must subtract one to get the equivalent index.


Note The following syntax is not legal:

fieldlist.OrderID(0) = "Bart-001" ' NOT VALID

You can not specify an index on the left side of the = assignment operator;you must assign the whole field. If the field is multivalued, use an array onthe right side of the = or else use the LCField properties to assign one valueat a time.

StringLCTYPE_BINARY

StringLCTYPE_TEXT

DoubleLCTYPE_NUMERIC

DoubleLCTYPE_FLOAT

LongLCTYPE_INT

Variant (Date/Time)LCTYPE_DATETIME

CurrencyLCTYPE_CURRENCY

Value Return TypeField Type

Fieldlist Merging and MappingFieldlist merging with LCFieldlistMerge and LCFieldlistMergeVirtualsupport field mapping. To perform mapping, two fieldlists are provided,one as the name source and the other as the field/data source. Dependingon merge options, a mapping is produced between the names of the namesource and the fields of the data source, and a third fieldlist is producedwhich references parts of the original fieldlists. When using virtual fieldsand LCFieldlistMergeVirtual, fields in the data fieldlist which match thesupplied virtual code are excluded from mapping and are added to aseparate new virtual fieldlist.

Mapping and MergingWhen a fieldlist is to be used for more than one specific action, there is oftena need to have it treated differently by each of those actions. For example,fields in a fieldlist map need to be reordered, renamed, or removed, butonly in the context of one particular operation. For such situations, thefollowing four methods are provided to perform this mapping:

• Map

• MapName

• Merge

• MergeVirtual

MergeVirtual is simply a variation of Merge which handles virtual codes as well. These methods produce a new fieldlist from an existing fieldlist, but with the same fields referenced from both fieldlists, allowing two

Chapter 6: LCFieldlist Class 157

different ’maps’ into a set of fields. If these two fieldlists are sent to differentConnector methods, then the Connectors will see different sets of fields in adifferent order, but referring to the same data and common fields.

The three methods Map, MapName, and Merge have various levels of diffi-culty and control available to the caller; which one is needed depends onthe specific situation. In general, the simplest method which supports yourrequirements should be used. These methods are listed below, starting withthe simplest.

Map is applicable when the names in the fieldlist are correct, but fieldseither need to be reordered or removed. It accepts a fieldlist and a text listof names, and the new fieldlist contains the fields from the original fieldlistreordered in the order they are listed in the text list. In addition, any fieldsnot included in the text list are excluded from the new fieldlist.

MapName adds renaming of fields to Map, but is otherwise identical. Byadding a second text list of names, it will rename each field in the first textlist with the corresponding entry in the second text list.

Merge accepts two fieldlists, one which provides the list of fields, and onewhich provides the list of names. In addition, it accepts a set of flags whichfurther control the new fieldlist produced. These flags control the type ofmapping, whether to allow fields to be excluded from either fieldlist, andhow to interact with specific field flags. Merge should only be used whenthe functionality of Map and MapName is insufficient for your needs, asMerge is much more complex to use.

LCFieldlist Class Methods Summary

CreationThe following methods create and free fieldlist instances. The fieldlistmerging methods also create new fieldlists.

Destructor. Frees a fieldlist object instance created with theconstructor, LCFieldlist.Copy, LCFieldlist.CopyRef,LCFieldlist.Merge, or LCFieldlist.MergeVirtual.

Delete LCFieldlist

Creates a new fieldlist object instance as a partial copy ofanother fieldlist. The contained fields are not copied, butare rather referenced.

LCFieldlist.CopyRef

Creates a new fieldlist object instance as a copy of anotherfieldlist. The field data is also copied.

LCFieldlist.Copy

Constructor. Creates a new fieldlist object instance.New LCFieldlist

DescriptionMethod


Fieldlist RetrievalThe following methods support retrieval of fieldlist contents.

Iterates through fields in a fieldlist.LCfieldlist.List

Locates a field in a fieldlist by field name.LCFieldlist.Lookup

Retrieves a copy of a field name from a fieldlist by fieldindex.

LCFieldlist.GetName

Retrieves a particular field from a fieldlist by field index.LCFieldlist.GetField

DescriptionMethod

Fieldlist ModificationThe following methods support modification of fieldlist contents.

Renames a field within a fieldlist.LCFieldlist.SetName

Embeds an existing field into a fieldlist.LCFieldlist.Includefield

Copies an existing field into a fieldlist.LCFieldlist.Copyfield

Replaces a field in a fieldlist with a new field.LCFieldlist.Replace

Removes a field from a fieldlist.LCFieldlist.Remove

Inserts a new field into a fieldlist.LCFieldlist.Insert

Adds a new field to the end of a fieldlist.LCFieldlist.Append

DescriptionMethod

Fieldlist MergingThe following methods support fieldlist merging.

Merges a name fieldlist and data fieldlist to produce amapped fieldlist. Fields with matching virtual codes areadded to a new virtual fieldlist.

LCFieldlist.MergeVirtual

Merges a name fieldlist and data fieldlist to produce amapped fieldlist.

LCFieldlist.Merge

DescriptionMethod

Fieldlist MappingThe following methods support fieldlist mapping.

Maps fields with different names.LCFieldlist.MapName

Maps fields with the same names but changes thepositions and can exclude some fields.

LCFieldlist.Map

DescriptionMethod


LCFieldlist Properties SummaryThe following is a list of fieldlist properties.

Retrieves the current sequence number for a fieldlist.LCFieldlist.GetSequence

Retrieves the record count supplied when allocatinga fieldlist.

LCFieldlist.GetRecordCount

Retrieves the current number of fields in a fieldlist.LCFieldlist.GetCount

DescriptionProperty

All other properties are dynamic. Field data may be accessed by referencingthe field name.

New Method for LCFieldlistThis is the constructor for LCFieldlist.

Defined InLCFieldlist

SyntaxDim variableName as New LCFieldlist(recordCount, fieldFlags)

Parameters

Long. Optional. The default field flags for the fieldlist (zero ormore LCFIELDF_XXX flags ORed together). These are set as theinitial field flags for each field added to the fieldlist. The defaultis LCFIELDF_TRUNC_PREC.

fieldFlags

Long. Optional, >= 1. The number of records in the fieldlist. Thedefault is 1. All fields added to the fieldlist will have this numberof records. Select a higher number to allow multiple-rowoperations (for example, to Fetch several rows at a time).

recordCount



Uselsx "*lsxlc"

Sub Initialize

Dim record As New LCFieldlist(1, 0)

' Space to contain one record, with no precisiontruncation allowed.


Append Method for LCFieldlistThis method creates a new field and appends it to an existing fieldlist.


SyntaxSet field = fieldlist.Append(fieldName, dataType)

Parameters

LCTYPE_CONNECTION

LCTYPE_FIELDLIST

LCTYPE_BINARY

LCTYPE_TEXT

LCTYPE_DATETIME

LCTYPE_NUMERIC

LCTYPE_CURRENCY

LCTYPE_FLOAT

LCTYPE_INT

Long. The constant for the data type. One of the following:dataType

String. The name for the field.fieldName


Return Value

A pointer to the new field.LCField

DescriptionValue

Usage NotesIf you need the field format to be other than the default for its type, or ifyou need to refer to the field conveniently later, store the new field refer-ence in a variable. The code below demonstrates this technique.


Option Explicit

Uselsx "*lsxlc"

Sub Initialize

REM this example copies a DB2 table.




Dim companyname As LCField

REM build the table definition.

Call FldLstRecord.Append ("ACCOUNTMANAGER", LCTYPE_INT)

Call FldLstRecord.Append ("CONTACTNAME", LCTYPE_TEXT)

Set companyname = FldLstRecord.Append ("COMPANYNAME",LCTYPE_TEXT)

Call companyname.SetFormatStream(, 40) ' max length forcompany name _ is 40 chars.

REM set properties to connect to both data sources.


src.Userid = "JDoe"



REM now connect.

src.Connect

REM create it based on the metadata property already setabove.

On Error LCFAIL_DUPLICATE Goto tableexists

Call src.Create (LCOBJECT_METADATA, fldLstRecord)

Print "The '" & src.Metadata & "' table did not exist so itwas created."

End

tableexists:

Print "The '" & src.Metadata & "' table exists."

End

End Sub

Example OutputThe 'customer' table exists.


Copy Method for LCFieldlistThis method creates a duplicate copy of an LCFieldlist and all its data.Every field in the LCFieldlist is also duplicated, so you don’t end up withtwo fieldlists that both refer to the same LCField objects.

If you want to have two fieldlists that reference the same LCField objects,use CopyRef instead.


SyntaxSet fldListRecordNew = fldListRecord.Copy

Parameters

LCFieldlist. The fieldlist that you want to copy.fldListRecord


Return Value

LCFieldlist. The copy of the fldListRecord object.fldListRecordNew

DescriptionValue


Option Explicit

Uselsx "*lsxlc"

Sub Initialize

Dim olist As New LCFieldlist

Dim nlist As LCFieldlist

Dim ofield As LCField, nfield As Lcfield

Set ofield = olist.Append ("FirstName", LCTYPE_TEXT)

ofield.Text = "Chi Len"

Set nlist = olist.Copy

Set nfield = nlist.GetField (1)

Print "before update, original=" & ofield.Text(0) & ",copy=" & nfield.Text(0)

nfield.Text = "Cheiko"


Print "after update, original=" & ofield.Text(0) & ",copy=" & nfield.Text(0)

Call nlist.Setname(1, "FullName")

Print "The copy contains field named " & nlist.Names(0)_

& " whose value is " & nfield.Text(0)

End Sub

Example Outputbefore update, original=Chi Len, copy=Chi Len

after update, original=Chi Len, copy=Cheiko

The copy contains field named FullName whose value is Cheiko

CopyField Method for LCFieldlistThis method copies an existing field and inserts a copy of the field within afieldlist at a specified position.


SyntaxSet newField = fieldList.CopyField(index, srcField, name)

Parameters

String. The name to give the copy of the field.name

LCField. The source field to copy.srcField

Long, in the range 1 to (fieldList.FieldCount + 1). Position to insertthe new field into the list. You may insert into the middle of the list,which will not overwrite an existing field.

index


Return Value

LCField. The new copy of srcField.newField

DescriptionValue


Option Explicit

Uselsx "*lsxlc"


Sub Initialize


Dim fld As New LCField (LCTYPE_TEXT)

Dim ref As LCField

Dim text As String

' There are a number of ways to build a fieldlist

' Append will add a field to a list given a type

Set ref = FldLstRecord.Append ("ACCOUNTMANAGER", LCTYPE_INT)

Set ref = FldLstRecord.Append ("COMPANYID", LCTYPE_INT)

' Insert is like Append but the position within

' the fieldlist must be specified

Set ref = FldLstRecord.Insert (1, "COMPANYADDRESS",LCTYPE_TEXT)

' CopyField will add a field to a list

' using an existing field as a template


Set ref = FldLstRecord.CopyField (1, fld, "CONTACTNAME")

' IncludeField will add an existing field to a list,

' making it part of the list. In this case, 'fld'

' becomes a reference into the fieldlist

fld.Flags = 0

Call FldLstRecord.IncludeField (3, fld, "COMPANYCITY")

text = ""

Forall fieldname In FldLstRecord.Names

If Text = "" Then text = fieldname Else text = text + ", " +fieldname

End Forall

Print "The field list looks like: " & text

End Sub

Example OutputThe field list looks like:

CONTACTNAME, COMPANYADDRESS, COMPANYCITY, ACCOUNTMANAGER,COMPANYID


CopyRef Method for LCFieldlistThis method creates a new fieldlist object instance as a partial copy ofanother fieldlist. The fields in the original fieldlist are not copied, but arereferenced.

This method creates a new fieldlist with separate name space but with thesame fields and data space as an existing fieldlist. The field names arecopied, but the new fieldlist references the original fields. In this situation,any changes to the data of one fieldlist is actually a change to the data for allfieldlists referencing the same data space.

Note The name of a field is not stored in the LCField object. Thisinformation is stored in the LCFieldlist. Therefore, if you use CopyRef andthen rename a field (SetName method), the same field will be known bydifferent names in the two lists.

To copy a fieldlist’s metadata and data, use LCFieldlistCopy.


SyntaxSet fldListRecordNew = fldListRecord.CopyRef

Parameters

LCFieldlist. The fieldlist that you want to make a referencecopy of.

fldListRecord


Return Values

LCFieldlist. The reference copy of the fieldlist.fldListRecordNew

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize

Dim olist As New LCFieldlist

Dim nlist As LCFieldlist

Dim ofield As LCField

Set ofield = olist.Append ("FirstName", LCTYPE_TEXT)


ofield.Text = "Chi Len"

Set nlist = olist.CopyRef

Set nfield = nlist.GetField (1)

Call olist.SetName (1, "FullName")

ofield.Text = "Cheiko"

Print "The copy contains field named " & nlist.Names(0) & ",value is " & nfield.Text(0)

Print "The original contains field named " & olist.Names(0) &", value is " & ofield.Text(0)

End Sub

Example OutputThe copy contains field named FirstName, value is Cheiko

The original contains field named FullName, value is Cheiko

GetField Method for LCFieldlistThis method gets a field reference from a specified position in a fieldlist andplaces its value into a variable.


SyntaxSet field = fldLstRecord.GetField(index)

Parameters

Long, in the range 1 to fldLst.FieldCount. Position of the fieldto be returned.

index


Return Values

LCField. The field at the index position in the fieldlist.field

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize



Dim conFldLst As New LCFieldList







' connect to DB2

connect.Connect

' now perform the catalog action - in this case for fields

If (connect.Catalog (LCOBJECT_FIELD, conFldLst) = 0) Then

Print "No tables were found."

Else

Set field = conFldLst.GetField(1)

Print "The columns in the '" & connect.Metadata & "' tableinclude:"

While (connect.Fetch (conFldLst) > 0)

Print " " & field.text(0)

Wend

End If

End Sub

Example OutputThe columns in the 'CUSTOMER' table include:

ACCOUNTMANAGER

CONTACTNAME

COMPANYNAME

COMPANYADDRESS

COMPANYCITY

COMPANYSTATE

COMPANYPHONE


GetName Method for LCFieldlistThis method obtains a copy of the name of a field within a fieldlist.


SyntaxfieldName = fldList.GetName(index)

Parameters

Long, in the range 1 to fldLst.FieldCount. The position of thefield in the fieldlist.

index


Return Values

String. The name of the field.fieldName

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize


Dim FldLst As New LCFieldlist


Dim i As Long






connect.Connect

' now perform the catalog action - in this case for fields

If (connect.Select (Nothing, 1, FldLst) = 0) Then

Print "The customer table was not found."

Else


Print "There are " & FldLst.FieldCount & _

" columns in the '" & connect.Metadata & "' table."

Print "They are:"

For i = 1 To FldLst.FieldCount

Print Tab(4); FldLst.GetName (i)

Next

End If

End Sub

Example OutputThere are 7 columns in the 'customer' table.

They are:

ACCOUNTMANAGER

CONTACTNAME

COMPANYNAME

COMPANYADDRESS

COMPANYCITY

COMPANYSTATE

COMPANYPHONE

IncludeField Method for LCFieldlistThis method includes an existing individual field in a fieldlist.


SyntaxCall fldLstRecord.IncludeField(index, field, fieldName)

Parameters

String. The name of the new field.fieldName

LCField. The new field.field

Long, in the range 1 to (fldLst.FieldCount+1). Position withinfldLstRecord to insert the field. You can insert the field into the middleof the list without overwriting another field.

index




Option Explicit

Uselsx "*lsxlc"

Sub Initialize


Dim ref As LCField

Dim text As String





' Insert is like Append but the position

' within the fieldlist must be specified

Set ref = FldLstRecord.Insert (1, "COMPANYADDRESS", LCTYPE_TEXT)





' making it part of the list. in this case, 'fld'




fld.Flags = 0


text = ""



End Forall

Print "The field list looks like: " & text

End Sub


Example OutputThe field list looks like:


Insert Method for LCFieldlistThis method inserts a new field into an existing fieldlist at a specified indexposition.


SyntaxSet fieldNew = fldLstRecord.Insert (index, fieldName, dataType)

Parameters

LCTYPE_CONNECTION

LCTYPE_FIELDLIST

LCTYPE_BINARY

LCTYPE_TEXT

LCTYPE_DATETIME

LCTYPE_NUMERIC

LCTYPE_CURRENCY

LCTYPE_FLOAT

LCTYPE_INT

Long. Data type of the new field. One of the following:dataType

String. Name of the new field.fieldName

Long, in the range 1 to (fldLst.FieldCount+1). Index number of thefield before which the new field is inserted. An index number equalto the number of fields currently in the fieldlist (plus one) isequivalent to using LCFieldlist.Append.

index



Option Explicit

Uselsx "*lsxlc"

Sub Initialize




Dim ref As LCField

Dim text As String





' Insert is like Append but the position

' within the fieldlist must be specified

Set ref = FldLstRecord.Insert (1, "COMPANYADDRESS", LCTYPE_TEXT)






' making it part of the list. in this case, 'fld'


fld.Flags = 0


text = ""



End Forall

Print "The field list is: " & text

End Sub

Example OutputThe field list is:



List Method for LCFieldlistThis method retrieves information about one field in the fieldlist. By callingit repeatedly, you can iterate through the fields in the list.


Syntaxflag = fldLst.List(position, destField, index, dataType, flags, fieldName)

Parameters

String. Output, optional. The field name.

Note This information is not also stored in destField.

fieldName

Long. Output, optional. Field flags of destField. Refer to the FieldClass section for a description of the flags.

flags

Long. Output, optional. Data type of destField.dataType

Long. Output, optional. Index of destField in the fieldlist. This maynot advance consecutively for fieldlists produced withLCFieldlist.Merge or LCFieldlist.MergeVirtual.

index

LCField. Output, optional. The field in the fieldlist.destField

Long. Constant indicating whether to return the first or next field.The options are:

LCLIST_FIRST — Return the first property in the property list.

LCLIST_NEXT — Return the next property (or the first property ifthis is the first call to this function for this Connection).

position



Uselsx "*lsxlc"

Sub Initialize



Dim pos As Long

Dim dtype As Long

Dim flags As Long

Dim fieldname As String


REM this section assigns the appropriate properties toconnect to DB2





REM connect to DB2

connect.Connect

REM select the records in the table (just to get the fielddescriptions)



Else

Print "The table description is:"

pos = LCLIST_FIRST

While (FldLst.List (pos, , , dtype, flags, fieldname) =True)

Print " " + fieldname + " is type #" +_

Cstr(dtype) + " with flags " + Hex(flags)

pos = LCLIST_NEXT

Wend

End If

End Sub

Example OutputThe table description is:

ACCOUNTMANAGER is type #1 with flags 2

CONTACTNAME is type #6 with flags 2

COMPANYNAME is type #6 with flags 2

COMPANYADDRESS is type #6 with flags 2

COMPANYCITY is type #6 with flags 2

COMPANYSTATE is type #6 with flags 2

COMPANYPHONE is type #6 with flags 2


Lookup Method for LCFieldlistThis method locates a field from a fieldlist based on field name.


SyntaxSet field = fldListRecord.Lookup (fieldName, index)

Parameters

Long. Output, optional. Position of the field.index

String. Name of the field to look up.fieldName


Return Value

LCField. The field whose name in this list is fieldName. If nosuch field exists, Nothing is returned.

field

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize




Dim pos As Long






REM connect to DB2

connect.Connect

REM now perform the catalog action - in this case for fields




Else

Set field = FldLst.Lookup ("contactname", pos)

If Not (field Is Nothing) Then

Print "Found 'ContactName' in the fieldlist at position " &pos

Else

Print "Did not find 'ContactName' in the fieldlist."

End If

End If

End Sub

Example OutputFound 'ContactName' in the fieldlist at position 2

Map Method for LCFieldlistThis method copies field references from one field list, into another fieldlist. It’s similar to the CopyRef method, except that you specify the names of fields you want to create new references to.

After you use Map, the source and destination lists will contain field refer-ences to (some of) the same LCField objects. No new LCField objects arecreated by this call.

Use this method for field mapping operations when the fieldnames are thesame in source and target, but you need to change the order of the fields oryou wish to exclude some fields. If the field names are not the same insource and target, use MapName.


SyntaxCall destList. Map(baseFieldList, nameList)

Parameters

String. Comma-delimited names of fields from srcList in the new,remapped order.

nameList

LCFieldlist. The fieldlist to map.srcList



Usage NotesThe value of destList can not be Nothing - there must already be an objectthere, preferably one just created with the New method. If the destList listalready contains some fields, the Map method discards them.


Uselsx "*lsxlc"

Sub Initialize


Dim srcCon As New LCConnection ("db2")


Dim fetchLst As New LCFieldList

Dim count As Long

Dim cname As LCField

Dim ccity As LCField

Dim cstate As LCField


srcCon.Database = "Gold"

srcCon.Userid = "JDoe"

srcCon.Password = "xyzzy"

srcCon.Metadata = "customer"

srcCon.Connect

' perform a select and get the records with

' the fields wanted, in our fldLstRecord object

If (srcCon.Select (Nothing, 1, fldLst) <> 0) Then

Print "Table contains " & fldLst.FieldCount & " fields."

' now map the fields of interest, in the order needed,

' discarding fields that we're not interested in.

Call fetchLst.Map (fldLst, "ContactName, CompanyCity,CompanyState")

Print "Fetch field list contains " & fetchLst.FieldCount & "fields."


Set cname = fetchLst.GetField (1)

Set ccity = fetchLst.GetField (2)

Set cstate = fetchLst.GetField (3)

REM fetch a record from the result set

srcCon.MapByName = True ' because the fields in the resultset are not in this order.

Print "Fetching ContactName, CompanyCity, and CompanyStatefields"

While (srcCon.Fetch (fetchLst, 1, 1) > 0)

count = count + 1

Print Cstr(count); Tab(3); cname.Text(0); Tab(28); _

ccity.Text(0); Tab(42); cstate.Text(0)

Wend

End If

End Sub

Example OutputTable contains 8 fields.

Fetch field list contains 3 fields.

Fetching ContactName, CompanyCity, and CompanyState fields:

1 Peter Jay Okend NH

2 Trent Kent Farmtown RI

3 Joan Thomast Lawrens MN

MapName Method for LCFieldlistThis method maps fields with different names. Use this method for fieldmapping operations when the fieldnames are different in the source andtarget. This allows you to change field order and also exclude fields.

No new LCField objects are created by this method. Instead, the destinationlist contains references to the same LCField objects that are in the sourcelist. If you assign a field in one list, the corresponding field in the other listis automatically assigned to the same value because they share the samestorage. This lets you fetch records from one connection and immediatelywrite them out to another connection, without copying values from onefieldlist to another.



SyntaxCall destList.MapName(sourcelist, nameList, mapList)

Parameters

String. A comma separated list of the new field names to place indestList, in the order in which they should appear. It should containthe same number of field names as nameList does, and the fields willbe mapped to the original fields in the corresponding positions innameList. For example, if nameList contains “a, b, c” and mapListcontains “d, e, f”, then field “a” in sourceList corresponds to field“d” in destList, field “b” corresponds to field “e”, and so on.

mapList

String. A comma separated list of the names of the original fieldsfrom sourceList. This need not include all the fields from sourceList,nor do they have to be in the same order as they appear insourceList.

nameList

LCFieldlist. The fieldlist to map fields from.sourcelist



Uselsx "*lsxlc"

Sub Initialize


Dim srcCon As New LCConnection ("db2")

Dim destCon As New LCConnection ("notes")

Dim fetchLst As New LCFieldList

Dim insertLst As New LCFieldList

Dim count As Long

REM set the appropriate properties to connect to the datasources





destCon.Server = "Rainbow"

destCon.Database = "Gold"


destCon.Metadata = "customer"

REM connect to the two data sources

srcCon.Connect

destCon.Connect

srcCon.FieldNames = "ContactName, CompanyCity, CompanyState"

If (srcCon.Select (Nothing, 1, fetchLst) <> 0) Then

' map the result set from the SELECT with the desired namesin the destination.

Call insertLst.MapName (fetchLst, _

"ContactName, CompanyCity, CompanyState", _

"Name, City, State")

' set the property MapbyName on the target.

' this is necessary if the fields in the form are

' (or might be) in different order than they appear indestCon.

destCon.MapByName = True


count = count + destCon.Insert (insertLst, 1, 1)

Wend

Print "Transferred " & count & " records from DB2, to Notes"

Print "Field mapping from (DB2 column name to Notes Fieldname):"

Print " ContactName —> Name"

Print " CompanyCity —> City"

Print " CompanyState —> State"

End If

End Sub

Example OutputTransferred 3 records from DB2, to Notes

Field mapping from (DB2 column name to Notes Field name):

ContactName —> Name

CompanyCity —> City

CompanyState —> State


Merge Method for LCFieldlistThis method merges two fieldlists, copying the names from one and takingthe field objects from another to fill in a third mapping fieldlist. Use thismethod for field mapping operations when you either have a name fieldlistalready built and/or you need to use fieldlist flags.


SyntaxCall destList.Merge(nameFieldList, dataFieldList, mergeFlags)

Parameters

LCMERGEF_KEY — Include fields with the LCFIELDF_KEY flag set.

LCMERGEF_DROP — Ignore fields with the LCFIELDF_NO_DROPflag set.

LCMERGEF_CREATE — Ignore fields with theLCFIELDF_NO_CREATE flag set.

LCMERGEF_REMOVE — Ignore fields with theLCFIELDF_NO_REMOVE flag set.

LCMERGEF_UPDATE — Ignore fields with theLCFIELDF_NO_UPDATE flag set.

LCMERGEF_INSERT — Ignore fields with theLCFIELDF_NO_INSERT flag set.

LCMERGEF_FETCH — Ignore fields with theLCFIELDF_NO_FETCH flag set.

LCMERGEF_NAME_LOSS — Ignore fields in nameFieldlist thathave no corresponding field in dataFieldlist.

LCMERGEF_DATA_LOSS — Ignore fields in DataFieldlist that haveno corresponding field in nameFieldlist.

LCMERGEF_MAP_NAME — Match source and destination fields byfield name instead of by position.

Long. By default, both fieldlists must have the same number of fields,and those fields are mapped by position (first to first, second tosecond, and so on). You can use mergeFlags to alter this defaultbehavior, with zero or more of the following values, ORed together:

mergeFlags

LCFieldlist. Source fieldlist containing the referenced data for thenew fieldlist.

dataFieldlist

LCFieldlist. Source fieldlist containing the field names for the newfieldlist. The data types and values of the fields in the list are ignored.

nameFieldlist



Usage NotesThis data obtained from the dataFieldList consists of references to that list’sLCField objects. The field name isn’t stored in the LCField, so different fieldlists can refer to the same LCField object by different names. This methoddoes not create new LCField objects.

What this method does is essentially no different from what you could dowith the Map method; it just gets its fieldnames from a LCFieldlist objectinstead of from a comma-delimited string. The data values and data typesof fields in the nameFieldList are ignored.

If destList already contains fields, the Merge method will discard them.


Uselsx "*lsxlc"

Sub Initialize


Dim srcCon As New LCConnection ("db2

Dim destCon As New LCConnection ("notes")

Dim fldLst As New LCFieldlist

Dim fetchLst As New LCFieldlist

Dim insertLst As New LCFieldlist

Dim dataLst As New LCFieldlist

Dim nameLst As New LCFieldlist

Dim count As Long

REM set the appropriate properties to connect to the datasources





destCon.Server = "Rainbow"

destCon.Database = "Gold"

destCon.Metadata = "customer"

REM connect to the two data sources

srcCon.Connect


destCon.Connect

REM we can perform a select and get the records with thefields we want

REM in our fldLstRecord object

If (srcCon.Select (Nothing, 1, fldLst) <> 0) Then

REM first we identify the data fields to fetch and orderthem

Call dataLst.Append ("CONTACTNAME", LCTYPE_TEXT)

Call dataLst.Append ("COMPANYCITY", LCTYPE_TEXT)

Call dataLst.Append ("COMPANYSTATE", LCTYPE_TEXT)

Call fetchLst.Merge (dataLst, fldLst, LCMERGEF_MAP_NAME OrLCMERGEF_DATA_LOSS)

REM now we need to do a merge of the fields being fetchedwith the

REM names of the fields being stored

Call nameLst.Append ("Name", LCTYPE_TEXT)

Call nameLst.Append ("City", LCTYPE_TEXT)

Call nameLst.Append ("State", LCTYPE_TEXT)

Call insertLst.Merge (nameLst, fetchLst, 0)

REM set the property Map by Name on both data sources

srcCon.MapByName = True

destCon.MapByName = True

REM fetch a record from the result set


REM now insert the record into the target and fetch thenext,

REM looping until all records have been inserted

count = count + destCon.Insert (insertLst, 1, 1)

Wend

Print "Transferred " & count & " records from DB2, to Notes"

Print "Field mapping from (DB2 column name to Notes Fieldname):"

Print " ContactName —> Name"


Print " CompanyCity —> City"

Print " CompanyState —> State"

End If

End Sub

Example OutputTransferred 3 records from DB2, to Notes

Field mapping from (DB2 column name to Notes Field name):

ContactName —> Name

CompanyCity —> City

CompanyState —> State

MergeVirtual Method for LCFieldlistThis method merges two fieldlists, creating new mapping and virtualfieldlists.

Note This method is provided for backward compatibility. Werecommend that you use either the Map or MapName methods for mergingfieldlists and creating new mappings.


SyntaxCall fldList.MergeVirtual(nameFieldList, dataFieldList, MergeFlags,virtualCode, virtualFieldList)

Parameters

continued

LCMERGEF_MAP_NAME — Match source and destination fieldsby field name instead of by position. (See Comment.)

Long. By default, both fieldlists must have the same number offields, and those fields are mapped by position (first to first, secondto second, an so on). Use MergeFlags to alter this default behavior.Zero or more of the following values are ORed together:

mergeFlags

LCFieldlist. Source fieldlist containing the referenced data for thenew fieldlist.

dataFieldlist

LCFieldlist. Source fieldlist containing the field list of names for thenew fieldlist.

nameFieldlist



LCFieldlist. New fieldlist, containing fields with virtual codesmatching virtualCode.

virtualFieldlist

Long. Connect or Connector code to separate fields with amatching virtual code into virtualFieldList.

virtualCode

LCMERGEF_KEY — Include fields with the LCFIELDF_KEY flagset.

LCMERGEF_DROP — Ignore fields with theLCFIELDF_NO_DROP flag set.

LCMERGEF_CREATE — Ignore fields with theLCFIELDF_NO_CREATE flag set.

LCMERGEF_REMOVE — Ignore fields with theLCFIELDF_NO_REMOVE flag set.

LCMERGEF_UPDATE — Ignore fields with theLCFIELDF_NO_UPDATE flag set.

LCMERGEF_INSERT — Ignore fields with theLCFIELDF_NO_INSERT flag set.

LCMERGEF_FETCH — Ignore fields with theLCFIELDF_NO_FETCH flag set.

LCMERGEF_NAME_LOSS — Ignore fields in nameFieldList thathave no corresponding field in DataFieldlist.

LCMERGEF_DATA_LOSS — Ignore fields in dataFieldList that haveno corresponding field in NameFieldlist.


Remove Method for LCFieldlistThis method removes an existing field from a fieldlist. This does not removea column from associated metadata. See the earlier section entitled “Field-list Merging and Mapping” for related information about how removing oradding columns to a result set affects Fetch, Insert and other operationalmethods.


SyntaxCall fldLstRecord.Remove (index)


Parameters

Long, >= 1. The index position of the field to be removed from thefieldlist.

index



Uselsx "*lsxlc"

Sub Initialize




Dim text As String






REM connect to DB2

connect.Connect




Else

REM fetch the field names

Forall fieldname In FldLst.Names

If (text = "") Then text = fieldname Else text = text + "," + fieldname

End Forall

Print "Before remove: " & text

Call FldLst.Remove (1)

text = ""




End Forall

Print "After remove: " & text

End If

End Sub

Example OutputBefore remove: ACCOUNTMANAGER, CONTACTNAME, COMPANYNAME,COMPANYADDRESS, COMPANYCITY, COMPANYSTATE, COMPANYPHONE

After remove: CONTACTNAME, COMPANYNAME, COMPANYADDRESS,COMPANYCITY, COMPANYSTATE, COMPANYPHONE

Replace Method for LCFieldlistThis method creates a new LCField object and puts it into the fieldlist inplace of an existing field. The data from the old field is not copied into thenew field.


SyntaxSet newField = fldLstRecord.Replace (index, fieldName, dataType)

Parameters

Long. The data type to assign to the new field.dataType

String. The name of the new field.fieldName

Long, >1. The index position of the field to replace.index


Return Value

LCField. The new field.newField

DescriptionValue

Usage NotesReplacing a field in a fieldlist does not affect the metadata associated withthe fieldlist. In the example below, the method is used to change the nameof a field retrieved from an existing table. This change affects the field nameand data type only within this program.


This example works because the connection is set to map fields by position(the default). If the MapByName property were set to True, the Fetch opera-tion would not fill in the renamed field with a value from a field that has adifferent name. See the Fetch method for details.


Uselsx "*lsxlc"

Sub Initialize




Dim text As String






REM connect to DB2

connect.Connect

REM Select all records in the customer table



Else

REM FldLst contains the list of fields in the table, but novalues REM until the Fetch

Call FldLst.Replace (2, "pinky", LCTYPE_TEXT)

text = ""



End Forall


Print "The new list of columns in the '" & connect.Metadata& "' table are: " & text

If connect.Fetch(FldLst) Then

REM if there's any data in the table, display the values in

REM the first row

Dim i As Long

text = ""

For i = 1 To FldLst.Fieldcount

text = text & " " & FldLst.GetName(i) & "=" & _ FldLst.GetField(i).Text(0)

Next

Print text

End If

End If

End Sub

Example OutputThe new list of columns in the 'customer' table are:ACCOUNTMANAGER, pinky, COMPANYNAME, COMPANYADDRESS,COMPANYCITY, COMPANYSTATE, COMPANYPHONE

ACCOUNTMANAGER=Tina Jenson pinky=John DarmainCOMPANYNAME=Darmain Pharmaceuticals COMPANYADDRESS=12 DarmainCircle COMPANYCITY=Topeka COMPANYSTATE=KSCOMPANYPHONE=605-555-2000

SetName Method for LCFieldlistThis method changes the name of a field within a fieldlist.


SyntaxCall fldLstRecord.SetName(index, fieldName)

Parameters

String. The new name to give to this field.fieldName

Long, >=1. The index position of the field.index




Uselsx "*lsxlc"

Sub Initialize




Dim text As String






REM connect to DB2

connect.Connect




Else

REM fetch the field names

Call FldLst.SetName (1, "pinky")

text = ""



End Forall

Print "The new list of columns in the '" & connect.Metadata& "' table are: " & text

End If

End Sub

Example OutputThe new list of columns in the 'customer' table are:

pinky, CONTACTNAME, COMPANYNAME, COMPANYADDRESS, COMPANYCITY,COMPANYSTATE, COMPANYPHONE


Chapter 7LCNumeric Class

This chapter provides information about the Lotus Connectors LCNumericclass methods and properties.

OverviewThe LCNumeric class represents a numeric value containing a precision,scale, and variable number of digits. Numeric values have a specific preci-sion and scale, and can accommodate very high-precision numbers.

Precision refers to the total number of decimal digits the number can store.Scale tells how many digits follow the decimal point. Or, to be more exact,it’s the base ten exponent by which the number is divided to produce theactual value. For example, a numeric value with a scale of -2 can only storevalues that are multiples of 100.

By default, a new numeric submitted to any other numeric method is initial-ized to a precision of 88 and a scale of 44. During any numeric overflow, themaximum or minimum valid numeric value is assigned in addition to theerror occurring.

The precision and scale of a numeric can only be set when it is first created.



Uselsx "*lsxlc"

Sub Initialize




193


Type NUMERIC Format and ValuesThe following is a list of formats and values for the NUMERIC type.

Maximum Positive Value (LCMAX_NUMERIC_VALUE) = 9.99... e126

Minimum Positive Value (LCMIN_NUMERIC_VALUE) = 1.0e-127

Maximum Scale (LCMAX_NUMERIC_SCALE) = 127

Minimum Scale (LCMIN_NUMERIC_SCALE) = -127

Precision (LCMAX_NUMERIC_PREC) = 88

NUMERIC Formats and Values

LCNumeric Class Properties SummaryThe following table lists the LCNumeric class properties.

Double. Value conversion between Lotus Connectors andLotusScript double. Since an LCNumeric may contain anumber of significantly higher precision than a Double, thevalues will not necessarily be identical.

LCNumeric.Value

String representation.LCNumeric.Text

Long [Read-Only]. Precision and Scale are set when theLCNumeric object is first constructed. See the New methodfor LCNumeric.

LCNumeric.Scale

Long [Read-Only]. Precision and Scale are set when theLCNumeric object is first constructed. See the New methodfor LCNumeric.

LCNumeric.Precision

DescriptionProperty

LCNumeric Class Methods SummaryThe following table lists the LCNumeric class methods.

Subtracts one numeric value from another, producing theresult.

LCNumeric.Subtract

Makes a copy of a numeric value.LCNumeric.Copy

Compares two numeric values returning a valueindicating the relationship between them.

LCNumeric.Compare

Adds two numeric values, producing the sum.LCNumeric.Add

DescriptionMethod


New Method for LCNumericThis is the constructor method for the new LCNumeric class object.

Defined InLCNumeric

SyntaxDim variableName As New LCNumeric(lprecision, scale)

Parameters

Long. Optional. Scale for this object, from -127 to +127. Default ifboth arguments are omitted is LCMAX_NUMERIC_PREC / 2 (44).If a precision is specified, the default scale is zero.

This number specifies the position of the decimal point relative tothe rightmost digit. Zero specifies an integer value. The 1 settingspecifies a value with one digit to the right of the decimal point. The -1 setting specifies a value with a decimal point one place to the right of the final digit stored (an integer multiple of 10).

Regardless of the precision, scale can be any number in the -127 to 127 range.

scale

Long. Optional. Precision for this object, from 0 - 88. Default isLCMAX_NUMERIC_PREC (88). This is the total number of decimaldigits you can store in the object.

precision



Uselsx "*lsxlc"

Sub Initialize

Dim hundreds As New LCNumeric(8, -2)

Dim tens As New LCNumeric(8, -1)

Dim ints As New LCNnumeric(8, 0)

Dim defaultNum As New LCNumeric

hundreds.Value = 4567.89

tens.Value = 4567.89

ints.Value = 4567.89

defaultNum.Value = 4567.89

Chapter 7: LCNumeric Class 195

Print "hundreds=" & hundreds.Text & ", tens=" &tens.Text & ", ints=" & ints.Text & ", defaultNum=" &defaultNum.Text

End Sub

Example Outputhundreds=4500, tens=4560, ints=4567, defaultNum=4567.89

Add Method for LCNumericThis method adds the values of two LCNumeric objects. The total is storedin the current object, overwriting any existing value.

Defined InLCNumeric

SyntaxCall numericTotal.Add(numeric1, numeric2)

Parameters

The second of two values being added.numeric2

The first of two values being added.numeric1


Usage NotesThe numericTotal must have been initialized prior to the call, for example itcannot be Nothing.

This method is also useful if numericTotal is the same as one of thearguments, as in the following example statement:

runningTotal.Add(runningTotal, rowAmount)


Uselsx "*lsxlc"

Sub Initialize

Dim num1 As New LCNumeric


Dim sum As New LCNumeric

num1.Value = 12345.6789


num2.Value = 12345.6789

Call sum.Add (Num1, Num2)

Print "The sum of the two numbers is " & sum.Text

End Sub

Example OutputThe sum of the two numbers is 24691.3578.

Compare Method for LCNumericThis method compares two LCNumeric objects.

Defined InLCNumeric

Syntaxresult = numericFirst.Compare(numericSecond)

Parameters

The base value to which to compare another value.numericSecond


Return Value

Result = 0 — numericFirst is equal to numericSecond.

Result < 0 (negative) — numericFirst is less thannumericSecond.

Result > 0 (positive) — numericFirst is greater thannumericSecond.

Long. Result of the comparison:result

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize



Dim diff As Long

num1.Value = 123.456789


num2.Value = 123

diff = num1.Compare (num2)

If (diff = 0) Then

Print "The first number is the same as the second."

Elseif (diff > 0) Then

Print "The first number is greater than the second."

Else

Print "The first number is less than the second."

End If

End Sub

Example OutputThe first number is greater than the second.

Copy Method for LCNumericThis method makes a copy of one LCNumeric, creating a new LCNumericobject.

Defined InLCNumeric

SyntaxSet newNumeric = srcFirst.Copy

Parameters

LCNumeric. The LCNumeric object that you want to copy.srcNumeric


Return Value

LCNumeric. The copy of the srcNumeric object.newNumeric

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize



Dim num2 As LCNumeric

num1.Value = 12345.6789

Set num2 = num1.Copy

Print "The copy has a value of " & num2.Text

End Sub

Example OutputThe copy has a value of 12345.6789.

Subtract Method for LCNumericThis method subtracts the value of one LCNumeric object from the value ofanother LCNumeric object , storing the result in the current object.

Defined InLCNumeric

SyntaxCall numericThird.Subtract(numericFirst, numericSecond)

Parameters

The value to subtract from numericFirst.numericSecond

The initial value from which to subtract numericSecond.numericFirst


Usage NotesThe numericThird must have been initialized prior to the call, for example itcannot be Nothing.

This method is also useful if numericThird is the same as one of thearguments, as in the following example statement:

remainingAmt.Subtract(remainingAmt, rowAmount)


Uselsx "*lsxlc"

Sub Initialize



Dim diff As New LCNumeric


num1.Value = 98765.4321

num2.Value = 12345.6789

Call diff.Subtract (Num1, Num2)

Print "The difference of the two numbers is " & diff.Text

End Sub

Example OutputThe difference of the two numbers is 86419.7532.


Chapter 8LCSession Class

This chapter provides information about Lotus Connectors LCSession classmethods and properties.

OverviewThe LCSession class represents the Lotus Connectors environment of thecurrent script, providing access to the available Connectors and Metacon-nectors, as well as the current error status. The status property and methodsare useful when writing error handling code and reporting errors as textmessages.

This chapter describes the LCSession class as it used in standard LCprogramming. The LCSession class provides additional methods andproperties, and has a different constructor, when it is used from an agentcalled by an LEI Scripted Activity. See Appendix E for details.

LCSession Class Properties SummaryAll sessions have a set of predefined properties with values that can beassigned and retrieved. All properties are represented by both an integervalue (called a property token) and a name.

Boolean. When set to FALSE (default), subsequentlycreated connections are not pooled when theconnection object is destroyed. Setting this propertyto TRUE enables connection pooling. For moreinformation about Connection Pooling, refer to theIntroduction in this manual.

LCSession.ConnectionPooling

Status of an LCSession. Zero, or LCSUCCESS,indicates no error. A non-zero value (representedby an LCFAIL_XXX constant) indicates an errorstate.

LCSession.Status

DescriptionProperty

LEI users can use the following additional predefined properties. SeeAppendix E for more information.

201

Long. Error code (LCFAIL_XXXconstant) to ignore. When thiserror is generated, it is ignored. Set to LCSUCCESS to clear thisproperty.

“IgnoreError”LCTOKEN_IGNORE_ERROR

String. Lotus Connector characterset indicator.

“CharacterSet”LCTOKEN_CHARACTER_SET

Stream format constant for textdata passed between the connectorand the external system. Thisproperty is generally read-only.

“TextFormat”LCTOKEN_TEXT_FORMAT

Long. Error code (LCFAIL_XXXconstant) to treat as an event.When this error is generated, it isdowngraded to an informationalevent. Set to LCSUCCESS to clearthis property.

“EventError”LCTOKEN_EVENT_ERROR

String. Session name.“Name”LCTOKEN_NAME

DescriptionNameProperty

Session properties may also be accessed by name. For example, the follow-ing line of script retrieves the session name for a scripted agent:

myName$ = session.Name

Note DECS users can also access the property tokens using the aboveapproach.

LCSession Class Methods SummaryThis section lists the methods that are available to both DECS and LEI users.

There are several additional LCSession methods available only to LEI users.See Appendix E for detailed information.

continued

List through all installed connectors available forLotusScript Extension for Lotus Connectors.

LCSession.ListConnector

Obtain the error text string corresponding to astatus code.

LCSession.GetStatusText

Obtain the current Session status.LCSession.GetStatus

Clear the Session status, putting the Session in anon-error state.

LCSession.ClearStatus

DescriptionMethod


Suspends script execution for a specified period oftime.

LCSession.Sleep

Determines if a specified metaconnector isavailable.

LCSession.LookupMetaConnector

Determines if a specified connector is available.LCSession.LookupConnector

List through all installed metaconnectors availablefor a LotusScript Extension for Lotus Connectorsinstallation.

LCSession.ListMetaConnector

DescriptionMethod

New Method for LCSessionThis is the constructor method for the LCSession object.

Multiple LCSession objects may be created within a script. All LCSessionobjects within a single script execution share the same status information.

In a normal LC application, this method accepts no arguments and you donot need to declare an LCSession object unless you wish to. However, whenused in an agent called by an LEI Scripted Activity, you must have anLCSession object and a different syntax applies. Refer to Appendix E fordetails.

Defined InLCSession

SyntaxDim variableName As New LCSession


Uselsx "*lsxlc"

Sub Initialize

Dim Session as New LCSession

ClearStatus Method for LCSessionThis method resets or clears the LCSession status after an error.

Defined InLCSession

Chapter 8: LCSession Class 203

SyntaxthisSession.ClearStatus()


Uselsx "*lsxlc"

Sub Initialize


REM Ignore errors

On Error Resume Next

REM purposely generate a Lotus Connector error

session.ListConnector (23)

Print "The current status code is #" & Cstr (session.Status)

session.ClearStatus

Print "The new status code is #" & Cstr (session.Status)

End Sub

Example OutputThe current status code is #12292.

The new status code is #0.

GetStatus Method for LCSessionThis method retrieves the current status value of a session.

Defined InLCSession

SyntaxCall thisSession.GetStatus (statusText, externalCode, externalText)

Parameters

String, output, optional. Any external message text associatedwith an external code.

externalText

Long, output, optional. Any external error codes. Long.externalCode

String, output, optional. Lotus Connector status message.statusText

DescriptionValue



Uselsx "*lsxlc"

Sub Initialize

On Error Goto handler




src.UserID = "JDoe"

REM deliberate bad password


src.Connect

Print "Connected to DB2."

End

handler:

If (session.Status <> LCSUCCESS) Then

Dim text As String

Dim extcode As Long

Dim exttext As String

Call session.GetStatus (text, extcode, exttext)

If (session.Status = LCFAIL_EXTERNAL) Then

Print "DB2 message: " & exttext & " code #" & Cstr(extcode)

Else

Print "Connector message: " & text

End If

Else

Print Error$

End If

End

End Sub


Example OutputDB2 message: [IBM][CLI Driver] SQL1403N The username and/orpassword supplied is incorrect. SQLSTATE=08004 code #-1403

GetStatusText Method for LCSessionThis method returns the message text corresponding to an LCStatus code.

Defined InLCSession

Syntaxmessage = thisSession.GetStatusText(errorCode)

Parameters

Long, output, optional. The error code for which to return themessage text. The default is the current status code.

errorCode

DescriptionValue

Return Values

A text string representation of the status.message

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize


On Error Goto trap

REM Purposely generate a Lotus Connector error.

session.ListConnector (23)

Print "No error encountered"

Exit Sub

trap:

If (session.Status <> LCSUCCESS) Then

Print session.GetStatusText

Else

Print "No error exists."


End If

Exit Sub

End Sub

Example OutputError: Invalid List direction

ListConnector Method for LCSessionThis method lists through all valid connectors for a Lotus Extension forLotus Connectors installation.

The identifyFlagList and identifyNameList parameters provide the ability toobtain information from a Lotus Connector about its supported functional-ity and naming used by the external system.

Defined InLCSession

SyntaxCall thisSession.ListConnector(firstOrNext, connectorName, connectorCode,identifyFlagList, identifyNameList)

Parameters

continued

LCIDFLAG_INDEX_CONNECTOR — Connector flagsLCIDENTIFYF_XXX

Stream, output, optional. The identifyFlagList is set to a stream offormat number list (LCSTREAMFMT_NUMBER_LIST), whichwill contain a series of flags from the connector. Use theNumberListGetValue method of LCStream to retrieve individualflag values as required. The specific flags to retrieve are indicatedby the index in the number list. Use the following constants torepresent a particular set of flags (default is Nothing):

identifyFlagList

String, output, optional. The assigned Connector code.connectorCode

String, output, optional. String representation of the Connectorname.

connectorName

LCLIST_NEXT — Return information about the next Connector.

LCLIST_FIRST — Return information about the first Connector.

Long constant indicating whether to return the first or nextConnector property.

firstOrNext

DescriptionValue


continued

LCIDENTIFYF_DISABLE_WRITEBACK — (Metaconnector only)The use of this metaconnector does not allow writeback resultsets.

LCIDENTIFYF_SRVDB_CAT_CONNECT — Databaseconnection is required for server and/or database browsing.

LCIDENTIFYF_SQL — SQL is the back-end-supported syntax.

LCIDENTIFYF_MULTI_DIMENSION — Multi-dimensionalresult sets are supported (nested fieldlists).

LCIDENTIFYF_MULTI_VALUE — Multi-value types (Binarystream formats for text, number, and datetime lists) are fullysupported by the external system.

LCIDENTIFYF_SCROLLING — Scrolling result sets are available(currently not supported by any connectors).

LCIDENTIFYF_WRITEBACKWriteback functionality isavailable.

LCIDENTIFYF_SINGLE_METADATA — All data is representedby a single metadata (for example, the File connector has onlyone metadata description).

LCIDENTIFYF_ARRAY_WRITE — Array writes (more efficienthandling of RecordCount > 1 for Insert, Update, and/or Removemethods) are supported.

LCIDENTIFYF_ARRAY_READ — Array reads (more efficienthandling of RecordCount > 1 for Fetch method) are supported.

LCIDENTIFYF_SINGLE_THREAD — Connector is not threadsafe. The LSX LC will properly serialize access to this connectorto avoid threading problems.

Supported Connector flags:

The following are the valid flag values. Each flag set is composedof zero or more of the corresponding flags ORed together:

LCIDFLAG_INDEX_OBJECT_DROP — Support objects forLCConnection.Catalog method LCOBJIDENTF_XXX

LCIDFLAG_INDEX_OBJECT_CREATE — Support objects forLCConnection.Catalog method LCOBJIDENTF_XXX

LCIDFLAG_INDEX_OBJECT_CATALOG — Support objects forLCConnection.Catalog method LCOBJIDENTF_XXX

LCIDFLAG_INDEX_ACTION — Support actions forLCConnection.Action method LCACTIDENTF_XXX

DescriptionValue


continued

LCIDNAME_INDEX_DATABASE — Name for database objectsin this external system.

LCIDNAME_INDEX_SERVER — Name for server objects in thisexternal system.

Stream, output, optional. The identifyNameList is set to a stream offormat text list (LCSTREAMFMT_TEXT_LIST), which willcontain a series of names used by the connector’s externalsystem. This can be used to customize the presentation of optionsfor a specific connector (for example, metadata is named Formfor Notes, and Table for DB2). Use the TextListGetValue methodof LCStream to retrieve individual names as required. Thespecific name to retrieve is indicated by the index in the text list.Use the following constants to represent a particular name(default is Nothing):

identifyNameList

LCOBJIDENTF_ALT_FIELD — The method supports alternatemetadata field objects.

LCOBJIDENTF_ALT_METADATA — The method supportsalternate metadata objects.

LCOBJIDENTF_PARAMETER — The method supportsparameter objects.

LCOBJIDENTF_FIELD — The method supports field objects.

LCOBJIDENTF_INDEX — The method supports index objects.

LCOBJIDENTF_PROCEDURE — The method supportsprocedure objects.

LCOBJIDENTF_METADATA — The method supports metadataobjects.

LCOBJIDENTF_DATABASE — The method supports databaseobjects.

LCOBJIDENTF_SERVER — The method supports server objects.

Supported object flags:

LCACTIDENTF_WAIT — Wait action is supported.

LCACTIDENTF_CLEAR — Clear action is supported.

LCACTIDENTF_ROLLBACK — Rollback action is supported.

LCACTIDENTF_COMMIT — Commit action is supported.

LCACTIDENTF_TRUNCATE — Truncate action is supported.

LCACTIDENTF_RESET — Reset action is supported.

Supported action flags:

DescriptionValue


LCIDNAME_INDEX_ALT_FIELD — Name for alternatemetadata fields in this external system.

LCIDNAME_INDEX_ALT_METADATA — Name for alternatemetadata objects in this external system.

LCIDNAME_INDEX_PARAMETER — Name for procedureparameters in this external system.

LCIDNAME_INDEX_FIELD — Name for metadata fields in thisexternal system.

LCIDNAME_INDEX_INDEX — Name for index objects in thisexternal system.

LCIDNAME_INDEX_PROCEDURE — Name for procedureobjects in this external system.

LCIDNAME_INDEX_METADATA — Name for metadataobjects in this external system.

LCIDNAME_INDEX_PASSWORD — Name for password objectsin this external system.

LCIDNAME_INDEX_USERID — Name for user ID objects in thisexternal system.

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize


Dim conName As String

Dim text As String

REM List the connectors available.

REM The parameters for connector code, identity flags, and

REM identity names are optional and omitted in this example.

Call session.ListConnector(LCLIST_FIRST, conName)

text = conName

While session.ListConnector(LCLIST_NEXT, conName)

text = text + ", " + conName

Wend

Print "The usable Connectors are " & text.


End Sub

Example OutputThe usable Connectors are db2, notes, odbc2, oracle, sybase.

ListMetaconnector Method for LCSessionThis method lists all valid metaconnectors for a Lotus Connectors installa-tion. Metaconnectors add an extra layer of functionality between the actualdata source and your program, letting you do such things as sort therecords as you read them, or automatically meter accesses. You can readabout metaconnectors in the Lotus Connectors and Connectivity Guide.

Defined InLCSession

SyntaxCall thisSession.ListMetaConnector(list, metaconnectorName, connectorCode,identifyFlagList, identifyNameList)

Parameters

continued



LCStream, output, optional. The identifyFlagList is set to astream-of-format number list (LCSTREAMFMT_NUMBER_LIST), which will contain a series of flags from the connector.Use the NumberListGetValue method of LCStream to retrieveindividual flag values as required. The specific flags toretrieve are indicated by the index in the number list. Use thefollowing constants to represent a particular set of flags:

identifyFlagList

String, output, optional. The code for this metaconnector.connectorCode

String, output, optional. The name of the metaconnector.metaconnectorName

LCLIST_NEXT — Return the next property (or the firstproperty if this is the first call to this function for thisconnection).


Long. Constant indicating whether to return the first or nextproperty:

list

DescriptionValue


continued

LCIDENTIFYF_DISABLE_WRITEBACK — (Metaconnectoronly) The use of this metaconnector does not allow writebackresult sets.


LCIDENTIFYF_SQL — SQL is the backend-supported syntax.

LCIDENTIFYF_MULTI_DIMENSION — Multidimensionalresult sets are supported (nested fieldlists).

LCIDENTIFYF_MULTI_VALUE — Multivalue types (Binarystream formats for text, number, and datetime lists) are fullysupported by the external system.

LCIDENTIFYF_SCROLLING — Scrolling result sets areavailable (currently not supported by any connectors).

LCIDENTIFYF_WRITEBACK — Writeback functionality isavailable.

LCIDENTIFYF_SINGLE_METADATA — All data isrepresented by a single metadata (for example, the FileConnector has only one metadata description).

LCIDENTIFYF_ARRAY_WRITE — Array writes (moreefficient handling of RecordCount > 1 for Insert, Update,and/or Remove methods) are supported.

LCIDENTIFYF_ARRAY_READ — Array reads (more efficienthandling of RecordCount > 1 for Fetch method) aresupported.

LCIDENTIFYF_SINGLE_THREAD — Connector is not threadsafe. The LSX will properly serialize access to this connector toavoid threading problems.


The following are the valid flag values. Each flag set iscomposed of zero or more of the corresponding flags ORedtogether:



SLCIDFLLAG_INDEX_OBJECT_CATALOG — Supportobjects for LCConnection.Catalog methodLCOBJIDENTF_XXX

DescriptionValue


continued

LCIDNAME_INDEX_SERVER — Name for server objects inthis external system.

LCStream, output, optional. The identifyNameList is set to astream of format text list (LCSTREAMFMT_TEXT_LIST),which will contain a series of names used by the connector’sexternal system. This can be used to customize thepresentation of options for a specific connector (for example,metadata is named Form for Notes, and Table for DB2). Usethe TextListGetValue method of LCStream to retrieveindividual names as required. The specific name to retrieve isindicated by the index in the text list. Use the followingconstants to represent a particular name (default is Nothing):

identifyNameList

LCOBJIDENTF_ALT_FIELD — The method supportsalternate metadata field objects.




LCOBJIDENTF_INDEX — The method supports indexobjects.


LCOBJIDENTF_METADATA — The method supportsmetadata objects.

LCOBJIDENTF_DATABASE — The method supportsdatabase objects.

LCOBJIDENTF_SERVER — The method supports serverobjects.






LCACTIDENTF_TRUNCATE — Truncate action is supported



DescriptionValue



LCIDNAME_INDEX_ALT_METADATA — Name foralternate metadata objects in this external system.


LCIDNAME_INDEX_FIELD — Name for metadata fields inthis external system.




LCIDNAME_INDEX_PASSWORD — Name for passwordobjects in this external system.

LCIDNAME_INDEX_USERID — Name for user ID objects inthis external system.

LCIDNAME_INDEX_DATABASE — Name for databaseobjects in this external system.

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize


Dim conName As String

Dim text As String

REM List the connectors available.

REM The parameters for connector code, identity flags, and

REM identity names are optional and omitted in this example.

Call session.ListMetaConnector(LCLIST_FIRST, conName)

text = conName

While session.ListMetaConnector(LCLIST_NEXT, conName)

text = text + ", " + conName

Wend


Print "The usable metaconnector(s) are " & text & "."

End Sub

Example OutputThe usable metaconnector(s) are broker, collexp, meter, order,tcc, trace.

LookupConnector Method for LCSessionThis method looks up a connector name to determine if it exists and returnsinformation about the connector. Metaconnectors add an extra layer offunctionality between the actual data source and your program, letting youdo such things as sort the records as you read them, or automatically trackaccesses. You can read about metaconnectors in the Lotus Connectors andConnectivity Guide.

Defined InLCSession

SyntaxCall thisSession.LookupConnector(connectorName, connectorCode, identifyFla-gList, identifyNameList)

Parameters

continued

LCIDFLAG_INDEX_OBJECT_CATALOG — Support objects forLCConnection.Catalog method LCOBJIDENTF_XXX



LCStream, output, optional. IdentifyFlagList is set to astream-of-format number list (LCSTREAMFMT_NUMBER_LIST), which will contain a series of flags from the connector.Use the NumberListGetValue method of LCStream to retrieveindividual flag values as required. The specific flags to retrieveare indicated by the index in the number list. Use the followingconstants to represent a particular set of flags:

identifyFlagList

Long, output, optional. The Connector code for this Connector.connectorCode

String. The name of the Connector to look up, for example,oracle.

connectorName

DescriptionValue


continued







LCIDENTIFYF_SQL — SQL is the external system-supportedsyntax.

LCIDENTIFYF_MULTI_DIMENSION — Multidimensionalresult sets are supported (nested fieldlists).

LCIDENTIFYF_MULTI_VALUE — Multivalue types (Binarystream formats for text, number, and datetime lists) are fullysupported by the external system.



LCIDENTIFYF_SINGLE_METADATA — All data is representedby a single metadata (for example, the File connector has onlyone metadata description).

LCIDENTIFYF_ARRAY_WRITE — Array writes (more efficienthandling of RecordCount > 1 for Insert, Update, and/or Removemethods) are supported.

LCIDENTIFYF_ARRAY_READ — Array reads (more efficienthandling of RecordCount > 1 for Fetch method) are supported.






DescriptionValue


continued




LCIDNAME_INDEX_DATABASE — Name for database objectsin this external system.

LCIDNAME_INDEX_SERVER — Name for server objects in thisexternal system.

LCStream, output, optional. The identifyNameList is set to astream of format text list (LCSTREAMFMT_TEXT_LIST), whichwill contain a series of names used by the connector’s externalsystem. This can be used to customize the presentation ofoptions for a specific connector (for example, metadata is namedForm for Notes, and Table for DB2). Use the TextListGetValuemethod of LCStream to retrieve individual names as required.The specific name to retrieve is indicated by the index in the textlist. Use the following constants to represent a particular name(default is Nothing):

identifyNameList

LCOBJIDENTF_ALT_FIELD — The method supports alternatemetadata field objects.






LCOBJIDENTF_METADATA — The method supports metadataobjects.

LCOBJIDENTF_DATABASE — The method supports databaseobjects.

LCOBJIDENTF_SERVER — The method supports server objects.





DescriptionValue



LCIDNAME_INDEX_ALT_METADATA — Name for alternatemetadata objects in this external system.


LCIDNAME_INDEX_FIELD — Name for metadata fields in thisexternal system.



DescriptionValue

Return Values

Boolean. True if a Connector with the specified name isavailable.

flag

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize


REM The optional parameters have been omitted in thisexample.

If (session.LookupConnector ("db2")) Then

Print "DB2 connectivity installed."

Else

Print "DB2 connectivity is not installed."

End If

End Sub

Example OutputDB2 connectivity installed.


LookupMetaConnector Method for LCSessionThis method looks up a metaconnector name to determine if it exists andreturns information about the metaconnector. Metaconnectors add an extralayer of functionality between the actual data source and your program,letting you do such things as sort the records as you read them, orautomatically track accesses. You can read about metaconnectors in theLotus Connectors and Connectivity Guide.

Defined InLCSession

SyntaxCall thisSession.LookupMetaConnector(metaconnectorName, connectorCode,tokenBase, identifyFlagList, identifyNameList)

Parameters

continued



SLCIDFLAG_INDEX_OBJECT_CATALOG — Support objectsfor LCConnection.Catalog method LCOBJIDENTF_XXX

LCIDFLAG_INDEX_ACTION — Support actions forLCConnection.Action methodLCACTIDENTF_XXX


LCStream. Optional. IdentifyFlagList is set to a stream offormat number list (LCSTREAMFMT_NUMBER_LIST), whichwill contain a series of flags from the connector. Use theNumberListGetValue method of LCStream to retrieveindividual flag values as required. The specific flags toretrieve are indicated by the index in the number list. Use thefollowing constants to represent a particular set of flags:

identifyFlagList

Long, output, optional. The token base for this Metaconnector.tokenBase

Long, output, optional. The Connector code of theMetaconnector.

connectorCode

String. The name of the Metaconnector to look up.metaconnectorName

DescriptionValue


continued



LCACTIDENTF_ROLLBACK — Rollback action is supported







LCIDENTIFYF_SQL — SQL is the backend-supported syntax.

LCIDENTIFYF_MULTI_DIMENSION — Multi-dimensionalresult sets are supported (nested fieldlists).

LCIDENTIFYF_MULTI_VALUE — Multi-value types (Binarystream formats for text, number, and datetime lists) are fullysupported by the external system.



LCIDENTIFYF_SINGLE_METADATA — All data isrepresented by a single metadata (for example, the Fileconnector has only one metadata description).

LCIDENTIFYF_ARRAY_WRITE — Array writes (moreefficient handling of RecordCount > 1 for Insert, Update,and/or Remove methods) are supported.

LCIDENTIFYF_ARRAY_READ — Array reads (more efficienthandling of RecordCount > 1 for Fetch method) aresupported.




DescriptionValue


continued





LCIDNAME_INDEX_DATABASE — Name for databaseobjects in this external system.

LCIDNAME_INDEX_SERVER — Name for server objects inthis external system.

LCStream, output, optional. IdentifyNameList is set to astream-of-format text list (LCSTREAMFMT_TEXT_LIST),which will contain a series of names used by the connector’sexternal system. This can be used to customize thepresentation of options for a specific connector (for example,metadata is named Form for Notes, and Table for DB2). Usethe TextListGetValue method of LCStream to retrieveindividual names as required. The specific name to retrieve isindicated by the index in the text list. Use the followingconstants to represent a particular name (default is Nothing).

identifyNameList

LCOBJIDENTF_ALT_FIELD — The method supportsalternate metadata field objects.






LCOBJIDENTF_METADATA — The method supportsmetadata objects.

LCOBJIDENTF_DATABASE — The method supportsdatabase objects.

LCOBJIDENTF_SERVER — The method supports serverobjects.


DescriptionValue



LCIDNAME_INDEX_ALT_METADATA — Name foralternate metadata objects in this external system.


LCIDNAME_INDEX_FIELD — Name for metadata fields inthis external system.


DescriptionValue


Uselsx "*lsxlc"

Sub Initialize


REM The optional parameters have been omitted in thisexample.

If (session.LookupMetaConnector ("order")) Then

Print "The 'order' meta connector is present."

Else

Print "The 'order' metaconnector is not present."

End If

End Sub

Example OutputThe 'order' metaconnector is present.

Sleep Method for LCSessionThis method forces a script execution to sleep for the specified length oftime.

Note LotusScript also has a Sleep statement, but it is only precise to thenearest second. Like the Sleep statement, the Sleep method for LCSessionpauses by repeatedly giving up its processor time section until the specifiedinterval has passed. This allows other processes that need to use the CPU totake advantage of the idle time. It also means that the actual interval may besignificantly longer than specified.


Defined InLCSession

SyntaxCall thisSession.Sleep(milliSeconds)

Parameters

Long. Number of milliseconds to sleep.milliSeconds

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize


Print "The Time is " Cstr(Now).

session.Sleep (5000)

Print "The Time is " Cstr(Now).

End Sub

Example OutputThe Time is 9/8/01 5:23:32 PM.

The Time is 9/8/01 5:23:37 PM.


Chapter 9LCStream Class

This chapter provides information about the Lotus Connector LCStreamclass methods and properties.

OverviewThe LCStream class represents text and binary data types. A stream value is a variable-length list of characters or bytes. Streams come in two basictypes, text and binary, represented by the format of the stream. Specificformat information indicates either the character set (for text) or the binaryformat (for binary).

In addition to specific text formats, there is also the option to designate atext stream as Native, or LCSTREAMFMT_NATIVE, indicating the charac-ters of the stream should be stored in the local platform specific characterset. (Note that the LC LSX uses Unicode for text representation. To create aUnicode stream, use LCSTREAMFMT_UNICODE.) Likewise, in addition tothe basic binary designation (BLOB or LCSTREAMFMT_BLOB), there arefour specialized binary formats:

• LCSTREAMFMT_COMPOSITE — Notes composite (Notes Rich Textformat)

• LCSTREAMFMT_TEXT_LIST — list of LMBCS text strings

• LCSTREAMFMT_NUMBER_LIST — list of double precision floatingpoint values and ranges

• LCSTREAMFMT_DATETIME_LIST — list of LCDatetime values andranges

There are special methods dedicated to working with the three LISTformats.

The maximum storage size of the LIST format stream object is 64K.

225



Uselsx "*lsxlc"

Sub Initialize





LCStream Type TEXT Format and ValuesThe following table shows the format and values for the TEXT type.

LMBCS, Native, or any valid character set (see Appendix D)Formats

Maximum Length 4GBOther

Locale-specific character streamDescription

LCTYPE_TEXTType constant

ValueDescription

LCStream Type BINARY Format and ValuesThe following table show format and values for the BINARY type.

BLOB (unformatted), Notes rich text, Notes text list, Notesnumber list, Notes datetime list

Format

Maximum Length 4GBOther

Optionally formatted byte streamDescription

LCSTREAM structureValue

LCTYPE_BINARYType constant

ValuesDescription


A stream value contains the following information:

Length, in bytes, of data in the data buffer field.Data Length

Stream data format. See Stream Format description below. Ifstream format is not a list type, it is a one-element string or abinary stream.

Stream Format

Zero or more stream flags ORed together. See Stream Flagsdescription below.

Stream Flags

The maximum valid data length for this stream. Any value isvalid, with a value of zero indicating no maximum length.

Maximum Length

DescriptionValue

Stream FlagsThe StreamFlags of a stream determine the behavior of the stream underparticular circumstances:

Stream should not be trimmed. This will notifyConnectors and the Trim method that trimming oftrailing spaces should not be performed for thisstream.

LCSTREAMF_NO_TRIM

Stream is not case sensitive. During text streamcomparisons, a non case sensitive comparison is donewhen either or both streams have this flag set.Without this flag, text-to-text comparisons are casesensitive.

LCSTREAMF_NO_CASE

Stream will automatically truncate assigned andconverted values if the stream cannot accommodatethem. Without this flag, assigning a value too long forthe stream will generate an overflow error.

LCSTREAMF_TRUNCATE

Buffer length is always MaxLength, and the buffer isallocated once and never changed. MaxLength cannotbe zero. Without this flag, the buffer is dynamicallyreallocated to accommodate assigned values (withinMaxLength).

LCSTREAMF_FIXED

DescriptionValue

Stream FormatThe Format of a stream indicates the structure of the stream data. The flagLCSTREAMFMTF_BINARY indicates whether the stream is of a binaryformat or a text format.

Chapter 9: LCStream Class 227

Text formats are represented by either a character set constant or thefollowing special value:

The same as the native character set of the localmachine.

LCSTREAMFMT_NATIVE


For a complete list of supported character sets, see Appendix D.

Binary formats must be one of the following values:

Lotus Notes format Datetime List (multivaluelist of datetime values and ranges)

LCSTREAMFMT_DATETIME_LIST

Lotus Notes format Number List (multivaluelist of number values and ranges)

LCSTREAMFMT_NUMBER_LIST

Lotus Notes format Text List (multivalue listof text values)

LCSTREAMFMT_TEXT_LIST

Lotus Notes format Composite (also known asRich Text or Compound Text)

LCSTREAMFMT_COMPOSITE

Unformatted (BLOB = Binary Large Object)LCSTREAMFMT_BLOB

DescriptionValue

Conversion is supported between stream formats excluding certain conver-sions. If composite is involved in a conversion, it must be the source and thetarget must be BLOB or a text format. In addition, conversion betweennumber list and datetime list is not supported.

Stream BufferThe maximum length of a stream indicates the maximum valid length inbytes for a value assigned to this stream. This can be any value up to 4GB.

A value of zero indicates that the stream has no maximum length.

LCStream PropertiesThe LCStream properties are described in the following table.

continued

Long. The length of the stream data, in bytes. For text streams, thelength in characters may be less, depending on the character set inuse.

Length

Long. The stream data format. This can be assigned, but to convertbetween character sets or formats, use the SetFormat method.

Format

Long. The flags for the stream.Flags

DescriptionValue


Long. The number of range elements in a stream. Valid only forList<Type> formats. [Read-Only]

RangeCount

Long. Number of elements in a stream. Valid only for List<Type>formats. [Read-Only]

Note Datetime and number lists may contain a mixture of singlevalues and range values. ValueCount returns the number of singlevalues.

ValueCount

Variant. An array with starting index 0. You may assign this propertyto set the value. The size of the array and data type of the elementsdepends on the stream format.

wwww TEXT — an array containing a single element of type String.wwww TEXT LIST — an array containing Valuecount elements of type

String.wwww NUMBER LIST — an array containing Valuecount elements of

type Double.wwww DATE/TIME LIST — an array containing Valuecount elements of

type date/time variant.Note Certain methods accept an index parameter to manipulatesingle elements within a list stream. These indexes start at 1, whereasthe Value array starts at zero.

Value

String. The value of the stream object, converted to the LotusScriptstring representation. This property can be assigned to set the valueof the stream. For list types, use comma as a delimiter between listelements.

Note A text list may also contain commas in the values of theindividual elements, so when working with text lists, use the Valueproperty for assignments.

Text

Long. The maximum valid data length for the stream. A value ofzero indicates no maximum [Read-Only].

MaxLength

DescriptionValue

New Method for LCStreamThis is the constructor method for the LCStream class. It creates an emptyLCStream object and optionally assigns initial properties.

Defined InLCStream

SyntaxDim variableName As New LCStream(maxLength, flags, format)


Parameters

Long. Optional. Initial stream format to be assigned to the stream.The default is LCSTREAMFMT_UNICODE.

format

Long. Optional. Flags for this stream. When using the flagLCSTREAMF_FIXED to create a fixed-length stream, the stream’sdata buffer is allocated to be maxLength bytes. Refer to the StreamFlags section for a description of the flags. The default is 0.

streamFlags

Long. Optional. Maximum length that this stream’s data can be. Avalue of zero indicates no maximum, which is not valid with theflag LCSTREAMF_FIXED. Default is 0.

maxLength



Uselsx "*lsxlc"

Sub Initialize

Dim times As New LCStream (0, 0,LCSTREAMFMT_DATETIME_LIST)

Dim fixedMessage As New LCStream(30, LCSTREAMF_TRUNCATE,LCSTREAMFMT_NATIVE)

Dim timeToday As New LCDateTime, timeTomorrow AsLCDatetime

Call timeToday.SetCurrent

Set timeTomorrow = timeToday.Copy( )

Call timeTomorrow.Adjust(LCDTUNIT_DAY, 1)

Call times.DatetimeListInsertValue (1, timeToday)

Call times.DatetimeListInsertValue (2, timeTomorrow)

fixedMessage.Text = "begorrah! he cried, tapping on thebacks of the sleeping tortoises."

' We used the Truncate flag, so the above doesn'tcause an overflow error.

Print {Times = "} & times.Text & {", message = "} &fixedMessage.Text & {"}

End Sub

Example OutputTimes = "03/13/2002 04:16:41.57 PM, 03/14/2002 04:16:41.57PM", message = "begorrah! he cried, tapping on"


Clear Method for LCStreamThis method clears a stream value and properties.

Defined InLCStream

SyntaxlcStream.Clear


Uselsx "*lsxlc"

Sub Initialize

Dim message As New LCStream

message.Text = "Hello World"

Message.Clear

If (Len(message.Text) > 0) Then

Print "the message is " & message.Text

Else

Print "The message is blank."

End If

End Sub

Example OutputThe message is blank.

Append Method for LCStreamThis method appends one stream to another to yield a third LCStreamobject (the destination object) containing the data from both.

The destination object must already have been assigned. The current valueof the destination object, if any, will be overwritten.

Defined InLCStream

SyntaxCall newStream.Append(stream1, stream2)


Parameters

LCStream. The stream to append to stream1. If this stream is adifferent format than stream1, it will first be converted to the formatof stream1.

stream2

LCStream. The stream to which you want to append. The newStreamwill have this stream’s format.

stream1



Option Explicit

Uselsx "*lsxlc"

Sub Initialize

Dim stream1 As New LCStream (64, , LCSTREAMFMT_ASCII)


Dim together As New LCStream (64, , LCSTREAMFMT_ASCII)

stream1.Text = "The quick brown fox "

stream2.Text = "jumped over the lazy dog."

Call together.Append (stream1, stream2)

Print "The combined stream is " & together.Text

End Sub

Example OutputThe combined stream is The quick brown fox jumped over thelazy dog.

Compare Method for LCStreamThis method compares two LCStream objects to determine if they are equal or unequal. If the streams are of different formats, they will first be converted to the same format. If both streams are text, they may beconverted to Unicode for comparison. In a text comparison, if either streamhas the flag LCSTREAMF_NO_CASE set, then a case-insensitive textcomparison will be done.

Defined InLCStream


Syntaxresult = thisStream.Compare(baseStream)

Parameters

LCStream. The stream to which to compare this stream.baseStream


Return Value

Result = 0 — thisStream is equal to baseStream.

Result < 0 (negative) — thisStream is less than baseStream.

Result > 0 (positive) — thisStream is greater than baseStream.

Long. Result of the comparison:result

DescriptionValue


Option Explicit

Uselsx "*lsxlc"

Sub Initialize

Dim stream1 As New LCStream (64, LCSTREAMF_NO_CASE,LCSTREAMFMT_ASCII)


Dim match As Long

stream1.Text = "The quick brown fox"

stream2.Text = "the QuiCK BROWn fOX"

match = stream1.Compare (stream2)

If (match = 0) Then

Print "The first string is the same as the second."

Elseif (match > 0) Then

Print "The first string comes before the second."

Else

Print "The first string comes after the second."

End If

End Sub


Example OutputThe first string is the same as the second.

Convert Method for LCStreamThis method obtains a stream in a particular stream format.

For related information, see the SetFormat method.

Defined InLCStream

SyntaxCall newStream.Convert (srcStream, flags, format)

Parameters

Long. Stream format of the destination data.format

Long. Flags that determine aspects of the conversion. Zero or more ofthe following values, ORed together:

wwww LCCONVERTF_REFERENCE — Allows the destination stream toreference the source stream if they are of the same format.Otherwise, a data copy is always required. See Usage Notes below.

wwww LCCONVERTF_PRESERVE — Preserves the destination streammeta-information (MaxLength and StreamFlags). Otherwise, theyare taken from the source stream.

wwww LCCONVERTF_FORCE_TEXT — Overrides the DECSTranslationsetting of 0 or 1 in the notes.ini file for text translation and forces itto occur between any different text character sets.

flags

LCStream. Stream whose data is to be converted. The srcStream shouldnot be the same object as the newStream.

srcStream


Usage NotesThe use of the flag LCCONVERTF_REFERENCE supports an efficientmethod of obtaining stream data in a particular format. When requesting astream in a specific format and using this flag, if the stream data is alreadyin the same format, no data copying is done. The new stream simply refer-ences the data of the original stream.

When working with a stream that references another stream’s data, do notdelete the original stream until the referencing stream is no longer needed.



Uselsx "*lsxlc"

Sub Initialize

Dim msga As New LCStream (0, 0, LCSTREAMFMT_ASCII)

Dim msgu As New LCStream

msga.Text = "Peter Pan lived in Never Never Land."

Call msgu.Convert (msga, 0, LCSTREAMFMT_UNICODE)

Print "The length of the msg in ASCII is " & msga.Length & "while the length in Unicode is " & msgu.Length

End Sub

Example OutputThe length of the msg in ASCII is 36, while the length inUnicode is 72.

Copy Method for LCStreamThis method copies the value of one LCStream object to another. The actualdata are copied, not just referenced.

Defined InLCStream

SyntaxSet newStream = lcStream.Copy

Parameters

LCStream. Source stream to be copied.lcStream


Return Value

LCStream. The copy of the original stream.newStream

DescriptionValue


Uselsx "*lsxlc"

Sub Initialize



Dim newmsg As LCstream

msg.Text = "Peter Pan"

Set newmsg = msg.Copy

Print "The original msg is " & msg.Text

msg.Text = "Tinkerbell"

Print "The new msg is " & newmsg.Text

End Sub

Example OutputThe original msg is Peter Pan.

The new msg is Peter Pan.

Extract Method for LCStreamThis method creates a stream from part of the data of an existing stream.

Since this method works off of byte counts, it is most useful if you knowyou have single or double byte character sets. It’s not as useful if there’s amix, like LMBCS or CodePage932 (mix of single-byte and double-bytecharacter sets).

Defined InLCStream

SyntaxCall lcStream.Extract (srcStream, offset, length)

Parameters

Long. Length in bytes of the new stream copied from srcStream. If thelength copies more bytes than are available, the copy stops at the endof the source data.

length

Long. Byte position in srcStream of the start of the new stream. If theoffset exceeds the length of the stream data, the new stream is cleared.

offset

LCStream. Stream supplying the data from which the new stream iscreated.

srcStream




Uselsx "*lsxlc"

Sub Initialize

Dim msg As New LCStream (, , LCSTREAMFMT_ASCII)

Dim part As New LCStream

msg.Text = "the quick brown fox jumped over the lazy dog"

Call part.Extract (msg, 11, 5)

Print "The 5 bytes, starting at the 11th byte, is " &part.Text

End Sub

Example OutputThe 5 bytes, starting at the 11th byte, is brown.

Merge Method for LCStreamThis method combines one stream into another, producing a new stream.

Defined InLCStream

SyntaxCall lcStream.Merge(stream1, offset, stream2)

Parameters

LCStream. stream2 is merged into stream1. If stream2 is a differentformat than stream1, it is converted to the format of stream1 beforebeing merged.

stream2

Long. Position in lcStream of the first byte of stream2 - stream2 isinserted into stream1 starting at the position indicated by offset.

Note This is the number of bytes, not the number of characters. Formultibyte character sets (Unicode in particular), the values will differ.

offset

LCStream. stream2 is combined into stream1.stream1




Uselsx "*lsxlc"

Sub Initialize

Dim msg As New LCStream ' Unicode is the default format forstreams

Dim part As New LCStream

Dim newmsg As New LCStream

msg.Text = "The quick brown fox jumped over the lazy dog."

part.Text = "very "

REM counting start with 1 and each character in a Unicodestring is 2 bytes

Call newmsg.Merge (msg, 9, part)

Print "The message, after inserting '" & part.Text"' startingat the 9th byte, is " & newmsg.Text

End Sub

Example OutputThe message, after inserting 'very ' starting at the 9th byte,is The very quick brown fox jumped over the lazy dog.

ResetFormat Method for LCStreamThis method resets the format of an LCStream object, without affecting thedata or other properties. This differs from SetFormat, which changes theformat and also converts the data.

This method may be useful when storing multiple language strings in asingle database and you need to switch the format. A typical case would beWeb browsers accessing an application from different countries and requir-ing different translations of the content. The different translations could bestored in a single database. Since most RDBMS environments do not permitmultiple languages within a single database, the translations could beselected based on a key. The contents would be treated as blobs and theformat would be reset to the correct character set before being passed to theWeb browser.

For related information, see the SetFormat method, which changes theformat and also converts the data.


Defined InLCStream

SyntaxCall lcStream.ResetFormat (format)

Parameters

Long. The new format for the stream object. See the list of streamformats in the section entitled “Stream Formats” earlier in thischapter.

format



Uselsx "*lsxlc"

Sub Initialize

Dim msg As New LCStream (0, 0, LCSTREAMFMT_ASCII)

msg.Text = "Peter Pan lived in Never Never Land."

Print "The length of the msg is " & msg.Length

Call msg.ResetFormat (LCSTREAMFMT_UNICODE)

Print "The length of the msg and its contents have notchanged but the format is now Unicode"

Print "The length of the msg is " & msg.Length

REM msg.Text at this point does not contain a useful value,because

REM the Unicode character set uses two bytes per characterand

REM the message has not been converted to this format.

End Sub

Example OutputThe length of the msg is 36

The length of the msg and its contents have not changed butthe format is now Unicode

The length of the msg is 36


SetFormat Method for LCStreamThis method sets the format for an LCStream object, converting the streamdata if necessary. This method may be more efficient than the Convertmethod, since a second stream is not required.

Defined InLCStream

SyntaxCall lcStream.setFormat (format)

Parameters

Long. The format to which to set the stream object. See the list ofstream formats in the section entitled “Stream Formats” earlier inthis chapter. The data will be converted to this stream format.

format



Uselsx "*lsxlc"

Sub Initialize

Dim msg As New LCStream (0, 0, LCSTREAMFMT_ASCII)

msg.Text = "Peter Pan lived in Never Never Land."

Print "The length of the msg in ASCII is " & msg.Length

Call msg.SetFormat (LCSTREAMFMT_UNICODE)

Print "The length of the msg in Unicode is " & msg.Length

End Sub

Example OutputThe length of the msg in ASCII is 36.

The length of the msg in Unicode is 72.

Trim Method for LCStreamThis method trims trailing spaces from text streams. If the stream is not atext format or if the stream has the flag LCSTREAM_NO_TRIM set, thenthis method will perform no action.


Defined InLCStream

SyntaxlcStream.Trim


Uselsx "*lsxlc"

Sub Initialize


msg.Text = " this has space at the start and the end "

msg.Trim ' trim trailing spaces (not leading ones)

Print "The msg is *" & msg.Text & "*".

End Sub

Example OutputThe msg is * this has space at the start and the end*.

DatetimeListGetRange Method for LCStreamThis method gets a range of values in an LCStream DatetimeList object.

The stream must be in the LCSTREAMFMT_DATETIME_LIST format.

Defined InLCStream

SyntaxCall lcStream.DatetimeListGetRange (index, startDatetime, endDatetime)

Parameters

LCDatetime. Output. The ending datetime of the range.endDatetime

LCDatetime. Output. The starting datetime of the range.startDatetime

Long, in the range 1 to lcStream.Rangecount. Index position of therange in the datetimeList stream.

index



Usage NotesDatetime list streams can contain a mixture of single datetime values anddatetime ranges (as shown in the example). This method scans the list start-ing with the first element, searching for range values and counting them.Once the count reaches index, the range value at that position is returned. Ifthe list contains a mixture, this might not be the indexth value in the list.


Uselsx "*lsxlc"

Sub Initialize

Dim datelist As New LCStream (0, 0,LCSTREAMFMT_DATETIME_LIST)

Dim start As New LCDatetime

Dim finish As New LCDatetime

datelist.Text = "12/25/50,7:00AM,12/31/99 12:59PM,1/1/200012:00AM," & _

"5:00PM - 6:00PM,6:30AM,5/1/96 - 5/31/96"

Call datelist.DatetimeListGetRange (1, start, finish)

Print "The new 1st range is " & start.Text & " - " &finish.Text

End Sub

Example OutputThe new 1st range is 05:00:00 PM - 06:00:00 PM.

DatetimeListGetValue Method for LCStreamThis method retrieves a datetime value from a specified place in aDateTimeList LCStream object.


Defined InLCStream

SyntaxCall lcStream.DatetimeListGetValue(index, datetime)


Parameters

LCDatetime. The datetime value.datetime

Long, in the range 1 to lcStream.Valuecount. Index position of thedatetime value to retrieve.

index


Usage NotesDatetime list streams can contain a mixture of single datetime values anddatetime ranges (as shown in the example). This method scans the list start-ing with the first element, searching for range values and counting them.Once the count reaches index, the range value at that position is returned. If the list contains a mixture, this might not be the indexth value in the list.


Uselsx "*lsxlc"

Sub Initialize


Dim num As New LCDatetime

datelist.Text = "12/25/50,7:00AM,5:00PM - 6:00PM,12/31/9912:59PM," & _

"1/1/2000 12:00AM,6:30AM,5/1/96 - 5/31/96"


"5:00PM - 6:00PM,6:30AM,5/1/96 - 5/31/96"

Call datelist.DatetimeListgetValue (3, num)

Print "The new 3rd datetime is " & num.Text

End Sub

Example OutputThe new 3rd datetime is 12/31/1999 12:59:00 PM.


DatetimeListInsertRange Method for LCStreamThis method inserts a datetime range into a datetime list stream object.


Defined InLCStream

SyntaxCall datetimeNew.DatetimeListInsertRange (index, startDatetime,endDatetime)

Parameters

LCDatetime. The second datetime value for the range.endDatetime

LCDatetime. The first datetime value for the range.startDatetime

Long, in the range 1 to lcStream.Rangecount + 1. The position atwhich to insert the value(s).

index




Uselsx "*lsxlc"

Sub Initialize


Dim start As New LCDatetime

Dim finish As New LCDatetime

start.Text = "8/6/1941"

finish.Text = "7/1/1997"

datelist.Text = "12/25/50, 7:00AM, 12/31/99 12:59PM, 1/1/2000 12:00AM, 5:00PM - 6:00PM, 6:30AM, 5/1/96 - 5/31/96"

Call datelist.DatetimeListInsertRange (2, start, finish)

Print "The new stream is " & datelist.Text

End Sub


Example OutputThe new stream is 12/25/1950, 07:00:00 AM, 12/31/1999 12:59:00PM, 01/01/2000 12:00:00 AM, 06:30:00 AM, 05:00:00 PM -06:00:00 PM, 08/06/1941 - 07/01/1997, 05/01/1996 - 05/31/1996

DatetimeListInsertValue Method for LCStreamThis method inserts a value into a datetime list LCStream object.


Defined InLCStream

SyntaxCall lcStream.DatetimeListInsertValue (index, datetime)

Parameters

LCDatetime. The datetime value to insert.datetime

Long, in the range 1 to lcStream.Valuecount + 1. The index position atwhich to insert the value.

index



Uselsx "*lsxlc"

Sub Initialize


Dim clock As New LCDatetime

clock.SetCurrent


"5:00PM - 6:00PM,6:30AM,5/1/96 - 5/31/96"

Call datelist.DatetimeListInsertValue (3, clock)


End Sub

Example OutputThe new stream is 12/25/1950, 07:00:00 AM, 09/08/199805:22:23.96 PM, 12/31/1999 12:59:00 PM, 01/01/2000 12:00:00AM, 06:30:00 AM, 05:00:00 PM - 06:00:00 PM, 05/01/1996 -05/31/1996


DatetimeListRemoveRange Method for LCStreamThis method removes a range from a datetime list LCStream object.


Defined InLCStream

SyntaxCall lcStream.DatetimeListRemoveRange (index)

Parameters

Long , in the range 1 to lcStream.Rangecount. The position of thevalue to remove.

index




Uselsx "*lsxlc"

Sub Initialize



"5:00PM - 6:00PM,6:30AM,5/1/96 - 5/31/96"

Call datelist.DatetimeListRemoveRange (2)


End Sub

Example OutputThe new stream is 12/25/1950, 07:00:00 AM, 12/31/1999 12:59:00 PM, 01/01/2000 12:00:00 AM, 06:30:00 AM, 05:00:00 PM- 06:00:00 PM


DatetimeListRemoveValue Method for LCStreamThis method removes a value from a datetime list LCStream object.


Defined InLCStream

SyntaxCall lcStream.DatetimeListRemoveValue(index)

Parameters

Long, in the range 1 to lcStream.Valuecount. The index position atwhich to insert the value.

index

DescriptionValue



Uselsx "*lsxlc"

Sub Initialize



"5:00PM - 6:00PM,6:30AM,5/1/96 - 5/31/96"

Call datelist.DatetimeListRemoveValue (3)


End Sub

Example OutputThe new stream is 12/25/1950, 07:00:00 AM, 01/01/2000 12:00:00AM, 06:30:00 AM, 05:00:00 PM - 06:00:00 PM, 05/01/1996 -05/31/1996


NumberListGetRange Method for LCStreamThis method selects a particular range from a number list LCStream object.

The stream must be in the LCSTREAMFMT_NUMBER_LIST format.

Defined InLCStream

SyntaxCall lcStream.NumberListGetRange (index, startNumber, endNumber)

Parameters

Double. Output. The second number value for the range.endNumber

Double. Output. The first number value for the range.startNumber

Long , in the range 1 to lcStream.Rangecount. The position of therange to select.

index


Usage NotesNumber list streams can contain a mixture of single number values andnumber ranges (as shown in the example). This method scans the list start-ing with the first element, searching for range values and counting them.Once the count reaches index, the range value at that position is returned. Ifthe list contains a mixture, this might not be the indexth value in the list.


Uselsx "*lsxlc"

Sub Initialize

Dim numlist As New LCStream (0, 0, LCSTREAMFMT_NUMBER_LIST)

Dim start As Double

Dim finish As Double

numlist.Text = "1.11, 22.2, 33, 4.444, 50-55, 66, 77-79"

Call numlist.NumberListGetRange (1, start, finish)

Print "The new 1st range is " & start & " - " & finish

End Sub

Example OutputThe new 1st range is 50 - 55.


NumberListGetValue Method for LCStreamThis method retrieves a specified value from a number list LCStream object.


Defined InLCStream

SyntaxCall lcStream.NumberListGetValue (index, number)

Parameters

Double. The variable in which to place the value.number

Long, in the range 1 to lcStream.Valuecount. The index position ofthe value to retrieve.

index




Uselsx "*lsxlc"

Sub Initialize


Dim num As Double

numlist.Text = "1.11, 22.2, 33, 4.444, 50-55, 66, 77-79"

Call numlist.NumberListgetValue (3, num)

Print "The new 3rd number is " & num

End Sub

Example OutputThe new 3rd number is 33.


NumberListInsertRange Method for LCStreamThis method inserts a number range into a number list LCStream object.


Defined InLCStream

SyntaxCall lcStream.NumberListInsertRange(index, startNumber, endNumber)

Parameters

Double. The second number of the range.endNumber

Double. The first number of the range.startNumber

Long, in the range 1 to lcStream.Rangecount +1. The index position atwhich to insert the value.

index




Uselsx "*lsxlc"

Sub Initialize


numlist.Text = "1.11, 22.2, 33, 4.444, 50-55, 66, 77-79"

Call numlist.NumberListInsertRange (2, 8.8, 9.9)

Print "The new stream is " & numlist.Text

End Sub

Example OutputThe new stream is 1.11, 22.2, 33, 4.444, 66, 50 - 55, 8.8 -9.9, 77 - 79


NumberListInsertValue Method for LCStreamThis method inserts a value into a number list LCStream object.


Defined InLCStream

SyntaxCall lcStream.NumberListInsertValue(index, number)

Parameters

Double. The value to insert.number

Long, in the range 1 to lcStream.Valuecount +1. The position at whichto insert the value.

index




Uselsx "*lsxlc"

Sub Initialize


numlist.Text = "1.11, 22.2, 33, 4.444, 50-55, 66, 77-79"

Call numlist.NumberListInsertValue (3, 99.99)


End Sub

Example OutputThe new stream is 1.11, 22.2, 99.99, 33, 4.444, 66, 50 - 55,77 - 79


NumberListRemoveRange Method for LCStreamThis method removes a range of numbers as indicated by an index from anumber list LCStream object.


Defined InLCStream

SyntaxCall lcStream.NumberListRemoveRange(index)

Parameters

Long, in the range 1 to lcStream.Rangecount. The position of thevalue to remove.

index

DescriptionValue



Uselsx "*lsxlc"

Sub Initialize


numlist.Text = "1.11, 22.2, 33, 4.444, 50-55, 66, 77-79"

Call numlist.NumberListRemoveRange (2)


End Sub

Example OutputThe new stream is 1.11, 22.2, 33, 4.444, 66, 50 - 55


NumberListRemoveValue Method for LCStreamThis method removes a value at a specified position from a number listLCStream object.


Defined InLCStream

SyntaxCall lcStream.NumberListRemoveValue(index)

Parameters

Long, in the range 1 to lcStream.Valuecount. Theposition of the value to remove.

index




Uselsx "*lsxlc"

Sub Initialize


numlist.Text = "1.11, 22.2, 50-55, 33, 4.444, 66, 77-79"

Call numlist.NumberListRemoveValue (3)


End Sub

Example OutputThe new stream is 1.11, 22.2, 4.444, 66, 50 - 55, 77 - 79


TextListFetch Method for LCStreamThis method fetches a text list from a text list stream object and assigns it toanother stream object.

The stream must be in the LCSTREAMFMT_TEXT_LIST format or anLCTYPE_TEXT value.

Defined InLCStream

SyntaxCall lcStream.TextListFetch(index, format, stream)

Parameters

String, output. The text value at position index in the list.value

Long, in the range 1 to lcStream.Valuecount. The index position of thevalue to fetch. If the index is one, this method will accept a textstream as a single-entry text list.

index



Uselsx "*lsxlc"

Sub Initialize

Dim textlist As New LCStream (0, 0, LCSTREAMFMT_TEXT_LIST)

Dim text As String

textlist.text = "red, orange, yellow, green, blue, indigo,violet"

Call textlist.TextListFetch (3, text)

Print "The 3rd string in the text list is " & text

End Sub

Example OutputThe 3rd string in the text list is yellow


TextListInsert Method for LCStreamThis method inserts text or a text list into a text list LCStream object.

The stream must be in the LCSTREAMFMT_TEXT_LIST format.

Defined InLCStream

SyntaxCall lcStream.TextListInsert(index, stream)

Parameters

String. The text string to insert.stream

Long, in the range 1 to lcStream.Valuecount + 1. The position atwhich to insert the text string.

index



Uselsx "*lsxlc"

Sub Initialize


textlist.text = "red, orange, yellow, green, blue, indigo,violet"

Call textlist.TextListInsert (3, "black")

Print "The new value of the text list is " & textlist.text

End Sub

Example OutputThe new value of the text list is red, orange, black, yellow,green, blue, indigo, violet

TextListRemove Method for LCStreamThis method removes a string from a text list LCStream object.

The stream must be in the LCSTREAMFMT_TEXT_LIST format.

Defined InLCStream


SyntaxCall lcStream.TextListRemove(index)

Parameters

Long, in the range 1 to lcStream.Valuecount. The position of thetext list element to remove.

index



Uselsx "*lsxlc"

Sub Initialize


textlist.text = "red, orange, yellow, green, blue, indigo,violet."

Call textlist.TextListRemove (3)

Print "The new value of the text list is " & textlist.text

End Sub

Example OutputThe new value of the text list is red, orange, green, blue,indigo, violet.


Appendix AError Messages

This appendix provides information about error messages.

IntroductionEach entry provides the error code in both hexadecimal and decimal format(hexadecimal is first, decimal second), the LCSTATUS constant (usablefrom any language), the error text for the message, and then a description of the error.

Parameterized elements of a message are indicated in all uppercase, and are replaced at error-generation time with the relevant value. Optionalelements of a message are enclosed in square brackets, and are includedonly if the contained parameters have values provided.

Error Message FormatThis section provides information about how to interpret the LC LSX errormessages. It describes the format of each error and what each component ofthe error message indicates.

Example Error MessageA sample error message is shown below:

Error: Two Fields cannot have the same name within a Form, ConnectorNotes, Method -Create [Metadata]- (0x80000803)

Error Message ComponentsThe error message shown above can be broken down into the followingcomponents:

“Error: ” — This prefix is added to any error. It is not included for ‘events’(informational messages).

257

“Two Fields cannot have the same name within a Form” — This is thespecific error message. This can be either an LC error message, or an external error message. In this case, it is an external error message.

“Connector ‘Notes” — This is the connector which generated the errormessage. This element is included only when the error occurs inside anLCConnection method; it is skipped otherwise.

“Method-Create [Metadata]” — This is the LCConnection method in whichthe error occurred. It is only generated when the connector is included inthe error message. It indicates the LCConnection method generating theerror. In addition, for methods which accept a parameter indicating anobject type (Create, Drop, or Catalog) or action type (Action), the object oraction type is included in square brackets for more information.

“(0x80000803)” — This is the external error code generated by the externalsystem. It is only included when the actual error was LCFAIL_EXTERNAL,which is true whenever the error is not an LC LSX error. When the value isbetween -65536 and 65536, the decimal value is used. When it is lower orhigher, the hex value is used.

Format of ErrorsErrors appear in the following format:

• Hex Value

• Decimal Value

• Constant

• Text

• Description

General ErrorsTwo general LEI error messages are shown below:

&H101 257 LCFAIL_PROGRAM Lotus Connectorprogram failure. Contact Lotus support.

An unexpected internal error has occurred. Collect all information regard-ing events leading up to this error and contact Lotus technical support.

&H102 258 LCFAIL_MEMORY Unable to allocatememory.


An attempt to allocate program memory failed. There are a few possiblecauses of this error. First check system resources to determine if yoursystem is low on memory. If it is, then more memory is needed on yoursystem to support the processing tasks occurring. If your system still hassignificant memory available, then a request for a very large amount ofmemory was made. Certain operations are memory intensive, such asloading extremely large data values, requesting too many records at onetime, or using a Metaconnector such as the Order Metaconnector (whichloads the entire result set at once) against a very large result set.

Connector ErrorsSeveral connector-related error messages are shown below:

&H3001 12289 LCFAIL_UNAVAILABLE Requestedfunctionality is not available

A request for unsupported functionality was made. This can occur whenusing a connector which doesn’t support a specific operation (for example,a connector may not support the Create method), or when an LC APImethod doesn’t support a specific request (see the documentation for themethod in question).

&H3002 12290 LCFAIL_END_OF_DATA The last data valuehas been retrieved

The last element has been retrieved from a list of available data values. Thisis a normal return code from any operation which is called to iteratethrough data values (for example, LCConnection.Fetch,LCConnect.ListProperty, LCFieldlist.List, etc…). It does not indicate a fatalerror, and is usually part of a normal flow of operations.

&H3003 12291 LCFAIL_INVALID_INDEX Cannot locate listelement

A request made of a multivalue object provided an invalid index. Thisnormally occurs when accessing a list entity (for example, a field in a field-list or a text entry in a text list) where the index provided is greater than themaximum valid index for that object. Note that all indices are one-based, sothat an object with three elements has valid index values of 1, 2, and 3.

&H3004 12292 LCFAIL_INVALID_LIST Invalid Listdirection

When using a method which iterates through values, an LCLIST parameterindicates the listing method (for example, start at the first, or return the next

Appendix A: Error Messages 259

entry). Either an invalid listing direction was provided, or a valid directionwas provided, but is not supported in the current context.

&H3005 12293 LCFAIL_INVALID_CONVERT Invalid conversion

An unsupported data conversion was attempted. Conversion is validbetween members of the same data type “class” (numbers, streams, anddatetimes) as well as to and from text. Conversions between data typeclasses where one type is not text (for example, converting between adatetime and a currency) will return this error. In addition, conversion to orfrom a binary stream formats is generally only valid when one type is textor a binary BLOB format.

&H3006 12294 LCFAIL_INVALID_TEXT_LIST This operationrequires a valid text list

An action that operates on a text list stream (a binary stream of formatLCSTREAMFMT_TEXT_LIST) was provided a stream of a different formator with an invalid structure. Ensure that the stream data is a properlyformatted text list.

&H3007 12295 LCFAIL_INVALID_NUMBER_LIST This opera-tion requires a valid number list

An action that operates on a number list stream (a binary stream of formatLCSTREAMFMT_NUMBER_LIST) was provided a stream of a differentformat or with an invalid structure. Ensure that the stream data is aproperly formatted number list.

&H3008 12296 LCFAIL_INVALID_DATETIME_LIST This opera-tion requires a valid datetime list

An action that operates on a datetime list stream (a binary stream of formatLCSTREAMFMT_DATETIME_LIST) was provided a stream of a differentformat or with an invalid structure. Ensure that the stream data is aproperly formatted datetime list.

&H3009 12297 LCFAIL_ZERO_INDEX All index valuesare one-based — an index of zero is not valid

A request made of a multivalue object provided an index of zero. All objectsand methods which support an index reference (for example, fieldlists andtext lists) use one-based indices, zero is never a valid index value.

&H300A 12298 LCFAIL_ZERO_COUNT This operationrequires a non-zero count

A parameter indicating a count was given a value of zero when it is notvalid. Zero counts are only valid in specific cases — check the methoddocumentation for more information.


&H300B 12299 LCFAIL_ZERO_OFFSET All offset valuesare one-based — an offset of zero is not valid.

A request made of a multivalue object provided an offset of zero. Allmethods which support an offset parameter (for example, LCStream.Merge)use one-based offsets, zero is never a valid offset value.

&H300C 12300 LCFAIL_ZERO_FORMAT This operationrequires a non-zero Stream Format

A parameter indicating a stream format was given a value of zero when it isnot valid. Zero stream formats are only valid in specific cases; check themethod documentation for more information. A list of valid stream formatsis provided in your documentation.

&H300D 12301 LCFAIL_NULL_BUFFER A NULL bufferwas provided when one was required

A method with a required buffer parameter was provided no value where avalid buffer was required. Check the method documentation for moreinformation.

&H300E 12302 LCFAIL_NULL_RESULT A return parame-ter is required, but none was provided

A method with a required output parameter was provided no value wherea valid parameter was required. Check the method documentation for moreinformation.

&H300F 12303 LCFAIL_FIXED_LENGTH A fixed-lengthstream requires a non-zero length

When requesting a fixed-length stream (with the stream flagLCSTREAMF_FIXED), a maximum length property with a non-zero valuemust be provided via LCStream.Create.

&H3010 12304 LCFAIL_INVALID_FLAGS The supplied flagsare invalid, possibly due to a conflict

Bitwise flags provided for an operation are not valid; either invalid flagswere specified, or conflicting flags were provided. Check the object ormethod documentation for more information on valid flags.

&H3011 12305 LCFAIL_TEXT_TRANSLATE Text translationfailure

Translation between character sets failed. This may be caused by an incor-rect character set indicator or invalid data in the source text. If the problempersists, contact Lotus technical support.

&H3012 12306 LCFAIL_NULL_FIELDNAME A NULL fieldname was provided


A NULL or empty field name was provided when a valid field name wasrequired. Ensure that the field name being provided has at least one charac-ter, and check the method documentation for more information.

&H3013 12307 LCFAIL_INVALID_FIELDLIST Invalid fieldlist

An LCFIELDLIST object handle is either not a valid handle, or is zero.Object handles must be a valid value returned by a method which creates anew fieldlist. Handles are no longer valid once the object is freed.

&H3014 12308 LCFAIL_INVALID_CONNECTION Invalidconnection

An LCCONNECTION object handle is either not a valid handle, or is zero.Object handles must be a valid value returned by a method which creates anew connection. Handles are no longer valid once the object is freed.

&H3015 12309 LCFAIL_EMPTY_FIELDLIST This operationcannot be performed on a fieldlist with no fields

A fieldlist that contains no fields is not valid in this context. To avoid thiserror, ensure that any fields are added to the fieldlist, and check the methoddocumentation for more information.

&H3016 12310 LCFAIL_NAME_FIELDLIST This operationcannot be performed on a name-only fieldlist

A fieldlist created with a record count of zero is not valid in this context.Such fieldlists are intended for name mapping, and cannot contain datavalues. As such, they cannot be used in any situation where data will beread from or written to a fieldlist. To avoid this error, provide a non-zerorecord count when creating the fieldlist.

&H3017 12311 LCFAIL_NATIVE_OVERRIDE Native text formatoverride supplied is not a valid stream format indicator

An override of the native character set was provided in an .INI variable asindicated in the documentation. The character set indicated is not a validcharacter set identifier. Check the documentation for a list of valid characterset strings.

&H3018 12312 LCFAIL_RECORD_INDEX An invalid fieldlistrecord index was encountered

A fieldlist record index is not valid for the relevant fieldlist. This generallyoccurs with LCConnection class methods which accept a fieldlist and arecord index. The index must be at least one (all indices are one-based), andcannot be greater than the number of records that the fieldlist was createdwith.


&H3019 12313 LCFAIL_RECORD_COUNT Request to transfermore records than allocated in fieldlist

A fieldlist record count is not valid for the relevant fieldlist. This generallyoccurs with LCConnection class methods which accept a fieldlist and arecord count. The count plus the record index cannot exceed the number ofrecords that the fieldlist was created with. In addition, a count of zero isonly valid in specific situations. See the method documentation for moreinformation.

&H301A 12314 LCFAIL_LIST_SETUP Fieldlist iterationrequires initial setup

Listing fieldlist in a fieldlist with LCFieldlist.List requires thatLCFieldlist.ListSetup be called first to prepare the iteration.

&H301B 12315 LCFAIL_NO_MERGE_DATA The data fieldlistin a merge cannot be a name-only fieldlist

When using the methods LCFieldlist.Merge or MergeVirtual, the fieldlistprovided as the data fieldlist cannot be a name-only fieldlist. It must becreated with a non-zero record count.

&H301C 12316 LCFAIL_NO_RESULTSET This operationrequires an active result set

A requested LCConnection operation cannot be performed unless theconnection has an active result set. Produce a result set before attemptingthis operation. This error is generally produced by callingLCConnection.Fetch without a previous call to a method which produces aresult set (such as Execute, Select, Call, or Catalog).

&H301D 12317 LCFAIL_NO_WRITEBACK This operationrequires an active writeback result set

A requested LCConnection operation cannot be performed unless theconnection has an active writeback result set. Produce a writeback-enabledresult set before attempting this operation. This error is generally producedby calling LCConnection.Update or Remove with the “Writeback” propertyset, but without a previous call to a method which produces a writebackresult set (such as Execute or Select with the “Writeback” property set). Ifthe result set is produced without the writeback property set, then write-back operations are not supported against that result set.

&H301E 12318 LCFAIL_WRITEBACK_COUNT Writeback opera-tion record counts must be one

When requesting a writeback operation against an LCConnection, only themost recently fetched record is affected, so the record count must be one.


&H301F 12319 LCFAIL_TRANSLATE_INIT Text translationsubsystem initialization failure

The internal character set translation subsystem failed to initialize properly.This is generally due to an improperly installed environment. Check thedocument for installation and platform-specific notes, and contact Lotustechnical support if the problem persists.

&H3020 12320 LCFAIL_TIMEBOMB This time-limitedversion has expired [as of DATE]

This is a time-limited version which expired on the date indicated. A newversion with a later time bomb, or a complete version must be obtainedfrom Lotus.

&H3021 12321 LCFAIL_SESSION_NOT_INIT The Lotus Connec-tor Session must be initialized before performing any operation

The Lotus Connector Session class must be initialized before any other LCobjects can be created or methods used.

&H3022 12322 LCFAIL_CONNECTOR_VERSION IncorrectConnector version

A connector was built with an incompatible version of the Lotus ConnectorToolkit. Contact Lotus or the developer of the connector for an updatedversion.

&H3023 12323 LCFAIL_NOT_CONNECTED This operationrequires a connection to a connector

The LCConnection method called cannot be used on an unconnectedLCConnection. Call the connect method before this operation. In general,any operation which produces a result set or manipulates data or metadatacannot be called before connecting — only getting and setting propertiesmay occur. One exception for some connectors is that a server or databasecatalog result set may be produced and fetched from before connecting.

&H3024 12324 LCFAIL_CONNECTED This operationcannot be performed when there is a valid connection to a connector

The LCConnection operation performed is not valid when the LCConnec-tion is actively connected — the Disconnect method must first be called.This may occur when performing an action which affects the connectionitself, such as using the Drop method on a database.

&H3025 12325 LCFAIL_EXTERNAL <external errortext>


An external database or application accessed by a connector generated anerror. The external error text and code are available with the methodLCSession.GetStatus.

&H3026 12326 LCFAIL_ACTIVE_SUBCONNECTOR Thesub-Connector of a metaconnector can only be set once

Any subconnector property of a metaconnector can only be set once; anyattempt to reset it will generate this error.

&H3027 12327 LCFAIL_TRANSLATE_TABLE No translationtables are available for the character set

A translation table is available for most translations between supportedcharacter sets. This error indicates that the translation table for a specificcharacter set or translation is not available and the character set translationcannot be performed. Often, a similar character set is available and can beused to obtain the same effective translation.

&H3028 12328 LCFAIL_NO_SCROLL This operationrequires an active scrollable result set

Using the LCConnection.Fetch method with a negative record count is onlyvalid when the connector supports scrolling result sets and the active resultset was produced with the “Scrolling” property set. This error is returnedfrom the Fetch method when a negative record count is provided and eitherof these conditions is not met.

&H3029 12329 LCFAIL_BINARY_FORMAT This operationrequires a non-binary Stream Format

Certain LCStream methods are not valid on formatted binary streamformats. This method requires a stream with a text format, or unformattedBLOB binary format. Check the method documentation for moreinformation.

&H302A 12330 LCFAIL_ASYNC_ACTIVE Asynchronousoperation is still active

This error is returned from methods that wait for an asynchronous opera-tion to complete. When the asynchronous operation is still active and anywait period specified passes, this error is returned.

Parameterized Connector ErrorsSeveral connector errors are shown below:

&H3101 12545 LCFAIL_INVALID_METADATAMetadata object[‘METADATA’] does not exist


The value provided for the “Metadata” property is not a valid metadataobject in the external system. The invalid metadata name will generally beprovided. Ensure that a valid value is being provided; common errorsinclude misspellings, incorrect capitalization in case-sensitive systems, andbeing connected to the wrong database.

&H3102 12546 LCFAIL_TYPE_MISMATCH Type mismatch[for field ‘FIELDNAME’] [; Connector: TYPE1] [, External: TYPE2]

Data type mismatch. Implicit data conversion is supported only within adata type “class”: number, stream, or datetime. When mapping isattempted between data types in different classes (for example, INT toTEXT; or DATETIME to NUMERIC), this error is generated. The fieldnameand data types are generally provided in the error text. Ensure that the datatypes being mapped are members of the same data type class.

&H3103 12547 LCFAIL_DUPLICATE Duplicate object[‘NAME’]

For database-specific connectors such as Sybase, Oracle, and DB2, this errorindicates that an object of the same name already exists. Select a differentname for the object. This error can occur when creating an API object or anexternal system object, such as creating a new metadata object where one ofthe same name already exists. Note that if using ODBC, LCFAIL_EXTER-NAL would occur in this scenario instead of LCFAIL_DUPLICATE.

&H3104 12548 LCFAIL_FIELD_COUNT_MISMATCHField countmismatch [; Connector: COUNT1, External: COUNT2]

The number of fields did not match between a connector and an externalsystem. In some cases, this problem can be resolved automatically (forexample, when writing fields to a external system that supports more fieldsthan provided). In other cases, this error will be generated (for example,when writing 5 fields to a external system which supports 3 fields). Toavoid this error, fields can be removed from a fieldlist on a per-operationbasis by using field flags.

&H3105 12549 LCFAIL_KEY_COUNT_MISMATCH Key countmismatch [; Connector: COUNT1, External: COUNT2]

The number of keys did not match two systems. In cases where keys mustbe specified for two systems, the same number of keys must be providedfor both systems.

&H3106 12550 LCFAIL_STAMPFIELD_TYPE Timestamp field[‘FIELDNAME’] must be type Datetime [; Actual: TYPE]

A timestamp field provided for the “StampField” property of a connectormust represent an external field of type datetime. This error is returnedwhen it is a number or stream data type.


&H3107 12551 LCFAIL_FIELD_TYPE Type mismatch forfield [‘FIELDNAME’] used in this context [; Expected: TYPE1 [, Actual:TYPE2]]

Specific functionality requested of a connector requires that a field be of aparticular data type. This error is generated when a specific data type isexpected for a particular field, but an incompatible data type is provided.

&H3108 12552 LCFAIL_MERGE_FIELD Field mappingfailed due to a missing field [‘FIELDNAME’]

When using the methods LCFieldlist.Merge or MergeVirtual, there was amismatch between the fieldlists. Either a field in the namelist had no matchin the data list, or vice-versa. If such a mismatch occurs and the merge flagLCMERGEF_NAME_LOSS or LCMERGEF_DATA_LOSS is not specified toindicate that loss of fields is allowed, then this error is generated. Ensurethat the field indicated in the error has a corresponding field in the otherfieldlist.

&H3109 12553 LCFAIL_MISSING_PROPERTY No value suppliedfor required property [‘PROPERTY’]

The indicated property requires a value for the requested operation, butnone was provided. Supply a valid value for the property. Check thedocumentation for the connector or the method being called (for example,when using the LCConnection.Create method to create an index, theproperty “Index” is required, and if no value was given, this error would begenerated).

&H310A 12554 LCFAIL_PROPERTY_CONFLICTConflicting valuesfor properties [‘PROPERTY1’ and ‘PROPERTY2’]

The values provided for the two indicated properties conflict with oneanother. Check the connector documentation for information regardingconflicting property values for this connector.

&H310B 12555 LCFAIL_INVALID_PROPERTY Invalid property[‘PROPERTY’]

The attempt to get or set the indicated property failed because it is notsupported by the connector. Check the connector documentation for moreinformation on supported properties for this connector.

&H310C 12556 LCFAIL_PROPERTY_VALUE Invalid propertyvalue [for property ’PROPERTY’]

The value provided for the indicated property is not a valid value. Checkthe connector documentation for information on valid property values forthis connector.


&H310D 12557 LCFAIL_INVALID_CHARSET The text formatprovided [‘CHARSET’] is not a valid Lotus connector character set indicator

An attempt to indicate a character set by it’s textual representation faileddue to an invalid string. Check the documentation for a list of supportedcharacter set strings.

&H310E 12558 LCFAIL_READ_ONLY_PROPERTY Cannotchange the value of read-only property [‘PROPERTY’]

The indicated property is read-only for this connector and an attempt to setit’s value was made. For example, the “TextFormat” property of someconnectors cannot be assigned, so will generate this error on any suchattempt.

&H310F 12559 LCFAIL_MISSING_CONNECTORLCXCannot loadConnector LCX Library [‘CONNECTOR’]

The connector library .LCX file could not be loaded. Ensure that a validconnector was specified and that the connector is available on the system. Acommon mistake which produces this error is to not have any client filesinstalled to support the connector. For example, use of the Lotus Connectorfor DB2 requires that a DB2 client product be installed.

&H3110 12560 LCFAIL_INVALID_CONNECTORLCXInvalid Connector LCX Library [‘CONNECTOR’]

The connector library .LCX file was located and loaded, but was not a validconnector. Contact Lotus or the connector vendor for a valid connectorlibrary.

Field-specific Parameterized Connector ErrorsSeveral field-specific parameterized connector errors are shown below:

&H3201 12801 LCFAIL_OVERFLOW Data overflow[infield ‘FIELDNAME’]

A data overflow was encountered when transferring data to or from a field.This error generally occurs when writing data to an external system, andthe data is too large for the target field (for example, writing the text“abcdefg” to a SQL CHAR(5) field). This error can also occur, though, whenreading data into an internal data type and the data cannot be accommo-dated (a number or datetime is out of range, or a stream exceeds themaximum allowed length. This error can be suppressed by assigning thefield flag LCFIELDF_TRUNC_DATA, or selecting the corresponding UIoption to allow data loss on overflow.


&H3202 12802 LCFAIL_PRECISION_LOSS Data precision loss[in field ‘FIELDNAME’]

This error is generated when performing type mapping between internaland external fields when the data types are different, and precision may belost on data transfer. Note that this error indicates that precision will be lostbetween the data types, irrelevant of the actual data (for example, writing aFLOAT values of 3 to an INT field will be considered a precision loss, sinceit checks the data types once at mapping time, rather than the data valuesfor each transfer). This error can be suppressed by assigning the field flagLCFIELDF_TRUNC_PREC, or selecting the corresponding UI option toallow precision loss.

&H3203 12803 LCFAIL_INVALID_INT Invalid integervalue [in field ‘FIELDNAME’]

The indicated field contains an invalid integer value, or an attempt to assignan invalid integer value was made. Ensure that the data source for the fieldwas a valid value and check that the field value is not being destroyed byan incorrect operation or method call.

&H3204 12804 LCFAIL_INVALID_FLOAT Invalid float value[in field ‘FIELDNAME’]

The indicated field contains an invalid floating point value, or an attempt toassign an invalid floating point value was made. Ensure that the datasource for the field was a valid value and check that the field value is notbeing destroyed by an incorrect operation or method call.

&H3205 12805 LCFAIL_INVALID_CURRENCY Invalid currencyvalue [in field ‘FIELDNAME’]

The indicated field contains an invalid currency value, or an attempt toassign an invalid currency value was made. Ensure that the data source forthe field was a valid datetime value within the allowable range of anLCCurrency and check that the field value is not being destroyed by anincorrect operation or method call.

&H3206 12806 LCFAIL_INVALID_NUMERIC Invalid numericvalue [in field ‘FIELDNAME’]

The indicated field contains an invalid numeric value, or an attempt toassign an invalid numeric value was made. Ensure that the data source forthe field was a valid numeric value within the allowable range of anLCNumeric and check that the field value is not being destroyed by anincorrect operation or method call.

&H3207 12807 LCFAIL_INVALID_DATETIME Invalid datetimevalue [in field ‘FIELDNAME’]


The indicated field contains an invalid datetime value, or an attempt toassign an invalid datetime value was made. Ensure that the data source forthe field was a valid datetime value within the allowable range of anLCDatetime, and check that the field value is not being destroyed by anincorrect operation or method call.

&H3208 12808 LCFAIL_INVALID_STREAM Invalid streamvalue [in field ‘FIELDNAME’]

The indicated field contains an invalid stream value, or an attempt to assignan invalid stream value was made. Ensure that the data source for the fieldwas a valid value and check that the field value is not being destroyed byan incorrect operation or method call.

&H3209 12809 LCFAIL_INVALID_FIELD Invalid field[‘FIELDNAME’]

An LCFIELD object handle is either not a valid handle, or is zero. Objecthandles must be a valid value returned by a method which creates a newfield. Handles are no longer valid once the object is freed.

&H320A 12810 LCFAIL_INVALID_TYPE Invalid datatype[for field ’FIELDNAME’]

The data type for the indicated field is an overview data type, or a data typeparameter was provided with an invalid value. This error will generallyonly occur if some sort of corruption exists, but could also be indicative of aversion mismatch between a specific connector and the calling program ortool. Check to ensure that only valid data types of the form LCTYPE_XXXare being used, and if the problem persists, contact Lotus technical support.

&H320B 12811 LCFAIL_INVALID_KEY Invalid key field[‘FIELDNAME’]

The indicated field was provided as a key field, but no such searchable fieldexists in the result set or external system. Two common sources of this errorare misspellings of the key field name or use of a non-searchable field (asdefined by the external systems — check the connector documentation forinformation on data types that cannot be used as keys) as a key. This errorcan also occur when the key field is left out of the result set.

&H320C 12812 LCFAIL_DUPLICATE_KEY Duplicate key field[‘FIELDNAME’]

The indicated field was provided as a key field twice; a single field can onlybe used once as a key. Either remove the second occurrence of the key field,or provide a different field name in its place.

&H320D 12813 LCFAIL_INVALID_STAMPFIELD Invalidtimestamp field [‘FIELDNAME’]


The indicated field was provided as a timestamp field, but no such fieldexists in the result set or external system. This generally occurs because thename of the field was misspelled, or it was not included in the result set.

&H320E 12814 LCFAIL_INVALID_FIELDNAME Field name[‘FIELDNAME’] is not valid in this context

The indicated field name is not valid for the context in which it was used.For example, when attempting to create a new metadata object in an exter-nal system, this error may be generated if any of the fields are not validfield names for that external system.

&H320F 12815 LCFAIL_VIRTUAL_FIELD Unsupportedvirtual field [‘FIELDNAME’]

Virtual fields are an advanced feature only supported by certain connectors.When using virtual fields, only those fields supported by the connector inquestion are valid. When a connector supports virtual fields and a fieldprovided has that connector’s virtual code set, then it will generate thiserror if it does not understand the supplied virtual field. Check the connec-tor documentation for information on supported virtual fields.

&H3210 12816 LCFAIL_VIRTUAL_VALUE Invalid data valuefor virtual field [‘FIELDNAME’]

Virtual fields are an advanced feature supported only by certain connectors.When using virtual fields, only values supported by the connector inquestions are valid. When a connector supports virtual fields and a fieldprovided has that connector’s virtual code set, then it will generate thiserror if it cannot handle or interpret the value supplied in that virtual field.Check the connector documentation for information on supported virtualfields and valid values for those fields.

&H3211 12817 LCFAIL_INVALID_ORDER Invalid order field[‘FIELDNAME’]

The indicated field was provided as an ordering field, but no such usablefield exists in the result set or external system. This error can occur whenmisspelling a fieldname or leaving the indicated field out of the result set. Itcan also occur in some cases when using a non-searchable field (as definedby the external systems; check the connector documentation for informationon data types that cannot be used as keys) for ordering, and not using anOrder Metaconnector.


Appendix BConnector Property Tokens

This appendix provides information about the property tokens used in theLotus Connectors LotusScript Extensions.

Predefined TokensWhen you work with property tokens, keep in mind:

• Flags can be combined with LCX property tokens.

• The base value for an LCX property is between 1 and 0xFFFF.

Several connector property tokens are shown below:

LCTOKEN_BASESTAMP – Base timestamp value for timestamp selection;see STAMPFIELD property.

LCTOKEN_CHARACTER_SET – Character Set indicator representing thecharacter set used by this connector for data transfers to and from the exter-nal system. This is normally dynamically determined by the connector fromthe external system at run time. Often read-only, but may be assigned forsome connectors. Valid values include any text stream format suffix fromthe supported character set appendix (such as “IBMCP932“ forLCSTREAMFMT_IBMCP932.)

LCTOKEN_CONDITION – Condition string in a syntax defined by theconnector. This clause will be embedded within a selection or modificationstatement for Select, keyed Update, or keyed Remove operations.

LCTOKEN_CONNECTOR_CODE – A code unique to this connector, andthe same for all connections to this connector. This code is assigned dynami-cally, so may change for each execution of a script. This code can be used asa virtual field code to indicate special handling by any connection to thisconnector.

LCTOKEN_CONNECTOR_NAME – Property representing the firstsub-connector for a particular Metaconnector. Setting this property to aconnector name is the same as creating a connection of that connector typeand assigning it to the metaconnector.

273

LCTOKEN_CONNECTION_CODE – A code unique to this connectionamong all connections. This code is assigned dynamically, so may changefor each execution of a script. This code can be used as a virtual field codeto indicate special handling by this connection only.

LCTOKEN_DATABASE – Database string, used for connectivity.

LCTOKEN_EVENT_ERROR – Error code (LCFAIL_XXX constant) to treatas an event. When this error is generated, it is downgraded to an informa-tional event. Set to LCSUCCESS to clear this property.

LCTOKEN_FIELDNAMES – Selection field name list, a text list (or commaor semicolon-separated list of field names in a text string) indicating fieldsto include in a Select method result set. By default, all fields selected areincluded; this property can be used to restrict that list.

LCTOKEN_IGNORE_ERROR – Error code (LCFAIL_XXX constant) toignore. When this error is generated, it is ignored. Set to LCSUCCESS toclear this property.

LCTOKEN_INDEX – Index string. Used when an index name is required,such as when creating or dropping an index.

LCTOKEN_LCX_VERSION – Version code for the connector LCX/DCXlibrary.

LCTOKEN_MAP_NAME – Map by name flag; set to TRUE to map fields infieldlist to external metadata by name, and to FALSE to map by position.

LCTOKEN_MAXSTAMP – Maximum timestamp value for timestamp selec-tion; see the STAMPFIELD property. This property is set by the Connectorduring Select operations when the STAMPFIELD property is set.

LCTOKEN_METADATA – Metadata object name. Used for reading andwriting records, as well as creating, dropping, and cataloging metadata andfields.

LCTOKEN_NAME – Library name for the connector used to create thisconnection.

LCTOKEN_ORDERNAMES – Ordering field name list, a text list (orcomma or semicolon-separated list of field names in a text string) indicatingfields by which to order a Select method result set.

LCTOKEN_OWNER – Owner name string to restrict Catalog method calls(excluding server and database catalogs) to only objects owned by thisowner.

LCTOKEN_PASSWORD – Password string, used for connectivity. Thisvalue is write-only, and cannot be retrieved from a connector onceassigned.


LCTOKEN_PROCEDURE – Procedure name, used by the Call method.

LCTOKEN_SCROLLABLE – Whether to produce a scrollable result set. Thisproperty is not supported by any connectors at this time.

LCTOKEN_SERVER – Server string, used for connectivity.

LCTOKEN_STAMPFIELD – Name of the field containing a timestampvalue (must be a datetime data type). When set before calling the Selectmethod, the result set will be restricted to fields where the timestamp fieldvalue is between the value assigned to the BASESTAMP property andreturned in the MAXSTAMP property. If BASESTAMP is not set, nominimum will be used. The Select method will determine the current timefrom the external server, assign that value to the MAXSTAMP property,and use that datetime as the upper boundary for selection.

LCTOKEN_TEXT_FORMAT – See CHARACTER_SET property; thisproperty is the numeric constant assigned to the particular character set.

LCTOKEN_USERID – User ID string, used for connectivity.

LCTOKEN_WRITEBACK – Writeback flag; set to TRUE before callingSelect to produce a writeback result set, and before calling Update orRemove to perform a writeback operation against a writeback result set.

Connector Identification Property TokensThe connector identification property tokens are listed below:

LCTOKEN_IDFLAG_ACTION – Action flags

LCTOKEN_IDFLAG_CONNECTOR – General flags

LCTOKEN_IDFLAG_OBJECT_CATALOG – Catalog flags

LCTOKEN_IDFLAG_OBJECT_CREATE – Create flags

LCTOKEN_IDFLAG_OBJECT_DROP – Drop flags

LCTOKEN_IDNAME_SERVER – Name for server objects in this externalsystem.

LCTOKEN_IDNAME_DATABASE – Name for database objects in thisexternal system.

LCTOKEN_IDNAME_USERID – Name for user ID objects in this externalsystem.

LCTOKEN_IDNAME_PASSWORD – Name for password objects in thisexternal system.

Appendix B: Connector Property Tokens 275

LCTOKEN_IDNAME_METADATA – Name for metadata objects in thisexternal system.

LCTOKEN_IDNAME_FIELD – Name for metadata fields in this externalsystem.

LCTOKEN_IDNAME_ALT_METADATA – Name for alternate metadataobjects in this external system.

LCTOKEN_IDNAME_ALT_FIELD – Name for alternate metadata fields inthis external.

LCTOKEN_IDNAME_PROCEDURE – Name for procedure objects in thisexternal system.

LCTOKEN_IDNAME_INDEX – Name for index objects in this externalsystem.

LCTOKEN_IDNAME_PARAMETER – Name for procedure parameters inthis external system.


Appendix CConnector Properties

This chapter provides information about Connector properties. Theseproperties are used when creating Connections using the Lotus ConnectorsLotusScript Extensions.

Connector PropertiesThe table below describes the items included in the tables of Connectorproperties.

The data type of the property:

Boolean Considered either FALSE (zero) or TRUE (non-zero).

Integer Valid values are indicated in the description.

Datetime Standard datetime.

Text Standard text stream.

Text List Can be submitted as a formatted text list or (more commonly)a comma, semicolon, or newline-separated text value.

All default values are FALSE (boolean), 0 (integer), no value(datetime), and the empty string (text) unless otherwise indicated.

Type

The property name. This is the dynamic property added through theLSX.

Name

Property token. Indicates the property is represented by thepredefined constant LCTOKEN_<name>. For example, METADATAindicates the constant LCTOKEN_METADATA. A number indicates aproperty specific to the particular connector.

Token

DescriptionItem

277

Notes Connector PropertiesThe table below defines the properties for the Lotus Connector for Notes.

continued

TextCondition

Notes-specific syntax conditional clauseused for Select operations (part of a Notesselection formula). This must be validsyntax for a “select <condition>” formula.

LCTOKEN_CONDITION

Text ListOrderNames

Text list of fields to order results by - usedfor Select operations

LCTOKEN_ORDERNAMES

Text ListFieldNames

Text list of fields to select - used for Selectoperations

LCTOKEN_FIELDNAMES

BooleanWriteback

Whether to perform writeback ornon-writeback operations.

LCTOKEN_WRITEBACK

BooleanMapByName

Whether to map by name or position whentransferring data between data source andtarget.

LCTOKEN_MAP_NAME

TextIndex

Notes view name.

LCTOKEN_INDEX

TextMetadata

Notes form name. Unlike many otherconnectors, Notes Execute operations alsorequire a Metadata property value, sincethe selection formula does not includemetadata information.

LCTOKEN_METADATA

TextDatabase

Notes database filepath, not the title.Required. Primarily used for establishing aconnection.

LCTOKEN_DATABASE

TextServer

Notes Server. If not supplied, the localNotes database will be accessed.

LCTOKEN_SERVER

TypeName/DescriptionToken


continued

IntegerEnforceForm

Whether to enforce the form design ondocuments created and accessed.

0 — The connection does not execute anyNotes form- and field-related formulas.

1 — Executes all Notes field-relatedformulas (default value, input translation,and computed field) as part of the session.This option may cause slower data transferas a result of formula calculations. Thisoption does not execute @DB functions.

2 — The session sets all field flags asdefined in the form but does not executeany formulas. As a result, special types,indicated in Notes by flags —such as readerand author names—are assigned in newdocuments as indicated in the form. Thisoption avoids the overhead of computingfield formulas.

2.00

TextPort

Port name to locate the server on. No valuesearches all ports.

1.00

DatetimeMaxStamp

During a Select operation, set by theconnector to the current/maximumtimestamp value - set by Select operations.

LCTOKEN_MAXSTAMP

DatetimeBaseStamp

Minimum timestamp value to include inresults - used for Select operations

LCTOKEN_BASESTAMP

TextStampField

Field name of timestamp field - used forSelect operations. Using StampFieldwithout a view (DB search instead) onlyworks when the timestamp field is“@Modified”, and the LoadModifiedproperty is set to TRUE. When not usingthis new property, a view search is stillrequired (although if no view property isset, a temporary one will be created).

LCTOKEN_STAMPFIELD


Appendix C: Connector Properties 279

continued

TextTemplateDatabaseNotes template database filepath onTemplateServer. This template is used inconjunction with the CreateDatabaseoption.

9.00

TextTemplateServerNotes Server where the database specifiedat TemplateDatabase resides. This templateis used in conjunction with theCreateDatabase option. No value uses thelocal Notes installation

8.00

BooleanCreateDatabaseWhether to create a database duringconnection if one does not exist. Thedatabase is blank, unless a databasetemplate is specified with theTemplateServer and TemplateDatabaseproperties.

7.00

BooleanUpdateViewsWhether to update all views in the databaseduring disconnection. After making exten-sive changes, the initial opening of a viewcan perform a time-consuming update.

6.00

TextFilePathDirectory on the Domino server into whichattachments are extracted to and attachedfrom when using the FILE virtual field orthe LoadFile property. By default, thecurrent working directory is used.

5.00

BooleanBulkStoreWhether to buffer all documentmodifications for bulk submittal atdisconnection. This increases performance,but prevents access to those changes untildisconnection.

4.00

BooleanMultiValueAsTextWhether to represent all multi-value Notestypes (text list, number list, and datetimelist) as text values. This can make typetransformation between non-Notesconnectors that do not support multi-valuetypes more straightforward.

3.00



continued

BooleanLoadUnid

Whether to add a UNID virtual field to theresult set produced by an Execute or Selectoperation.

17.00

BooleanViewResponses

Whether to include view response docu-ments. By default, only main topics areincluded. Requires a View property value.

16.00

BooleanAllForms

Whether to include documents of all forms.By default, only documents of the formindicated by the metadata property valueare included. When including documents ofother forms, fields in the indicatedmetadata are used in place of thosedocument’s forms.

15.00

BooleanFetchViewData

Whether to fetch data from view columnsrather than from document fields. Requiresa View property value.

14.00

IntegerTextMaxLength

Notes text data is limited to slightly lessthan 64K. To simplify data creation on otherconnectors with shorter text columns,specify a value to assign as the maximumlength for text metadata in any result setproduced.

13.00

TextFullTextQuery

Notes full text query for an Executeoperation on the result set produced byeither the Statement parameter or the Viewproperty, and any Agent property.

12.00

TextAgent

Notes agent to run for an Execute operationon the result set produced by either theStatement parameter or the View property.

11.00

TextView

Notes view to open for Execute or to use forkeyed operations. The view’s result setreplaces any Statement submitted toExecute.

10.00



continued

BooleanMailEmbedForm

Whether to embed the form in documentsmailed through the InsertMail property.Use when the target form is not available inthe recipients’ mail database.

25.00

BooleanInsertMail

Whether to reroute Inserted documents asmail. Normal Notes addressinginformation, such as the required SendTofield, is used.

24.00

BooleanExecuteDelete

Whether to delete the result set producedduring an Execute operation. This propertyis to simulate native DELETE statementsprovided on some other connectors.

23.00

BooleanCopyFile

Whether to add a LCXFILE virtual field tothe result set produced by an Execute orSelect operation.

22.00

BooleanCopyHierarchy

Whether to add a LCXHIER virtual field tothe result set produced by an Executeoperation.

21.00

BooleanLoadFile

Whether to add a FILE virtual field to theresult set produced by an Execute or Selectoperation.

20.00

BooleanLoadRef

Whether to add a REF virtual field to theresult set produced by an Execute or Selectoperation.

19.00

BooleanLoadNoteid

Whether to add a NOTEID virtual field tothe result set produced by an Execute orSelect operation.

18.00



continued

BooleanLoadModified

Set to add a field “@Modified” to the resultset, which contains the Notes implicitdocument timestamp. This field can only beread and attempts to set it will be ignored.

31.00

BooleanAlterView

When the LSX does a Select operation withthe connector’s View property set,AlterView=True allows the script to modifyor create the view if it doesn’t already existor doesn’t have the proper formatting.Necessary for select operations when aview and stampfield are specified.

30.00

BooleanSearchNoCase

Makes view searches case-insensitive (theyare case-sensitive by default).

29.00

BooleanPurgeDeleteStubs

Clears all deletion stubs from the Notesdatabase when disconnecting. It is stronglyrecommended that this only be used withUpdateViews, since once the stubs aredeleted, they will not be properly removedfrom views.

28.00

Text list EncryptKeyList

One or more private encryption key namesseparated by commas or semicolons, to beused by Encrypt. Valid only if Encrypt isTrue.

27.00

BooleanEncrypt

Encrypts all encryption-enabled fields inthe form of the target document. To useprivate encryption keys (the default is touse the public key), provide one or moreprivate encryption key names, separated bycommas or semicolons in EncryptKeyList.These keys must be available on theDomino server.

26.00



continued

TextPreUpdateFormula

Enter the Notes formula that will executebefore the data in the designated target isupdated. The transformation will take placeas part of the update operation.

37.00

TextPreInsertFormula

Enter the Notes formula that will executejust before the selected data is inserted intothe target. The data is changed as part ofthe insert operation.

36.00

TextPostFetchFormula

Enter the Notes formula that will executejust after the data is fetched. The data isaltered as part of the fetch/select operation.

35.00

BooleanDeleteDatabase

Deletes the database specified in theActivity upon connection. This is usedtogether with Creation (below) to deleteand then recreate the database prior topopulation.

34.00

BooleanCopyCompSpecial

Copies any composite support fieldsassociated with transferred documents.This includes the fields, links, and fonts toreturn full fidelity of composed data.

To use this option from an Activity withmanual field mapping, add a field‘LCXHIER’ to both field lists (this is notnecessary for automatic field mapping byname or position).

33.00

IntegerStampViewKey

Indicates the value for the first key value forkeyed operations when the view is anLSX-created view for timestamp selection.Zero means don’t use. 1 is the value fordocs outside the timestamp selection range,2 is the value for docs inside the range.When performing a timestamp selection,this is automatically set to 1 by theconnector, and reset to zero when clearingthe result set, and should only be used oraltered with great care.

32.00



Text ListAddSubformList

To support computed subforms, list all ofthe subforms to include here. All fields inthese subforms will be considered to be partof the form.

38.00


Notes Connector Property CombinationsThe following are invalid combinations:

• FetchViewData TRUE and Agent or FieldList non-NULL

• View NULL and any of FetchViewData, ViewResponses, or CopyFileTRUE

• ViewResponses TRUE and CopyHierarchy TRUE

• FetchViewData TRUE and any of LoadUnid, LoadNoteid, LoadRef,LoadFile, or CopyFile TRUE

• MapByName TRUE and any of LoadUnid, LoadNoteid, LoadRef,LoadFile, CopyFile, or CopyHierarchy TRUE

When using ordering or timestamps (properties OrderNames orStampField, respectively) in Notes select operations, the View property canbe set to indicate the name of the view to use for these operations. Whenperforming selections with View set, the LSX will check that the view hasthe proper formatting (special requirements for either ordered or times-tamped result sets). If the view has the correct format, it will be used.Supplying a view name when doing these operations can drasticallyimprove performance by not requiring the database to be reindexed everyrun. When no view is specified, a temporary view is still created. When theview is the wrong format or doesn’t exist, the use of the AlterView propertyallows the LSX to create or overwrite that view to be in its own format.

Processing Attachments Stored in Rich Text FieldsNotes 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. It stores theattachment data separately from the Rich Text field data. Currently you canonly transfer attachments from Notes to Notes; Rich Text fields with attach-ments do not store correctly in the target RDBMS’s such as DB2 and Oracle.


To work around this constraint, you can use the Notes Connector ExtractFile Attachments option to save attachments to files on disk. You can thenuse LotusScript to read the files, store their contents in LCFields, and savethe LCFields to binary fields in a RDBMS. This level of scripting requiresLotusScript expertise.

Notes Virtual FieldsNotes recognizes a set of virtual fields — fields which are interpreted differ-ently by the Notes connector than by other connectors. To use these virtualfields, either set the virtual code of the relevant fields to the Notes Connec-tor virtual code (obtain the property LCTOKEN_CONNECTOR_CODEfrom a Notes connection, and set that code into the properly names fieldusing the LCField.SetVirtualCode method), or use one of the Notes proper-ties which adds a virtual field to the result set. The virtual fields supportedby Notes are described below:

4.00Binary (BLOB)CopyCompSpecialLCXSPEC

4.00Binary (BLOB)CopyFileLCXFILE

8.00Binary (BLOB)CopyHierarchyLCXHIER

N/ADatetimeLoadModifiedMODIFIED

variable (up to 64K)Binary (Text List)LoadFileFILE

16.00Binary (BLOB)LoadRefREF

N/AIntegerLoadNoteidNOTEID

16.00Binary (BLOB)LoadUnidUNID

Stream Length (in bytes)Data typeCorresponding PropertyField Name

Descriptions may vary based on whether a document is being read (Fetch)or written (Insert or Update):

• UNID

Read — Read the UNID of the document

Write — Set the document’s UNID to the field value

• NOTEID

Read — Read the NOTEID of the document

Write - Ignored

• REF

Read — Read the parent UNID of a response document

Write — Make the document a response to the document whose UNIDis in this field


• FILERead — Retrieve all attachments from the document, writing the files todisk. This field is set to a text list containing the filenames of all the filesfrom the document

Write — Store each entry in the text list value as a file attachment to thedocument.

• MODIFIEDRead — Read the last modified timestamp from the document

Write — Ignored

• LCXHIERThis field is only relevant when the document is both read from andwritten to a Notes connector. When written, the field contents storedduring the read are used to access the source database and transfer theentire response hierarchy beneath the document into the targetdatabase. Note that the source result set must still be valid at the timethe document is written.

• LCXFILE

This field is only relevant when the document is both read from andwritten to a Notes connector. When written, the field contents storedduring the read are used to access the source database and transfer allfile attachments directly from the source document to the targetdocument. Since they are transferred directly without temporarystorage on disk, this is more efficient than the FILE property for Notesto Notes transfers. The source document must be the most recentlyfetched document in the result set at the time the document is written.

• LCXSPEC

This field is only relevant when the document is both read from andwritten to a Notes connector. When written, the field contents storedduring the read are used to access the source database and transferspecific document fields required to retain full document fidelity fordoclinks and rich text fonts. Specifically the fields “$Links“ and“$Fonts“ are copied. The source document must be the most recentlyfetched document in the result set at the time the document is written.


DB2 Connector PropertiesThe table below defines the properties for the Lotus Connector for DB2.

continued

True (1)BooleanWriteback

Specifies whether theLCXUpdate or LCXRemoveoperation is a writebackoperation.

LCTOKEN_WRITEBACK

True (1)BooleanMapByName

Specifies whether to mapfields and columns by nameor by position whentransferring data betweenthe data source andLEI/DECS.

LCTOKEN_MAP_NAME

“DBINST1.EMPID”

TextIndex

Specifies the name of a DB2index.

LCTOKEN_ INDEX

“DBINST1.EMP_TABLE”

TextMetadata

Specifies the name of a DB2table to access during anoperation.

LCTOKEN_METADATA

“dbinstpass”TextPassword

Specifies a passwordassociated with the specifieduser name known by DB2.

Required.

LCTOKEN_ PASSWORD

“dbinst1”TextUsername

Specifies the user name asknown by DB2. This username is used to authorizeaccess to the specifieddatabase.

Required.

LCTOKEN_ USERID

“db2ver6”TextDatabase

Specifies the DB2 databasename used to establish aconnection. Required.

LCTOKEN_DATABASE

ExampleTypeProperty Name/DescriptionProperty Token


continued

“DBINST1”TextOwner

Displays a result set.

Only objects owned by theowner name in this propertyare included in the result set

LCTOKEN_ OWNER

“DBINST1.PROC1”

TextProcedure

Specifies the storedprocedure to execute for theLCXCall method.

LCTOKEN_PROCEDURE

“IBMCP932”TextTextFormat

Specifies a DB2 character setother than NATIVE.

LCTOKEN_TEXT_FORMAT

09/27/200001:38 PM

DatetimeMaxStamp

Displays the currenttimestamp value. During aSelect operation, this is setby the Connector to thecurrent timestamp value.

LCTOKEN_MAXSTAMP

11/17/200012:00 AM

DatetimeBaseStamp

Specifies a minimumtimestamp value to includein result sets.

LCTOKEN_BASESTAMP

“MODIFIED”TextStampField

Specifies a field name oftimestamp field.

LCTOKEN_STAMPFIELD

“EMPID =1123”

TextCondition

Specifies a DB2-specificsyntax conditional clauseused for select, keyedupdate, and removeoperations. Must be of validsyntax.

LCTOKEN_CONDITION

“LNAME,MGR”

TextListOrderNames

Displays a text list of fieldsto order results by.

LCTOKEN_ORDERNAMES

“EMPID,FNAME,LNAME”

TextListFieldNames

Displays a text list of fieldswith which to perform anoperation.

LCTOKEN_FIELDNAMES



continued

10.00IntegerCommitFrequency

Specifies the number ofmodification actionsbetween commits. A valueof zero causes a commit atdisconnect; a value of oneauto-commits after everyaction; any other valuecommits after that manydata modification actions.

1.00IntegerPosition

Specifies the start position ofa scrollable cursor.

LCTOKEN_ POSITION

True (1)BooleanScrollable

Specfies whether or notfetch cursors will bescrollable in DB2.

Note Scrollable cursors arecurrently supported inLotusScript and LCJavaonly. Scrollable cursors aredisabled by default, andenabled by setting theconnection property“SCROLLABLE” to True (1)in the script.

LCTOKEN_SCROLLABLE

10.00IntegerRecordLimit

Specifies the maximumnumber of records in theresult set. Result setsproduced should be limitedto this many records. Avalue of zero (the default)indicates no limit.

LCTOKEN_RECORD_LIMIT

True (1)BooleanAlternateMetadata

Affects the behavior ofMETADATA and FIELDcatalog types, returning alist of objects of the alternatemetadata type instead of thenormal metadata type.

LCTOKEN_ALT_METADATA



True (1)BooleanTraceSQL

Specifies that all SQLstatements generated 1during the execution of theActivity be included in theActivity’s log.

6.00

“DBINST1.EMP_TABLE2”

TextCreateInDatabase

Used to add “INDATABASE <dbname>” toa CREATE TABLE queryconstructed for tablecreation.

5.00

False (0)BooleanNoJournal

Specifies whether thedatabase containsnon-journaled data. If so,the transaction isolationlevel is set to uncommittedread to permit SQLoperations.

4.00

128.00IntegerCreateMaxLogged

Specifies the maximumlength of a CLOB/BLOBcolumn to create whenlogging. This value is usedwhen creating tables.

If, during metadata creation,the length is longer than thisvalue, the option NOTLOGGED COMPACT isused.

A value of zero indicates nomaximum, althoughunbounded columns arealways created with thisoption.

3.00

True (1)BooleanRollbackOnError

Specifies whether to rollback the current transactionat disconnect if the sessionis in an error state.

2.00



File System Connector PropertiesThe table below defines the properties for the Lotus Connector for FileSystem.

continued

DatetimeBaseStamp

Minimum timestamp value to include inresults — used for Select operations

LCTOKEN_BASESTAMP

TextStampField

Field name of timestamp field — used forSelect operations

LCTOKEN_STAMPFIELD

TextCondition

The file specification for the files to include.The specification can include the standardwildcard characters: * to match anycharacter string; ? to match any singlecharacter.

LCTOKEN_CONDITION

Text ListOrderNames

Multi-value text list of fields to order resultsby - used for Select operations

LCTOKEN_ORDERNAMES

Text ListFieldNames

Multi-value text list of fields to select - usedfor Select operations

LCTOKEN_FIELDNAMES

BooleanWriteback


LCTOKEN_WRITEBACK

BooleanMapByName


LCTOKEN_MAP_NAME

TextMetadata

The subdirectory name (mydirectory orsomedir/mydir). This subdirectory containsthe files you want to access.

LCTOKEN_METADATA

TextDatabase

Path to the directories (C:\files\somefiles or/unix/usr/files). Required.

LCTOKEN_DATABASE



IntegerSort

Defines the sort order in the case of orderingby filename (0 = binary, 1 = case sensitive, 2 = case insensitive).

2.00

BooleanBinary

Whether file contents should be treated asbinary (BLOB) data rather than the default(native TEXT).

1.00

DatetimeMaxStamp

During a Select operations, set by theconnector to the current timestamp value —set by Select operations

LCTOKEN_MAXSTAMP


File System MetadataFile system metadata is defined as follows:

Filename — Text

Contents — Text

Timestamp — Datetime

Size — Int

ODBC Connector PropertiesThe table below defines the properties for the Lotus Connector for ODBC.

continued

TextMetadata

Data table source or target for data transferoperations

LCTOKEN_METADATA

TextPassword

Password: used for logging in duringconnection

LCTOKEN_PASSWORD

TextUserid

User ID/name: used for logging in duringconnection

LCTOKEN_USERID

TextServer

Name of the ODBC data source as listed inthe ODBC Administrator

LCTOKEN_SERVER



continued

IntegerMaximum number of seconds to wait for asuccessful connection (the default value ofzero indicates to use that connector’s defaultsettings).

LCTOKEN_CONNECT_TIMEOUT

BooleanAffects the behavior of METADATA andFIELD catalog types, returning a list ofobjects of the alternate metadata type insteadof the normal metadata type.


TextOwner

Only objects owned by the owner name inthis property are included in the result set

LCTOKEN_ OWNER

DatetimeMaxStamp

During a Select operations, set by theconnector to the current timestamp value —set by Select operations

LCTOKEN_MAXSTAMP

DatetimeBaseStamp


LCTOKEN_BASESTAMP

TextStampField

Name of timestamp field used for Selectoperations

LCTOKEN_STAMPFIELD

TextCondition

Connector-specific syntax conditional clause— used for Select operations

LCTOKEN_CONDITION

Text ListOrderNames

Text list of fields to order results by — usedfor Select operations

LCTOKEN_ORDERNAMES

Text ListFieldNames

Text list of fields to select — used for Selectoperations

LCTOKEN_FIELDNAMES

BooleanWriteback


LCTOKEN_WRITEBACK

BooleanMapByName


LCTOKEN_MAP_NAME

TextIndex

Data index name.

LCTOKEN_INDEX



BooleanSingleThread

By default, the Lotus Connector for ODBC ismulti-threaded. However, some ODBCdrivers are not multi-threaded. Use thisproperty to force the connector into a singlethread.

7

BooleanTraceSQL

Select this option to include all SQLstatements generated during the execution ofthe Activity in the Activity’s log. This can behelpful when you need to troubleshoot theActivity.

6

TextDBMSName

Read-only name of the DBMS target of theODBC connection

5

TextQuoteColumn

String used to surround column names (forexample ")

4

BooleanDisableCursor

Whether to force disabling of ODBC cursors.This option reduced performance, andshould be used only during writebackoperations when the ODBC driverinaccurately reports cursor support, resultingin an error.

3

BooleanRollbackOnError

Whether to rollback the current transactionat disconnection if the session is in an errorstate.

2

IntegerCommitFrequency

Number of data modification actionsbetween commits. A value of zero causes acommit at disconnect; a value of oneauto-commits after every action; any othervalue commits after that many datamodification actions.

1

IntegerResult sets produced should be limited tothis many records. A value of zero (thedefault) indicates no limit.




Oracle 7 Connector PropertiesThe table below defines the properties for the Lotus Connector for Oracle 7.

continued

TextStampField


LCTOKEN_STAMPFIELD

TextCondition

Connector-specific syntax conditionalclause — used for Select operations

LCTOKEN_CONDITION

Text ListOrderNames

Text list of fields to order results by — usedfor Select operations

LCTOKEN_ORDERNAMES

Text ListFieldNames

Text list of fields to select — used for Selectoperations

LCTOKEN_FIELDNAMES

BooleanWriteback


LCTOKEN_WRITEBACK

BooleanMapByName


LCTOKEN_MAP_NAME

TextIndex

Index name.

LCTOKEN_INDEX

TextMetadata

Data table or view: the source or target fordata transfer operations.

LCTOKEN_METADATA

TextPassword

Password — used for logging in duringconnection

LCTOKEN_PASSWORD

TextUserid

User ID/name — used for logging induring connection

LCTOKEN_USERID

TextServer

Oracle Host Name. Required.

LCTOKEN_SERVER



continued

BooleanAffects the behavior of METADATA andFIELD catalog types, returning a list ofobjects of the alternate metadata typeinstead of the normal metadata type.


TextOwner

Only objects owned by the owner name inthis property are included in the result set

LCTOKEN_ OWNER

TextProcedure

Use when executing parameterized storedprocedures in a link-independent fashion.When a session is run and this property isset, the property’s value is taken as a storedprocedure name and is executed instead ofthe normal selection operation, potentiallyproducing a result set. If a fieldlist isprovided to the Select operation, then allfields in that fieldlist (not just key fields)are supplied to the stored procedure asparameters, with the names taken from thefield names.

LCTOKEN_PROCEDURE

DatetimeMaxStamp

During a Select operations, set by theconnector to the current timestamp value— set by Select operations

LCTOKEN_MAXSTAMP

DatetimeBaseStamp


LCTOKEN_BASESTAMP



continued

TextCreateLongColumn

Use for table creation. Name of the columnto create as a long type during tablecreation (Oracle tables are restricted to onelong column). This value is only used ifCreateLongByUser property indicates auser-defined long column.

3.00


Whether to rollback the current transactionat disconnection if the session is in an errorstate.

2.00


Number of data modification actionsbetween commits. A value of zero causes acommit at disconnect; a value of oneauto-commits after every action; any othervalue commits after that many datamodification actions. Note: A commitduring a cursored (writeback) operationfollowing an update unlocks result set.Therefore, when a writeback result set isactive, the commit frequency property isignored and commits do not occur.

1.00

IntegerIndicate what the expected behavior of theprocedure call. The default behavior is toexecute a procedure and expect (but notrequire) a result.

The following context values may providemore specific information:

LCCALL_SELECT: check for (but do notrequire) a result set.

LCCALL_INSERT: Do not check for orproduce a result set.

LCCALL_UPDATE: Do not check for orproduce a result set.

LCCALL_REMOVE: Do not check for orproduce a result set.

LCCALL_COMMAND: Do not check for orproduce a result set.

LCCALL_NONE: No context information -behavior is defined by the connector.

LCTOKEN_CALL_CONTEXT



BooleanTraceSQL

Select this option to include all SQLstatements generated during the executionof the Activity in the activity’s log. This canbe helpful when you need to troubleshootthe Activity.

5.00

IntegerCreateLongByUser

Use for table creation. Method of selectingthe column to create as a long type duringtable creation. Oracle tables are restrictedto no more than one long column. A valueof zero indicates that the connector shouldchoose the best candidate from thecolumns being created (the first and/orlongest column). A value of one indicatesto use the column name in theCreateLongColumn property. A value oftwo indicates that no long column shouldbe created.

4.00


Oracle 8 Connector PropertiesThe table below defines the properties for the Lotus Connector for Oracle 8.

continued

TextIndex

Index name.

LCTOKEN_INDEX

TextMetadata

Data table or view: the source or targetfor data transfer operations.

LCTOKEN_METADATA

TextPassword


LCTOKEN_PASSWORD

TextUserid

User ID/name — used for logging induring connection

LCTOKEN_USERID

TextServer

Oracle Host Name. Required.

LCTOKEN_SERVER



continued

TextProcedure

Use when executing parameterizedstored procedures in a link-independentfashion. When a session is run and thisproperty is set, the property’s value istaken as a stored procedure name and isexecuted instead of the normal selectionoperation, potentially producing a resultset. If a fieldlist is provided to the Selectoperation, then all fields in that fieldlist(not just key fields) are supplied to thestored procedure as parameters, withthe names taken from the field names.

LCTOKEN_PROCEDURE

DatetimeMaxStamp

During a Select operations, set by theconnector to the current timestampvalue — set by Select operations

LCTOKEN_MAXSTAMP

DatetimeBaseStamp


LCTOKEN_BASESTAMP

TextStampField

Field name of timestamp field — usedfor Select operations

LCTOKEN_STAMPFIELD

TextCondition


LCTOKEN_CONDITION

Text ListOrderNames

Text list of fields to order results by —used for Select operations

LCTOKEN_ORDERNAMES

Text ListFieldNames

Text list of fields to select — used forSelect operations

LCTOKEN_FIELDNAMES

BooleanWriteback


LCTOKEN_WRITEBACK

BooleanMapByName

Whether to map by name or positionwhen transferring data between datasource and target.

LCTOKEN_MAP_NAME



continued


Number of data modification actionsbetween commits. A value of zerocauses a commit at disconnect; a valueof one auto- commits after every action;any other value commits after that manydata modification actions. Note: Acommit during a cursored (writeback)operation following an update unlocksresult set. Therefore, when a writebackresult set is active, the commit frequencyproperty is ignored and commits do notoccur.

1.00

IntegerIndicate what the expected behavior ofthe procedure call. The default behavioris to execute a procedure and expect(but not require) a result.

The following context values mayprovide more specific information:

LCCALL_SELECT: check for (but do notrequire) a result set.

LCCALL_INSERT: Do not check for orproduce a result set.

LCCALL_UPDATE: Do not check for orproduce a result set.

LCCALL_REMOVE: Do not check for orproduce a result set.

LCCALL_COMMAND: Do not checkfor or produce a result set.

LCCALL_NONE: No contextinformation - behavior is defined by theconnector.

LCTOKEN_CALL_CONTEXT

BooleanAffects the behavior of METADATAand FIELD catalog types, returning a listof objects of the alternate metadata typeinstead of the normal metadata type.


TextOwner

Only objects owned by the owner namein this property are included in theresult set

LCTOKEN_ OWNER



TextDefaultTranslationFormat

Fall back text format. It is the name ofthe Oracle text format to use ifautomatic translation fails.

7.00

BooleanEnhanceErrorInformation

Use this option to include additionalerror information or warnings in theactivities log.

6.00

BooleanTraceSQL

Use this option to include all SQLstatements generated during theexecution of the Activity in theActivity’s log. This can be helpful whenyou need to troubleshoot the Activity.

5.00


Whether to rollback the currenttransaction at disconnection if thesession is in an error state.

Note Tokens 3 and 4 are not valid forthe Oracle 8 connector.

2.00


OLE DB Connector PropertiesThe following table defines the properties for the Lotus Connector for OLEDB.

continued

TextObject Class

Data table or view: the source or target fordata transfer operations.

LCTOKEN_METADATA

TextPassword

Password. Used for logging in duringconnection.

LCTOKEN_PASSWORD

TextUser ID/name

User ID/ Name used for logging in duringconnection.

LCTOKEN_USERID

TextDatabase

Database name

LCTOKEN_DATABASE



continued

TextOwner

Only objects owned by the owner name inthis property are included in the result set.

LCTOKEN_OWNER

DatetimeProcedure

The stored procedure to execute for the Callmethod.

LCTOKEN_PROCEDURE

DatetimeMaxStamp

During a Select operations, set by theconnector to the current timestamp value.

LCTOKEN_MAXSTAMP

DatetimeBaseStamp

Minimum timestamp value to include inresults — used for Select operations.

LCTOKEN_BASESTAMP

TextStampField

Field name of timestamp field — used forSelect operations.

LCTOKEN_STAMPFIELD

TextCondition

OLE DB Provider-specific syntax conditionalclause — used for Select operations.

LCTOKEN_CONDITION

TextListFieldNames

Text list of fields to select — used for Selectoperations.

LCTOKEN_FIELDNAMES

BooleanWriteback

Whether to perform writeback ornon-writeback operations. Even withWriteback operations, the fieldlist mustcontain key fields which uniquely identifythe record to be modified.

LCTOKEN_WRITEBACK

BooleanMapByName

Whether to map by name (TRUE) or position(FALSE) when transferring data betweendata source and target.

LCTOKEN_MAP_NAME

TextIndex

Index name.

LCTOKEN_INDEX



continued

TextInit_Catalog

Corresponds to the OLE DBDBPROP_INIT_CATALOG property. Forthe Microsoft SQL Server provider enter thename of the initial database to use. Not usedfor the Microsoft Jet provider.

4.00

TextInit_DataSource

Corresponds to the OLE DBDBPROP_INIT_DATASOURCE property.For the Microsoft SQL Server provider, enterthe server name. For the Microsoft Jetprovider, use the path to the Jet (.mdb)database.

3.00

TextInit_Location

Corresponds to the OLE DBDBPROP_INIT_LOCATION property. Notused for either the SQL Server or Jet OLE DBproviders.

2.00

TextProvider

The OLE DB provider’s COM programmaticID (ProgID). Thus it indicates which OLEDB driver to use. For Microsoft SQL Server 7use “SQLOLEDB”; for Microsoft Access 2000databases use “Microsoft.Jet.OLEDB.4.0” —Required

1.00



continued

IntegerInit_Mode

Corresponds to the OLE DBDBPROP_INIT_MODE property. Not usedfor the Microsoft SQL Server provider.

For the Microsoft Jet provider, bitwise or thenumeric values to indicate special accessprivileges. The default setting isDB_MODE_READWRITE.

The following list shows the AccessPrivileges, Value, and Description for eachsetting.

wwww DB_MODE_READ — 1 — Indicatesread-only

wwww DB_MODE_READWRITE — 3 —Indicates read/write

wwww DB_MODE_SHARE_DENY_WRITE — 8— Prevents others from opening in writemode

wwww DB_MODE_SHARE_EXCLUSIVE — 12— Prevents others from opening inread/write mode

wwww DB_MODE_SHARE_DENY_NONE — 16— Indicates that neither read nor writeaccess can be denied to others

5.00



continued


Number of data modification actionsbetween commits. A value of zero causes acommit at disconnect; a value of oneauto-commits every action; any other valuecommits after that many data modificationactions.

8.00

TextAuth_Integrated

Corresponds to the OLE DB DBPROP_AUTH_INTEGRATED property. Indicatesthe authentication service to use if any. Forthe Microsoft SQL Server provide, one canenter “SSPI” in order to use Windows NTAuthentication service for authorizing useraccess to the SQL Server database. If thisproperty is not set, the SQL Server login andpassword should be specified in the UserIDand Password properties.

Not used for the Microsoft Jet provider.

7.00

TextInit_ProviderString

Corresponds to the OLE DBDBPROP_INIT_PROVIDERSTRINGproperty. OLE DB recognizes an ODBC-likesyntax in provider string property values.Within the string, elements are delimited byusing a semicolon. The final element in thestring must be terminated with a semicolon.Each element consists of a keyword, anequal sign character, and the value passedon initialization, as shown in the followingexample:

Server=Gumby;UID=everett;

For the Microsoft SQL Server provider,developers may need to set the networkproperty to the name of the Net-Library(DLL) used to communicate with the SQLServer. The name should not include thepath or the .dll file name extension. So forexample to use the TCP/IP network library,add the following:“Network=DBMSSOCN;” Alternatively, thedefault Net-Library can be set by the SQLServer Client Network Utility.

6.00



continued

IntegerIsolationLevel

This property determines the extent thatoutside actions can affect a transaction. ReadCommitted is the default option.

The following list shows the Name,Description, and Value for each option.

wwww Read Uncommitted — A transactionoperating at the Read Uncommitted levelcan see uncommitted changes made byother transactions. At this level ofisolation, dirty reads, nonrepeatablereads, and phantoms are all possible —256

wwww Read Committed — A transactionoperating at the Read Committed levelcannot see changes made by othertransactions until those transactions arecommitted. At this level of isolation, dirtyreads are not possible but nonrepeatablereads and phantoms are possible — 4,096

wwww Repeatable Read — A transactionoperating at the Repeatable Read level isguaranteed not to see any changes madeby other transactions in values it hasalready read. At this level of isolation,dirty reads and nonrepeatable reads arenot possible but phantoms are possible.— 65,536

wwww Serializable — A transaction operating atthe Serializable level guarantees that allconcurrent transactions interact only inways that produce the same effect as ifeach transaction were entirely executedone after the other. At this isolation level,dirty reads, nonrepeatable reads, andphantoms are not possible. transactionsinteract only in ways that produce thesame effect as if each transaction wereentirely executed one after the other. Atthis isolation level, dirty reads,nonrepeatable reads, and phantoms arenot possible. — 1,048,576

9.00



BooleanTraceSQL

Include all SQL statements generated duringthe execution of the activity in the activity’slog.

10.00


Sybase Connector PropertiesThe table below defines the properties for the Lotus Connector for Sybase.

continued

Text ListFieldNames

Multi-value text list of fields to select —used for Select operations

LCTOKEN_FIELDNAMES

BooleanWriteback


LCTOKEN_WRITEBACK

BooleanMapByName

Whether to map by name or positionwhen transferring data between datasource and target.

LCTOKEN_MAP_NAME

TextIndex

Index name. A view (Notes), index(relational DB), or other data index

LCTOKEN_INDEX

TextMetadata

Metadata object — the source or target fordata transfer operations. A form (Notes),table (relational DB), or other datacontainer

LCTOKEN_METADATA

TextPassword


LCTOKEN_PASSWORD

TextUser ID/name

Used for logging in during connection

LCTOKEN_USERID

TextDatabase

Database name.

LCTOKEN_DATABASE

TextServer

Server name. Required.

LCTOKEN_SERVER



continued

IntegerResult sets produced should be limited tothis many records. A value of zero (thedefault) indicates no limit.


IntegerMaximum number of seconds to wait for asuccessful connection (the default value ofzero indicates to use that connector’sdefault settings).

LCTOKEN_CONNECT_TIMEOUT

BooleanAffects the behavior of METADATA andFIELD catalog types, returning a list ofobjects of the alternate metadata typeinstead of the normal metadata type.


TextOwner

Only objects owned by the owner name inthis property are included in the result set.

LCTOKEN_ OWNER

TextProcedure

The stored procedure to execute for theCall method. Any returned result set isavailable.

LCTOKEN_PROCEDURE

DatetimeMaxStamp

During a Select operations, set by theconnector to the current timestamp value -set by Select operations

LCTOKEN_MAXSTAMP

DatetimeBaseStamp


LCTOKEN_BASESTAMP

TextStampField


LCTOKEN_STAMPFIELD

TextCondition


LCTOKEN_CONDITION

Text ListOrderNames

Multi-value text list of fields to orderresults by — it is used for Selectoperations

LCTOKEN_ORDERNAMES



BooleanTraceSQL

Select this option to include all SQLstatements generated during the executionof the Activity in the Activity’s log. Thiscan be helpful when you need totroubleshoot the activity.

7.00

BooleanProcedureStatus

A Sybase stored procedure can eithergenerate a result set or return a statuscode. When a non-zero code is returned,this may signal an error. The defaultbehavior is to interpret the status as a1-row, 1-column result set. Selecting thisoption interprets the status codeseparately, not as a result set (non-zero iserror, and zero is success).

6.00

BooleanDisableCursor

Disable Sybase writeback cursors.

5.00

BooleanCreateShortUnbound

Whether to truncate unbounded text andbinary data during table creation. Whenused, all text and binary fields with nomaximum length will be truncated to fit ina char/varchar/binary/ varbinarycolumn.

4.00

BooleanCreateShortBound

Whether to truncate bounded text andbinary data during table creation. Whenused, all text and binary fields with amaximum length will be truncated to fit ina char/ varchar/binary/ varbinarycolumn.

3.00



Appendix DCharacter Sets

This appendix provides information about character sets, including character set translation, character sort order, and a list of the character sets supported by the LotusScript Extensions Language (LC LSX).

When using the Oracle 7 Connector, set the notes.ini variable “EIOracle7NativeText” to a valid Oracle code page to force the translation of all transferred Oracle data to that code page.

When using the Oracle 8 Connector, set the notes.ini variable “EIOracle8NativeText” to a valid Oracle code page to force the translation of all transferred Oracle data to that code page.

International Character Set TranslationNot all computer systems treat text data the same. Computers around theworld have different character sets and sending text data from one countryto another may not yield expected results. As well, different databaseproducts treat this problem differently.

LEI and DECS provide extensive support for international character sets.LEI and DECS support over 200 different character set mappings, includingUS English, Asian, Far East, and Western and Eastern European languages,as well as multi-lingual characters sets such as LMBCS and Unicode. LEIprovides support for translating characters from one set to another.

All text data within LEI and DECS maintains a reference to its own charac-ter set. This reference is determined automatically by the connector whenthe data is fetched from a database. If the data is inserted into a databasewith a different character set, LEI and DECS automatically translates thetext data just prior to storing it. This process maintains maximum perform-ance by eliminating any unnecessary translation.

Performance may be further enhanced through three levels of translationsupport. The translation support choices are described below:

• Disabled — For maximum performance and when all text data is incompatible character sets, translation is disabled completely.

311

• LMBCS only — Only Notes text data is translated. This isappropriate when all non-Notes text data is in compatible charactersets.

• Enabled — Translation between different character sets alwaysoccurs.

Regardless of the setting, Unicode text is always translated.

Note In LEI, the text translation setting is available for each LEI server,allowing different servers to have different levels of support. Thetranslation support level is set during the installation of an LEI server. Itmay also be viewed and edited in the server configuration document in theLEI Administrator. In DECS, the text translation setting is controlled by thenotes.ini file, see “Forcing LEI or DECS to Use a Character Set as Native” inthis chapter.

Forcing LEI or DECS to Use a Character Set as NativeLEI and DECS determines the native character set on the local machineduring startup and uses this setting whenever the native character set isrequired. LEI and DECS can be forced to use a different character set asnative by setting the EINativeText variable in the notes.ini file to the suffixof an LEI text stream format.

LCSTREAMFMT_IBMCP932 indicates IBM code page 932. To force LEI touse that character set as native, add the following line to the notes.ini file:


Note The Supported Character Sets table appears later in this appendix.You can specify the native text character set in the notes.ini by simplyremoving the LCSTREAMFMT preface from the IBMname portion of theStream Format Constant name listed in that table.

In all cases, this character set will be assumed to be the native format.

The NativeText variable can be used in conjunction with any Character SetTranslation setting. The Character Set Translation Disabled setting causesthis character set to be used in all connector interactions. For example, ifyou’re on a CP932 machine, and you access CP819 data with the NativeTextvariable set to IBMCP932, the character set is considered to be CP932without translation enabled. If converted to another character set, it isconverted as if it were CP932.


In LMBCS-only mode, the system only operates with three character sets:

• Unicode = Unicode

• LMBCS = LMBCS

• All else = Native codepage

This option changes what native text is on the machine. For example, if youforce native text to be CP819, then all native text conversion maps to andfrom CP819. You still have Unicode and LMBCS as in the above example,but everything else is considered CP819.

This feature is important for Thai systems, where the native character setgenerally cannot be retrieved well. The Thai character set, IBMCP874, canbe set and then with the translation level set to LMBCS-only or disabled, alldatabases that LEI (or DECS) interacts with (except Notes if LMBCS onlytranslation is selected) will be considered as CP874.

Character Sort Order in LEILEI cannot control the sort order specified in the databases that it accesses.If the sort orders used in two databases are not the same, mismatches canarise during Replication Activities, causing excessive insert/delete opera-tions and thereby affecting performance. The use of the Order MetaConnec-tor for databases which sort differently is designed to solve sort orderdifferences. Replication also provides an option for case-insensitive stringcomparison when excessive insert/delete pairs occur during replicationbetween databases that use case-insensitive sorting.

See the Replication Activity chapter of the Lotus Enterprise Integrator Activi-ties and User Guide for more information about this feature. Also see theLotus Connectors and Connectivity Guide for information about the LotusConnectors and Metaconnectors.

List of Supported Character SetsThe list is given as text stream format constants. Any of these values may beused as a stream format for a text stream when creating scripts using theLotus Connectors LotusScript Extensions. To indicate the character set onthe local machine, use the constant LCSTREAMFMT_NATIVE. Whenproviding a character set on the LEI Administrator, use the stream formatconstant with the prefix “LCSTREAMFMT_” removed. For DECS see“Forcing LEI or DECS to Use a Character Set as Native” in this chapter.

Appendix D: Character Sets 313

continued

MS-DOS PRC (simplified) Chinese (CP 936)LCSTREAMFMT_IBMCP936

Chinese GB18030LCSTREAMFMT_GB18030

MS-DOS PRC (simplified) Chinese (GB 2312)LCSTREAMFMT_GB

MS-DOS Taiwan (traditional) Chinese (CP 950)

LCSTREAMFMT_IBMCP950

MS-DOS Taiwan (traditional) Chinese(BIG-5)

LCSTREAMFMT_BIG5

TCALCSTREAMFMT_TCA

MS-DOS Korean (CP 949)LCSTREAMFMT_IBMCP949

MS-DOS Korean — KSC 5601LCSTREAMFMT_KS

Extended UNIX CodeLCSTREAMFMT_EUC

DEC Multinational Character SetLCSTREAMFMT_DECMCS

MS-DOS PC Korean (CP 891)LCSTREAMFMT_IBMCP891

MS-DOS PC Japanese Microsoft Shift-JIS (CP 942)


MS-DOS PC Japanese Microsoft Shift-JIS (CP 932)


IBM Code Page 899 (CP 899)LCSTREAMFMT_IBMCP899

MS-DOS PC Greek (CP 869)LCSTREAMFMT_IBMCP869

MS-DOS PC Norwegian (CP 865)LCSTREAMFMT_IBMCP865

MS-DOS PC Canadian French (CP 863)LCSTREAMFMT_IBMCP863

MS-DOS PC Icelandic (CP 861)LCSTREAMFMT_IBMCP861

MS-DOS PC Portuguese (CP 860)LCSTREAMFMT_IBMCP860

MS-DOS PC Cyrillic (CP 855)LCSTREAMFMT_IBMCP855

MS-DOS PC Western European (CP 850)LCSTREAMFMT_IBMCP850

MS-DOS PC US (CP 437)LCSTREAMFMT_IBMCP437

MS-DOS PC Cyrillic Unicode (CP 866)LCSTREAMFMT_IBMCP866

MS-DOS PC Arabic (CP 864)LCSTREAMFMT_IBMCP864

MS-DOS PC Hebrew (CP 862)LCSTREAMFMT_IBMCP862

MS-DOS PC Turkish (CP 857)LCSTREAMFMT_IBMCP857

MS-DOS PC Turkish (CP 853)LCSTREAMFMT_IBMCP853

MS-DOS PC Eastern European (CP 852)LCSTREAMFMT_IBMCP852


Lotus International Character SetLCSTREAMFMT_LICS

DescriptionStream Format Constant


continued

IBM EBCDIC German — Austrian (CP 273)LCSTREAMFMT_IBMCP273

IBM Code Page 28709 (CP28709)LCSTREAMFMT_IBMCP28709

IBM EBCDIC US/Canadian English (CP 37)LCSTREAMFMT_IBMCP37

HP Traditional Chinese (LaserJet)LCSTREAMFMT_HPROC

HP Simplified Chinese (LaserJet)LCSTREAMFMT_HPPRC

HP Korean (LaserJet)LCSTREAMFMT_HPKOREA

HP Kana (LaserJet)LCSTREAMFMT_HPKANA

HP Japanese (LaserJet)LCSTREAMFMT_HPJAPAN

HP Thai (LaserJet)LCSTREAMFMT_HPTHAI

HP Arabic (LaserJet)LCSTREAMFMT_HPARABIC

HP Hebrew (LaserJet)LCSTREAMFMT_HPHEBREW

HP Turkish (LaserJet)LCSTREAMFMT_HPTURKISH

HP Greek (LaserJet)LCSTREAMFMT_HPGREEK

HP Roman (LaserJet)LCSTREAMFMT_HPROMAN

ISO Latin-5 Southern European (CP 920)LCSTREAMFMT_IBMCP920

ISO Latin-5 Southern European (ISO-8859-9)LCSTREAMFMT_ISO88599

ISO Hebrew (CP 916)LCSTREAMFMT_IBMCP916

ISO Hebrew (ISO-8859-8)LCSTREAMFMT_ISO88598

ISO Greek (CP 813)LCSTREAMFMT_IBMCP813

ISO Greek (ISO-8859-7)LCSTREAMFMT_ISO88597

ISO Arabic (CP 1008)LCSTREAMFMT_IBMCP1008

ISO Arabic (ISO-8859-6)LCSTREAMFMT_ISO88596

ISO Cyrillic (CP 915)LCSTREAMFMT_IBMCP915

ISO Cyrillic (ISO-8859-5)LCSTREAMFMT_ISO88595

ISO Latin-4 Northern European (ISO-8859-4)LCSTREAMFMT_ISO88594

ISO Latin-3 Southern European (ISO-8859-3)LCSTREAMFMT_ISO88593

ISO Latin-2 Eastern European (CP 912)LCSTREAMFMT_IBMCP912

ISO Latin-2 Eastern European (ISO-8859-2)LCSTREAMFMT_ISO88592

ISO Latin-1 US, Western European (CP 819)LCSTREAMFMT_IBMCP819

ISO Latin-1 US, Western European(ISO-8859-1)

LCSTREAMFMT_ISO88591

ASCIILCSTREAMFMT_ASCII

ASCIILCSTREAMFMT_ISO646

MS-DOS PC Japanese NEC Shift-JIS (CP 932)LCSTREAMFMT_NECESJIS



continued

Macintosh Oriya (Script 12)LCSTREAMFMT_MACSCRIPT12

Macintosh Gujarati (Script 11)LCSTREAMFMT_MACSCRIPT11

Macintosh Gurmukhi (Script 10)LCSTREAMFMT_MACSCRIPT10

Macintosh Devanagari (Script 9)LCSTREAMFMT_MACSCRIPT9

Macintosh Right-left symbol (Script 8)LCSTREAMFMT_MACSCRIPT8

Macintosh Cyrillic (Script 7)LCSTREAMFMT_MACSCRIPT7

Macintosh Greek (Script 6)LCSTREAMFMT_MACSCRIPT6

Macintosh Hebrew (Script 5)LCSTREAMFMT_MACSCRIPT5

Macintosh Arabic (Script 4)LCSTREAMFMT_MACSCRIPT4

Macintosh Korean (Script 3)LCSTREAMFMT_MACSCRIPT3

Macintosh Traditional Chinese (Script 2)LCSTREAMFMT_MACSCRIPT2

Macintosh Japanese (Script 1)LCSTREAMFMT_MACSCRIPT1

Macintosh Roman (Script 0)LCSTREAMFMT_MACSCRIPT0

Windows Korean (CP 1363)LCSTREAMFMT_IBMCP1363

Windows Baltic (CP 1257)LCSTREAMFMT_IBMCP1257

Windows Arabic (CP 1256)LCSTREAMFMT_IBMCP1256

Windows Hebrew (CP 1255)LCSTREAMFMT_IBMCP1255

Windows Turkish (CP 1254)LCSTREAMFMT_IBMCP1254

Windows Greek (CP 1253)LCSTREAMFMT_IBMCP1253

ANSILCSTREAMFMT_ANSI

Windows ANSI (CP 1252)LCSTREAMFMT_IBMCP1252

Windows Cyrillic (CP 1251)LCSTREAMFMT_IBMCP1251

Windows Eastern European (CP 1250)LCSTREAMFMT_IBMCP1250

IBM EBCDIC Latin-1 Open Systems (CP 1047)


IBM EBCDIC Danish, Norwegian (CP 277)LCSTREAMFMT_IBMCP277

IBM EBCDIC International (CP 500)LCSTREAMFMT_IBMCP500

IBM EBCDIC French (CP 297)LCSTREAMFMT_IBMCP297

IBM EBCDIC Japanese (Katakana) (CP 290)LCSTREAMFMT_IBMCP290

IBM EBCDIC UK (CP 285)LCSTREAMFMT_IBMCP285

IBM EBCDIC Spanish, Latin American (CP 284)


IBM EBCDIC Italian (CP 280)LCSTREAMFMT_IBMCP280

IBM EBCDIC Finnish, Swedish (CP 278)LCSTREAMFMT_IBMCP278



continued

Thai Industrial Standard (TIS620-2529)LCSTREAMFMT_TIS620

ISO Thai (ISO-8859-11)LCSTREAMFMT_ISO885911

MS-DOS PC Thai (CP 874)LCSTREAMFMT_IBMCP874

MS Thai WindowsLCSTREAMFMT_THAI

Macintosh Roman variant — TurkishLCSTREAMFMT_MACSCRIPT0TURKISH

Macintosh Roman variant — RomanianLCSTREAMFMT_MACSCRIPT0ROMANIAN

Macintosh Roman variant — IcelandicLCSTREAMFMT_MACSCRIPT0ICELANDIC

Macintosh Roman variant — GreekLCSTREAMFMT_MACSCRIPT0GREEK

Macintosh Roman variant — CroatianLCSTREAMFMT_MACSCRIPT0CROATIAN

Macintosh un-interpreted symbols (Script 32)LCSTREAMFMT_MACSCRIPT32

Macintosh extended Arabic/Sindhi (Script 31)

LCSTREAMFMT_MACSCRIPT31

Macintosh Vietnamese (Script 30)LCSTREAMFMT_MACSCRIPT30

Macintosh EastEurRoman/Slavic (Script 29)LCSTREAMFMT_MACSCRIPT29

Macintosh Geez/Ethiopic (Script 28)LCSTREAMFMT_MACSCRIPT28

Macintosh Mongolian (Script 27)LCSTREAMFMT_MACSCRIPT27

Macintosh Tibetan (Script 26)LCSTREAMFMT_MACSCRIPT26

Macintosh Simplified Chinese (Script 25)LCSTREAMFMT_MACSCRIPT25

Macintosh Armenian (Script 24)LCSTREAMFMT_MACSCRIPT24

Macintosh Georgian (Script 23)LCSTREAMFMT_MACSCRIPT23

Macintosh Laotian (Script 22)LCSTREAMFMT_MACSCRIPT22

Macintosh Thai (Script 21)LCSTREAMFMT_MACSCRIPT21

Macintosh Khmer/Cambodian (Script 20)LCSTREAMFMT_MACSCRIPT20

Macintosh Burmese (Script 19)LCSTREAMFMT_MACSCRIPT19

Macintosh Sinhalese (Script 18)LCSTREAMFMT_MACSCRIPT18

Macintosh Malayalam (Script 17)LCSTREAMFMT_MACSCRIPT17

Macintosh Kannada/Kanarese (Script 16)LCSTREAMFMT_MACSCRIPT16

Macintosh Telugu (Script 15)LCSTREAMFMT_MACSCRIPT15

Macintosh Tamil (Script 14)LCSTREAMFMT_MACSCRIPT14

Macintosh Bengali (Script 13)LCSTREAMFMT_MACSCRIPT13



continued

IBM EBCDIC Cyrillic (CP 1025)LCSTREAMFMT_IBMCP1025

IBM EBCDIC US Text Subset (CP 1003)LCSTREAMFMT_IBMCP1003

IBM EBCDIC DCF (CP 1002)LCSTREAMFMT_IBMCP1002

MS-DOS PC Desktop Publishing (CP 1004)LCSTREAMFMT_IBMCP1004

MS-DOS PC Hebrew (CP 85)LCSTREAMFMT_IBMCP856

ANSI Standard Notation (ASN.1)LCSTREAMFMT_ASN1

Teletex T.50LCSTREAMFMT_T50

Teletex T.61LCSTREAMFMT_T61

DEC Nat’l Replacement Char — Swiss

LCSTREAMFMT_ DECNRCSWISS

DEC Nat’l Replacement Char — Swedish

LCSTREAMFMT_DECNRCSWEDISH

DEC Nat’l Replacement Char — Spanish

LCSTREAMFMT_DECNRCSPANISH

DEC Nat’l Replacement Char — Portuguese

LCSTREAMFMT_DECNRCPORTUGUESE

DEC Nat’l Replacement Char — Norwegian Danish

LCSTREAMFMT_DECNRCNORWEGIANDANISH

DEC Nat’l Replacement Char — Italian

LCSTREAMFMT_DECNRCITALIAN

DEC Nat’l Replacement Char — German

LCSTREAMFMT_DECNRCGERMAN

DEC Nat’l Replacement Char — French Canadian

LCSTREAMFMT_DECNRCFRENCHCANADIAN

DEC Nat’l Replacement Char — FrenchLCSTREAMFMT_DECNRCFRENCH

DEC Nat’l Replacement Char — FinnishLCSTREAMFMT_DECNRCFINNISH

DEC Nat’l Replacement Char — DutchLCSTREAMFMT_ DECNRCDUTCH

DEC National Replacement Char — UKLCSTREAMFMT_DECNRCUK

Lotus MultiByte Character Set (LMBCS)LCSTREAMFMT_LMBCS

Unicode Transformation Formats 8LCSTREAMFMT_UTF8

Unicode Transformation Formats 7LCSTREAMFMT_UTF7

Unicode (ISO 10646)LCSTREAMFMT_ISO10646

Unicode (IBM CP 1200)LCSTREAMFMT_IBMCP1200

Unicode (ISO 10646)LCSTREAMFMT_UNICODE



continued

IBM EBCDIC Cyrillic (CP 880)LCSTREAMFMT_IBMCP880

IBM EBCDIC Greek (CP 875)LCSTREAMFMT_IBMCP875

IBM EBCDIC Icelandic (CP 871)LCSTREAMFMT_IBMCP871

IBM EBCDIC Eastern Europe (CP 870)LCSTREAMFMT_IBMCP870

IBM EBCDIC Hebrew Character Set A (CP 803)


IBM EBCDIC Hebrew (CP 424)LCSTREAMFMT_IBMCP424

IBM EBCDIC Greek 183 (CP 423)LCSTREAMFMT_IBMCP423

IBM EBCDIC US, Canadian (English) (CP 395)


IBM EBCDIC UK, Australian, Hong Kong,Ireland, New Zealand (CP 394)


IBM EBCDIC Latin American (SpanishSpeaking) (CP 393)


IBM EBCDIC Spanish, Philippines (CP 392)LCSTREAMFMT_IBMCP392

IBM EBCDIC Portuguese (CP 391)LCSTREAMFMT_IBMCP391

IBM EBCDIC Japanese (Latin) (CP 390)LCSTREAMFMT_IBMCP390

IBM EBCDIC Italian, Swiss (CP 389)LCSTREAMFMT_IBMCP389

IBM EBCDIC French, Swiss (CP 388)LCSTREAMFMT_IBMCP388

IBM EBCDIC Finnish, Swedish (CP 387)LCSTREAMFMT_IBMCP387

IBM EBCDIC Danish, Norwegian (CP 386)LCSTREAMFMT_IBMCP386

IBM EBCDIC Canadian (French) (CP 385)LCSTREAMFMT_IBMCP385

IBM EBCDIC Brazilian (CP 384)LCSTREAMFMT_IBMCP384

IBM EBCDIC Belgian (CP 383)LCSTREAMFMT_IBMCP383

IBM EBCDIC Austrian, German, Switzerland (CP 382)


IBM EBCDIC International #5 (CP 361)LCSTREAMFMT_IBMCP361

IBM EBCDIC Portuguese (CP 282)LCSTREAMFMT_IBMCP282

IBM EBCDIC Japanese (Latin) (CP 281)LCSTREAMFMT_IBMCP281

IBM EBCDIC Brazilian (CP 275)LCSTREAMFMT_IBMCP275

IBM EBCDIC Belgian (CP 274)LCSTREAMFMT_IBMCP274

IBM EBCDIC Symbols Set 7 (CP 259)LCSTREAMFMT_IBMCP259

IBM EBCDIC International #1 (CP 256)LCSTREAMFMT_IBMCP256

IBM EBCDIC Hebrew Publishing (CP 1028)LCSTREAMFMT_IBMCP1028

IBM EBCDIC Turkish (CP 1026)LCSTREAMFMT_IBMCP1026



continued

Vietnamese VISCII 1.1 (VICSII)LCSTREAMFMT_VISCII

Vietnamese Quoted ReadableLCSTREAMFMT_VIQRI

OSI/JIS X 5003-1987 X.400 Japanese ISPLCSTREAMFMT_JP1TEXT

ISO Latin-6 (ISO-8859-10)LCSTREAMFMT_ISO885910

Windows Vietnamese (CP 1258)LCSTREAMFMT_IBMCP1258

IBM Code Page 720 (CP 720)LCSTREAMFMT_IBMCP720

Cyrillic Internet SupportLCSTREAMFMT_KOI8

Russian (CP 922)LCSTREAMFMT_IBMCP922

Replacement for Lithuanian (CP 921)LCSTREAMFMT_IBMCP921

Extended Unix Code — ChineseLCSTREAMFMT_EUCC

ISO-2022-KR switching: treated as EUCKLCSTREAMFMT_ISOKR

Extended Unix Code — KoreanLCSTREAMFMT_EUCK

Extended Unix Code — TaiwaneseLCSTREAMFMT_EUCT

Extended Unix Code — JapaneseLCSTREAMFMT_EUCJ

Japanese Information Standard 0208 (JIS 208)LCSTREAMFMT_JIS2

Content-Transfer-EncodingLCSTREAMFMT_BASE64

Latin chars (non-spacing accents) similar to T.61

LCSTREAMFMT_ISO6937

MS-DOS PC Baltic (CP 775)LCSTREAMFMT_IBMCP775


IBM Korean (CP 934)LCSTREAMFMT_IBMCP934

IBM Extended Korean (CP 944)LCSTREAMFMT_IBMCP944

Xerox CJKLCSTREAMFMT_XEROXCJK

Chinese Character Code for InformationInterchange (Taiwan)

LCSTREAMFMT_CCCII

Japanese Information Standard 0201 (JIS 201)LCSTREAMFMT_JIS

East Asian Character Code Set (ANSI Z39.64-1989)

LCSTREAMFMT_EACC

IBM Traditional Chinese (CP 1386)LCSTREAMFMT_IBMCP1386

IBM Traditional Chinese (CP 1383)LCSTREAMFMT_IBMCP1383

IBM GB = GB + Hanzi (CP 1381)LCSTREAMFMT_IBMCP1381

IBM Taiwanese (CP 938)LCSTREAMFMT_IBMCP938

IBM Extended Taiwanese (CP 948)LCSTREAMFMT_IBMCP948

IBM EBCDIC Turkish (CP 905)LCSTREAMFMT_IBMCP905



continued

IBM EBCDIC PRC (simplified) Chinese Mixed (CP 931)


IBM EBCDIC Japanese Latin Kanji Mixed (CP 939)


IBM EBCDIC Taiwan (traditional) Chinese Mixed (CP 937)




IBM EBCDIC Korean Mixed (CP 933)LCSTREAMFMT_IBMCP933

IBM EBCDIC Japanese Katakana Kanji Mixed (CP 930)


TCVN3 Vietnamese (VCSII-3)LCSTREAMFMT_TCVN3

TCVN3 Vietnamese (VCSII-3)LCSTREAMFMT_VISCII3

IBM EBCDIC Devnagiri (CP 1137)LCSTREAMFMT_IBMCP1137

ISO Devnagiri (CP 806)LCSTREAMFMT_IBMCP806

IBM EBCDIC Code Page 1133 (CP 1133)LCSTREAMFMT_IBMCP1133









IBM EBCDIC Arabic (CP 420)LCSTREAMFMT_IBMCP420

IBM EBCDIC SBCS Japanese Latin —extended (CP 1027)


IBM EBCDIC SBCS PRC (simplified) Chinese(CP 836)


IBM EBCDIC SBCS Korean — extended (CP 833)


IBM EBCDIC SBCS Thai (CP 9030)LCSTREAMFMT_IBMCP9030

IBM EBCDIC SBCS Thai (CP 838)LCSTREAMFMT_IBMCP838

TCVN Vietnamese Graphic (VCSII-2)*/LCSTREAMFMT_VISCII2

TCVN Vietnamese Orthographic (VCSII-1)LCSTREAMFMT_VISCII1



IBM Simplified Chinese EUC (CP 1383)LCSTREAMFMT_IBMCP1383

IBM EBCDIC DBCS PRC (CP 1388X)LCSTREAMFMT_IBMCP1388X

IBM EBCDIC DBCS PRC (simplified)Chinese (CP 931X)

LCSTREAMFMT_IBMCP931X

IBM EBCDIC DBCS Japanese (CP 939X)LCSTREAMFMT_IBMCP939X

IBM EBCDIC DBCS Taiwan (traditional) Chinese (CP 937X)


IBM EBCDIC DBCS PRC (simplified)Chinese (CP 935X)


IBM EBCDIC DBCS Korean (CP 933X)LCSTREAMFMT_IBMCP933X

IBM EBCDIC DBCS Japanese (CP 930X)LCSTREAMFMT_IBMCP930X

IBM EBCDIC DBCS PRC (simplified)Chinese (CP 837)


IBM EBCDIC DBCS Taiwan (traditional) Chinese (CP 835)


IBM EBCDIC DBCS Korean (CP 834)LCSTREAMFMT_IBMCP834

IBM EBCDIC DBCS Japanese (CP 300) LCSTREAMFMT_IBMCP300

IBM EBCDIC Japanese Latin Kanji Mixed(CP 5035)


IBM EBCDIC Japanese Katakana Kanji Mixed (CP 5026)






Appendix EAdditional Scripting Capability for LEI

This appendix provides information about additional methods and proper-ties provided for LEI with the LCSession class that expand on the LC LSX.

Additional Scripting for LEIThere are additional properties and methods provided for LEI with theLCSession class that expand on the LC LSX.

The additional LCSession properties are as follows:

Long. Set this property to an LCFAIL_xxx code to instructLC to ignore this type of error.

IgnoreError

Long. Set this property to an LCFAIL_xxx code to instructLC to treat this error as an “event”. When the error occurs, itdoesn’t generate an error condition, merely assigns thesession status. Set to LCSUCCESS to clear this property.

EventError

String.CharacterSet

Long.TextFormat

String. The session name specified in the argument to New.Name

DefinitionProperty

The additional LCSession methods are as follows:

• AddProperty

• GetCommand

• GetProperty

• GetProperty<Type>

• ListProperty

• LookupProperty

• Log

• LogEx

• LogText

• LogTextEx

323

• RunActivity

• SetProperty

• SetProperty<Type>

Expanded LCSession FunctionalityLEI expands the LCSession Class functionality with properties not availablefor non-LEI users. The LCSession class also provides additional methods tosupport activity-level properties and logging. The additional features of theLotus Connector Classes for LEI are only available when used in conjunc-tion with LEI and the LEI Administrator.

The use of the LEI Administrator and logging is determined when theLCSession class object is created. LEI Scripted activities require that the firstLotus Connector Class object created be an LCSession object.

When an LEI Scripted Activity is run, all the property fields of the activityform are accessible in the script. Additionally, when a Scripted Activity isused in conjunction with the LEI CGI program and an HTML form, theform’s field values appear in the session object as read-only properties.

LCSession properties may be accessed through several techniques.

• After creating the LCSession object, you may specify the property. Forexample, if session is the name of a LCSession object and CharacterSetis a property of the session, session. CharacterSet is the value of theitem. When using the Notes LotusScript development environment, thedebugger displays all session properties when inspecting variables.

• You can use the GetProperty and SetProperty methods of LCSession toaccess the property as an LCField object.

• You can use GetProperty<type> and SetProperty<type> to access theproperty as a specific data type.

LEI requires that you also provide a name for every session and the name ofan existing Connection Document. You must specify Dim LCSession as anamed session (this becomes the default log document name). LCConnec-tions must be dimensioned as existing named Connection Documents thathave been created in the LEI Administrator.

Example statement syntax is shown below:

Uselsx "*lsxlc"

Sub Initialize



Dim MyNotesConnection as New LCConnection(:MyNotesConn")

Dim MyOracleConnection as NewLCConnection(:MyOracleConn")

In the above example, “MyNotesConnection” and “MyOracleConn” areassumed to be existing named Connection Documents in the LEI Adminis-trator. When writing LC LSX scripts for LEI, LCSession must be named.This name is used as the default log document name. Named sessionsenable support of LEI activity log documents.

AddProperty Method for LCSessionThis method creates a new property and assigns it a property token.

Defined InLCSession Class

SyntaxtokenID = lcSession.AddProperty (propertyName, storageType

Parameters

Long. Optional. One of the following:

LCPROPSTORE_STATIC —This value is read from or written tothe activity document.

LCPROPSTORE_DYNAMIC —This value will only exist duringthis run.

LCPROPSTORE_SYSTEM — This value is read from and writtento operating system environment variables.

System properties are not persistent across executions.

storageType

String. Name of the property to be created. The name must beunique among properties of this storage type. Using the samename as an existing property creates a new token if the storagetype differs, but simply returns the previously assigned token ifthe storage type is the same.

propertyName


Return Value

Long. Token assigned to the property. The token is only valid forthis run of the activity. The token will be a value between thehighest token defined by the activity itself and the maximumbase token value, 65535.

tokenID

DescriptionValue

Appendix E: Additional Scripting Capability for LEI 325

CommentAny added properties are in addition to the properties defined by an activ-ity. There are three types of properties which may be added. Static proper-ties will be stored in the activity document itself in the LEI Administratordatabase, and their values may be retrieved for future executions of thesame activity. Dynamic properties are defined only for the current execu-tion of the activity, and are discarded when the activity terminates. Systemproperties are represented by operating system environment variables, andany retrieval or assignment of values immediately alters the environmentvariable’s value.

GetProperty Method for LCSessionThis method obtains a copy of the current value for an activity property.


SyntaxSet destField = lcSession.GetProperty(propertyToken)

Parameters

Long. Token representing the activity property. See Appendix Bfor a list of tokens or use ListProperty method to find thecurrently available values.

propertyToken


Return Value

LCField. The value of the session property whose token ispropertyToken. The properties and methods of LCField can alsobe used to obtain information about the property, such as itsdataType and (using GetFormatStream) maximum length.

destField

DescriptionValue


Option Declare

Uselsx :*lsxlc"

Sub Initialize

Dim lses As New Lcsession(:SessionNameHere")

Dim result As Long, propObj As Variant


Dim pToken As Long, dType As Long, pFlags As Long, pNameAs String

result = lses.ListProperty(LCLIST_FIRST, pToken, dType,pFlags, pName)

Do While result

Set propObj = lses.GetProperty(pToken)

Print pName & { = } & projObj.Text(0) & {,datatype=} & dtype & _ {, flags=} & pFlags

result = lses.ListProperty(LCLIST_NEXT, pToken,dType, pFlags, pName)

Loop

End Sub

Example OutputName = SessionNameHere, datatype=6, flags=4

TextFormat = 82, datatype=1, flags=4

CharacterSet = IBMCP1252, datatype=6, flags=4

EventError = 0, datatype=1, flags=0

IgnoreError = 0, datatype=1, flags=0

AgentName = SA2, datatype=6, flags=0

AgentServer = Boo, datatype=6, flags=0

AgentDatabase = LCSamples2.nsf, datatype=6, flags=0

GetProperty<Type> Method for LCSessionThe GetProperty<Type> methods return a session property value as aspecific data type. Supported data types are Boolean, Currency, Datetime,Float, Int, Numeric, and Text.

This method allows retrieval of session properties as withLCSession.GetProperty, but does not require a field object. If the propertyvalue is of a different type, data conversion will be performed.



Syntaxflag = lcSession.GetPropertyBoolean(propertyToken, default)

Set destCurrency = lcSession.GetPropertyCurrency(propertyToken)

Set destDatetime = lcSession.GetPropertyDatetime(propertyToken)

destFloat = lcSession.GetPropertyFloat(propertyToken)

destInt = lcSession.GetPropertyInt(propertyToken)

Set destNumeric = lcSession.GetPropertyNumeric(propertyToken)

Set destStream = lcSession.GetPropertyStream(propertyToken, streamFormat)

Parameters

(GetPropertyStream only) Format that the stream is converted tobefore being returned. If streamFormat is zero, no conversionoccurs and the stream is copied in the same format as theproperty value.

streamFormat

(GetPropertyBoolean only) Value to be returned if the propertycannot be located. Default value is FALSE.

default

A token identifying the session property. See Appendix B for alist of tokens.

propertyToken


Return Values

Current value for the session property.dest<Type>

(GetPropertyBoolean only) Boolean value, either TRUE orFALSE. If the property does not exist, the default is returned.

flag

DescriptionValue

ListProperty Method for LCSessionThis method lets you retrieve information about each of the propertiessupported by the Session. Information about one property is returned witheach call to ListProperty.


Syntaxflag = lcSession.ListProperty(list, propertyToken, dataType, propertyFlags,propertyName)


Parameters

String, output. Optional. Name of the property.propertyName

Long, output. Optional. Property flags for the property. Nonedefined at this time. Value is always zero.

propertyFlags

Long, output. Optional. Data type of the property.dataType

Long, output. Optional. Token assigned to the property. SeeAppendix B for a list of tokens

propertyToken

Long. Constant indicating whether to return the first or nextsession property.


LCLIST_NEXT — Return the next property (or the first propertyif this is the first call to this method for this session).

list


Return Value

Boolean. True if information about a property was fetched, Falseif there were no more properties to list.

flag

DescriptionValue

ExampleUselsx :*lsxlc"

Option Declare

Sub Initialize

Dim ses As New Lcsession(:Salad")

' Must supply session name for scripted activity.

Dim more As Variant, token As Long, dtype As Long

Dim flags As Long, pname As String, propFld as LCField

more = ses.Listproperty(LCLIST_FIRST, token, dtype, flags,pname)

Do While more

Set propFld = ses.GetProperty(token)

Print pname & : = " & ses.Getproperty(token).Text(0)

more = ses.Listproperty(LCLIST_NEXT, token, dtype, flags,pname)

Loop


End Sub

Example OutputName = Salad

TextFormat = 82

CharacterSet = IBMCP1252

EventError = 0

IgnoreError = 0

LookupProperty Method for LCSessionThis method determines if the specified property has been defined in theactivity.


Syntaxflag = lcSession.LookupProperty (propertyToken, dataType, propertyFlags,propertyName)

Parameters

String. Optional. The name of the property.propertyName

Long, output. Optional. The property flags from the following list.

LCPROPERTYF_CONNECT — Property is used for connecting.

LCPROPERTYF_BOOLEAN — Property is a Boolean value.

LCPROPERTYF_READONLY — Property is read-only.

LCPROPERTYF_TEXTLIST — Property is a text list.

propertyFlags

Long, output. Optional. The property data type.dataType

Long. A token identifying the session property. See Appendix B fora list of tokens.

propertyToken


Return Value

TRUE or FALSE, indicating whether the property is supported forthis session.

flag

DescriptionValue


Log Method for LCSessionThis method adds a new entry to the log for this activity.

Use LCSession.Log to log LEI errors for which the error codes are definedby LEI. This Log function logs a basic error or event; use LogEx forextended logs and LogText or LogTextEx for external logs. When loggingan error, the activity status is set, placing the activity into an error state. Thelog text corresponding to the status code is added to any Log entry for thisactivity.


SyntaxlcSession.Log (status)

Parameters

Long. LEI status code to log. Most status codes are errors; thoseORed with the flag LCSTATUSF_EVENT are considered non-errorevents.

status


LogEx Method for LCSessionThis method adds a new extended entry to the log for this activity. Thevalues supplied are a status code, such as you would supply to the Logmethod, plus various additional parameters that supply additional information about the particular error code being returned.


SyntaxlcSession.LogEx (status, int1,int2, int3, text1, text2, text3)


Parameters

String. Optional Extended parameters. See Usage below.text3



Long. Optional Extended parameters. See Usage below.int3



Long. Base LEI status code and also the return value from thefunction. This value will show up as the external code number inthe session status.

status


UsageThis Log method logs an extended error or event with parameters; use Logfor basic logs and LogText or LogTextEx for external logs. When logging anerror, the activity status is set, placing the activity into an error state. Thelog text corresponding to the status code is added to any Log entry for thisactivity.

Each of the supported extended errors is described below along with theextended intN and textN parameters used by that error. For instance, if youare logging the error code LCFAIL_INVALID_METADATA, you shouldsupply the metadata name that was found to be invalid, in the text1parameter.

continued

PropertyToken (Int1), PropertyToken(Int2)

LCFAIL_PROPERTY_CONFLICT

PropertyToken (Int1)LCFAIL_MISSING_PROPERTY

FieldName (text1)LCFAIL_MERGE_FIELD

FieldName (text1), ExpectedType (Int1),ActualType (Int2)

LCFAIL_FIELD_TYPE

FieldName (text1), LinkType (Int1)LCFAIL_STAMPFIELD_TYPE

LCCount (Int1), LinkCount (Int2)LCFAIL_KEY_COUNT_MISMATCH

LCCount (int1), LinkCount (Int2)LCFAIL_FIELD_COUNT_MISMATCH

Metadata (text1)LCFAIL_DUPLICATE

FieldName (text1), LCType (Int1),ConnectorType (Int2)

LCFAIL_TYPE_MISMATCH

Metadata (text1)LCFAIL_INVALID_METADATA

DescriptionValue


Character Set Descriptor (text1)LCEVENT_CHARACTER_SET

PropertyToken (Int1)LCFAIL_PROPERTY_VALUE

PropertyToken (Int1)LCFAIL_INVALID_PROPERTY

DescriptionValue

The following status values are in the error package LCXPKG_EXFIELD.All of these take a single extended parameter, which is the field name, inText1:

LCFAIL_OVERFLOW

LCFAIL_PRECISION_LOSS

LCFAIL_INVALID_INT

LCFAIL_INVALID_FLOAT

LCFAIL_INVALID_CURRENCY

LCFAIL_INVALID_NUMERIC

LCFAIL_INVALID_DATETIME

LCFAIL_INVALID_STREAM

LCFAIL_INVALID_FIELD

LCFAIL_INVALID_TYPE

LCFAIL_INVALID_KEY

LCFAIL_DUPLICATE_KEY

LCFAIL_INVALID_STAMPFIELD

LCFAIL_INVALID_FIELDNAME

LCFAIL_VIRTUAL_FIELD

LCFAIL_VIRTUAL_VALUE

LCFAIL_INVALID_ORDER

LogText Method for LCSessionThis method adds a new external entry to the log for this activity.

This Log method logs an external basic error or event; use LogTextEx forexternal extended logs and Log or LogEx for LEI errors. When logging anerror, the activity status is set, placing the activity into an error state. Amessage is composed from the external text and code, and is added to anyLog entry for this activity. Use the method to log external errors from data


providers when LEI does not have the error message available. Obtain theerror code and text for an external error message, and call LogText to addthat information to the LEI log. The LEI error code used for this type oferror is LCFAIL_EXTERNAL, which is the same value returned by themethod for error logs.


SyntaxCall lcSession.LogText(logFlags, text, externalCode)

Parameters

Long. External logcode. Use zero if you have no particular code toreport.

externalCode

String. External log text.text

Long. Flags which affect this log entry. Zero or more of thefollowing values are ORed together:

LCLOGSTREAMF_EVENT Log a non-error event.

logFlags


ExampleCreate an LEI Scripted Activity that runs the script below. LCStream text iswritten to the Scripted Activity log.

Option Public

Uselsx :*lsxlc"

Sub Initialize

'create the New LCSession and New LCStream Objects

Dim myTestLog As New LCSession (:LogTest")

Dim myTextString As New LCStream

Dim x As Integer

Dim y As Integer

Dim z As Integer

myTextString.text = :LEI 3.2 Script Example UsingLCStream"

x=1 ' For loop start value

y=1 ' Counter start value

z=10 ' For loop end value


'write entries to the Scripted Activity log

For x% = 1 To z

Call myTestLog.Logtext (LCLOGSTREAMF_EVENT,myTextString.text & : — Log Entry_"&Cstr(y), 0)

y=y+1

Next

End Sub

LogTextEx Method for LCSessionThis method adds a new external extended entry to the log for this activity.

This Log method logs an external extended error or event; use LogText forexternal basic logs and Log or LogEx for LEI errors. When logging an error,the activity status is set, placing the activity into an error state. A message iscomposed from the external text, code, and additional parameters, and isadded to any Log entry for this activity.


SyntaxlcSession.LogTextEx(logFlags, text, externalCode, int1, int2, int3, text1, text2,text3)

Parameters

String. Optional extended parameters. See Usage below.text3



Long. Optional extended parameters. See Usage below.int3



Long. External log code.externalCode

String. External log text. See Usage below.text

Long. Flags which affect his long entry.

LCLOGSTREAMF_EVENT Log a non-error event.

logFlags



UsageThe text in text for extended logs contains parameter substitution markerswhich indicate placement and formatting of extended parameters. Thesesubstitution markers are of the format “[[Lcxx]]”, where “xx” can be any ofthe following values:

In Integer value, from parameter Int<n>

Tn Type constant LCTYPE_XXX, from parameter Int<n>

Pn Property token, from parameter Int<n>

On Object constant LCOBJECT_XXX, from parameter Int<n>

Sn Stream text, from parameter text<n>

X Stop indicator if all extended parameters are zero/null/empty

X( Left bound to remove if next parameter is zero/null/empty

X) Right bound to remove if next parameter is zero/null/empty

The method of variable substitution allows for relatively complex multiple-parameter log text, as well as grammar variations between languages. Thefollowing examples are the actual LEI resources for three extended statusvalues to demonstrate how this formatting is used:

“Type mismatch[[LCX(]] for field’[[LCS1]]’[[LCX)]][[LCX(]]; LEI:[[LCT1]][[LCX)]][[LCX(]], Database:[[LCT2]][[LCX)]]”

LCFAIL_TYPE_MISMATCH

“Metadata object [[LCX(]]’[[LCS1]]’[[LCX)]]does not exist”.

LCFAIL_INVALID_METADATA

“Duplicate object[[LCX]] ’[[LCS1]]’”.LCFAIL_DUPLICATE

DescriptionValue

RunActivity Method for LCSessionThis method causes one or more LEI activities to be executed.


SyntaxCall thisSession.RunActivity (name, runFlags, stopDatetime)


Parameters

LCDatetime. Optional. If you run activities synchronously thenStopDateTime indicates the time at which this method will return ifthe activities are not yet complete.

stopDateTime

Long. Optional. Flags that affect how the activities run. Zero or moreof the following values ORed together:

LCACTRUNF_SYNCHRONOUSRuns the activity and any dependent activities synchronously. Inthis case, the function will return only when all activities in the listand their dependents have completed, or when stopDatetime hasbeen reached.

The flag value is 0X01.

runFlags

String. The name of the activity to run. Multiple activities may bespecified by separating each with a semicolon (;) within the string.

name


SetProperty Method for LCSessionThis method assigns the current value for an activity property.


SyntaxCall thisSession.SetProperty (propertyToken, srcField)

Parameters

LCField. New value for the session property. If the propertyvalue is of a different type than this field, then data conversionwill occur. The property value will be assigned from the firstvalue in the field.

srcField

Long. Token representing the session property for which thevalue is to be assigned. See Appendix B for a list of tokens.

propertyToken


SetProperty<Type> Method for LCSessionThe SetProperty<Type> methods assign a property value as a specific datatype. Supported data types include Boolean, Currency, Datetime, Float, Int,Numeric, and Text.



SyntaxCall lcSession.SetPropertyBoolean(propertyToken, srcBoolean)

Call lcSession.SetPropertyCurrency(propertyToken, srcCurrency)

Call lcSession.SetPropertyDatetime(propertyToken, srcDatetime)

Call lcSession.SetPropertyFloat(propertyToken, srcFloat)

Call lcSession.SetPropertyInt(propertyToken, srcInt)

Call lcSession.SetPropertyNumeric(propertyToken, srcNumeric)

Call lcSession.SetPropertyStream(propertyToken, srcStream)

Parameters

LCStream. Value to assign to the session property.src<Type>

Long. Token identifying the session property. See Appendix Bfor a list of tokens.

propertyToken



AAction method

LCConnection class, 36Add method

LCCurrency class, 91LCNumeric class, 192

AddProperty methodLCSession(LEI LSX)

class, 321Adjust method

LCDatetime class, 105Alternate Metadata

defined, 7Append method

LCStream class, 227Arrays

described, 21Attachments

accessing Notes, 281storing in relational

databases, 118

CCaches

in LSX, 23Call method

LCConnection class, 38Catalog method

LCConnection class, 40Character

sort order in LEI ReplicationActivity, 309

Character setsOracle 7 notes.ini setting, 307Oracle 8 notes.ini setting, 307setting with DECS initialization

variables, 27setting with LEI initialization

variables, 25supported in LEI and

DECS, 309using as native in LEI

and DECS, 308

Clear methodLCDatetime class, 106LCStream class, 227

ClearStatus methodLCSession(LC LSX) class, 199

ClearVirtualCode methodLCField class, 120

Codevirtual, 118

Codepage, 309Compare method

LCCurrency class, 92LCDatetime class, 107LCField class, 121LCNumeric class, 193LCStream class, 228

Connect methodLCConnection class, 45

Connection pooling, 16, 17Connections

caching, 23pooling, 15querying, 12

Connector propertiescommon tokens for, 269described, 273identification tokens for, 271

Connector property tokensdescribed, 269

Convert methodLCField class, 123LCStream class, 230

Copy methodLCConnection class, 46LCCurrency class, 93LCDatetime class, 108LCField class, 124LCFieldlist class, 159LCNumeric class, 194LCStream class, 231

CopyRef methodLCFieldlist class, 162

Create methodLCConnection class, 47

Credentials, 17

DData types

described, 19DatetimeListGetRange method

LCStream class, 237DatetimeListGetValue method

LCStream class, 238DatetimeListInsertRange method

LCStream class, 240DatetimeListInsertValue method

LCStream class, 241DatetimeListRemoveRange method

LCStream class, 242DatetimeListRemoveValue method

LCStream class, 243Disconnect method

LCConnection class, 50Domino Connectors

caching, 23File System connector

properties, 284, 288Notes connector properties, 274ODBC connector properties, 289OLE DB connector properties, 298Oracle 7 connector properties, 292Oracle 8 connector properties, 295software requirements, 6supported by LSX, 5Sybase connector properties, 304

EError messages

connector-related, 255described, 253field-specific, 264general, 254improving content, 11that supply parameters, 261

Execute methodLCConnection class, 53

Extract methodLCStream class, 232

339

Index

FFetch method

LCConnection class, 54Fieldlists

accessing with arrays, 21accessing with parameters, 22mapping, 153merging, 153virtual, 153

Fieldsvirtual, 118

File System data sourceconnector properties, 284, 288

GGetCurrency method

LCField class, 125GetDatetime method

LCField class, 126GetDiff method

LCDatetime class, 109GetField method

LCFieldlist class, 163GetFieldlist method

LCField class, 127GetFloat method

LCField class, 129GetFormatDatetime method

LCField class, 130GetFormatNumber method

LCField class, 131GetFormatStream method

LCField class, 132GetInt method

LCField class, 133GetName method

LCFieldlist class, 165GetNumeric method

LCField class, 134GetProperty method

LCConnection class, 58LCSession(LEI LSX) class, 322

GetProperty<Type> methodLCConnection class, 59LCSession(LEI LSX) class, 323

GetStatus methodLCSession(LC LSX) class, 200

GetStatusText methodLCSession(LC LSX) class, 202

GetStream methodLCField class, 135

IIncludeField method

LCFieldlist class, 166Indexes

described, 21Insert method

LCConnection class, 63LCFieldlist class, 168

International text characters, 307IsNull method

LCField class, 136

LLanguages

supported in LEI and DECS, 309LC API

connection pooling, 17LC LSX classes

described, 8LC LSX environment

loading, 6LC LSX libraries

registering, 6LCConnection class, 29

data types, 30methods, 32properties, 30

LCCurrencyused with LCFieldlistand

LCField, 95LCCurrency class, 89

data types, 90methods, 90properties, 90

LCDatetime class, 101data types, 102methods, 102properties, 103

LCField class, 113data types, 116methods, 114properties, 115

LCFieldlist class, 151data types, 152methods, 154properties, 156

LCNumeric classdata types, 190methods, 190properties, 190

LCSession class, 197LC LSX methods, 198

LEI LSX additional features, 320LEI LSX methods, 319properties, 197

LCStream class, 221data types, 222properties, 224

LEI LSX classesdescribed, 8

LEI LSX environmentloading, 6, 320naming sessions, 6, 320

LEI LSX librariesregistering, 6, 320

LEI LSX sessionslogging with LCSession class, 320

lei.ini, 308LEI.INI variables

described, 25List method

LCFieldlist class, 170ListConnector method

LCSession(LC LSX) class, 203ListMetaConnector method

LCSession(LC LSX) class, 207ListProperty method

LCConnection class, 66LMBCS, 309Log method

LCSession(LEI LSX) class, 327LogEx method

LCSession(LEI LSX) class, 327LogText method

LCSession(LEI LSX) class, 329LogTextEx method

LCSession(LEI LSX) class, 331Lookup method

LCFieldlist class, 172LookupConnector method

LCSession(LC LSX) class, 211LookupMetaConnector method

LCSession(LC LSX) class, 215LookupProperty method

LCConnection class, 69LCSession(LEI LSX) class, 326

LookupVirtualCode methodLCField class, 138

Loopscoding tips, 25

LotusScript Extensions. See LSXlanguage, 5

LSX classesdescribed, 8

LSX codeoptimizing with tight loops, 25


LSX languageconnecting using, 12data types, 19described, 5modes, 15usage example, 10

MMap method

LCFieldlist class, 173Merge method

LCFieldlist class, 178LCStream class, 233

MergeVirtual methodLCFieldlist class, 181

Metadatadefined, 7

Multi-value dataaccessing with parameters, 22assigning arrays to, 21

NNew method

LCConnection class, 33LCCurrency class, 90LCDatetime class, 104LCField class, 119LCFieldlist class, 156LCNumeric class, 191LCSession(LC LSX) class, 199LCStream class, 225

Notes attachmentsstoring in relational

databases, 281Notes data source

connector properties, 274invalid connector property

combinations, 281notes.ini

Oracle Connector charactersettings, 307

NumberListGetRange methodLCStream class, 244

NumberListGetValue methodLCStream class, 245

NumberListInsertRange methodLCStream class, 246

NumberListInsertValue methodLCStream class, 247

NumberListRemoveRange methodLCStream class, 248

NumberListRemoveValue methodLCStream class, 249

OODBC data source

connector properties, 289OLE DB data source

connector properties, 298Oracle 7 data source

connector properties, 292Oracle 8 data source

connector properties, 295

PParameters

accessing multiple rows of datawith, 22

how LSX handles, 23Performance

enhancing, 15, 23

RRemove method

LCConnection class, 70LCFieldlist class, 182

ResetFormat methodLCStream class, 234

Result Setdefined, 7

RunActivity methodLCSession(LEI LSX) class, 332

SSelect method

LCConnection class, 74SetConstant method

LCDatetime class, 111SetCurrency method

LCField class, 139SetCurrent method

LCDatetime class, 112SetDatetime method

LCField class, 140SetFieldlist method

LCField class, 141SetFloat method

LCField class, 142SetFormat method

LCStream class, 236SetFormatDatetime method

LCField class, 143SetFormatNumber method

LCField class, 144

SetFormatStream methodLCField class, 146

SetInt methodLCField class, 147

SetName methodLCFieldlist class, 186

SetProperty methodLCConnection class, 78LCSession(LEI LSX) class, 333

SetProperty<Type> methodLCConnection class, 79LCSession(LEI LSX) class, 333

SetVirtualCode methodLCField class, 149

Sleep methodLCSession(LC LSX) class, 218

Sort Orderfor characters in LEI, 309

Subtract methodLCCurrency class, 94LCNumeric class, 195

Sybase data sourceconnector properties, 304

TText

international character sets, 307Text translations

supported character sets in LEIand DECS, 309

TextListFetch methodLCStream class, 250

TextListInsert methodLCStream class, 251

TextListRemove methodLCStream class, 251

Timestamp, 285Tokens

defined, 8for common connector

properties, 269for connector identification

properties, 271for File System connector

properties, 284, 288for Notes connector

properties, 274for ODBC connector

properties, 289for OLE DB connector

properties, 298for Oracle 7 connector

properties, 292

Index 341

for Oracle 8 connector properties, 295

for Sybase connector properties, 304

Trim methodLCStream class, 236

UUnicode, 309Update method

LCConnection class, 83Uselsx, 16

VVirtual code

creating, 118setting for Notes connector, 282

Virtual fieldlistscreating, 153

Virtual fieldsin Notes, 282interpreting, 118merging, 153

WWeb sites

DECS, 4, 5LEI, 5PTFs, 5

Writeback Result Setdefined, 8

YY2K settings

default DECS initializationvariables, 27
