LotusScript for Visual Basic Programmers

To view this page ensure that Adobe Flash Player version 9.0.124 or greater is installed.

Please login or register to make a comment!

International Technical Support Organization LotusScript forVisual Basic Programmers redbook title 12498 8/12/96 11:45 AM Page 1 Edition Notice First Edition (August 1996) This edition applies to Release 4 of Lotus Notes. Comments may be addressed to: IBM Corporation, International Technical Support Organization Dept. HZ8 Building 678 P.O.

Box 12195 Research Triangle Park, NC 27709-2195 When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. © International Business Machines Corporation 1996. All rights reserved.

Note to U.S. Government Users: Documentation related to restricted rights. Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Abstract This redbook describes how to work with LotusScript, a BASIC-like, object-oriented programming language that comes as part of Lotus Notes Release 4 and other Lotus products. The introductory chapter compares LotusScript and Visual Basic. Other chapters cover Lotus Notes as an OLE 2 automation server and OLE 2 automation client.

A description of the LotusScript Notes classes is also provided. The redbook focuses on how to convert HiTest applications, and how to access the major Notes elements using: The HiTest Basic API ... more. less.

Notes classes in Visual Basic through OLE automation LotusScript in Notes. This redbook was written for Visual Basic programmers who want to learn about the features of LotusScript, and who are planning to migrate their HiTest applications. Some knowledge of the HiTest Basic API and of Visual Basic is assumed. iii Edition Notice.............ii ..... Abstract.................iii ..... Preface..................ix ..... 1 LotusScript and Visual Basic: A Comparison....... 1 ..... History........................ 1 ....... LotusScript................... 2 ....... Visual Basic.................. 2 ....... Programming Model Differences.... 2 ....... Language Syntax Comparison...... 4 ....... Other References.............. 4 ....... Data Types................... 5 ....... Operators.................... 8 ....... Commands..................... 8 ....... File I/O...................... 9 ....... Other Recent Language Additions. 10 ...... Error Handling................ 10 ...... On...GoSub................... 11 ...... Conditional Compilation........ 12 ...... MessageBox.................. 13 ...... Constants .................... 13 ...... Errors, Error Constants.......... 13 ...... Extending the Code............... 15 ...... Application Programming Interface Calls...................... 15 ...... Other Interesting LotusScript Commands................ 18 ...... Other Interesting Visual Basic Commands................ 19 ...... Object-Oriented Programming (OOP) 19 ...... Visual Basic Class Modules...... 21 ...... LotusScript Notes Classes ....... 21 ...... CreateObject, GetObject......... 26 ...... Mail Enabling................... 26 ...... Code Sharing Concerns............ 27 ...... Close but Different............. 27 ...... Control Arrays................ 29 ...... Visual Basic Environment Constants 29 ...... 2 The Notes Integrated Development Environment.. 31 .... Introduction.................... 31 ...... Elements of the Forms Integrated Development Environment.... 32 ...... Main Design Window.......... 32 ...... Action Pane.................. 33 ...... Design Pane.................. 34 ...... Working with the Script Editor...... 38 ...... Special Script Editor Features..... 38 ...... Error Checking................ 40 ...... Testing the Form............... 40 ...... Debugging LotusScript.......... 40 ...... 3 LotusScript Notes Classes45 .... The Database (back_end) Classes.... 47 ...... NotesACL.................... 48 ...... NotesACLEntry............... 48 ...... NotesAgent................... 50 ...... NotesDatabase................ 51 ...... NotesDateRange............... 55 ...... NotesDateTime................ 56 ...... NotesDbDirectory............. 57 ...... NotesDocument............... 58 ...... NotesDocumentCollection....... 62 ...... NotesEmbeddedObject.......... 64 ...... NotesForm................... 65 ...... NotesInternational............. 66 ...... NotesItem.................... 67 ...... NotesLog.................... 68 ...... NotesName................... 70 ...... NotesNewsletter............... 71 ...... NotesRichTextItem............. 72 ...... NotesSession.................. 73 ...... Contents v Contents NotesTimer................... 76 ...... NotesView................... 76 ...... NotesViewColumn............. 79 ...... Notes UI (front_end) Classes....... 79 ...... NotesUIWorkspace............ 80 ...... NotesUIDocument............. 80 ...... NotesUIDatabase.............. 84 ...... NotesUIView................. 84 ...... 4 Lotus Notes as an OLE 2 Automation Server......... 85 .... Using Notes Classes in Visual Basic through OLE Automation..... 85 ...... Declaring Notes Classes in Visual Basic 90 ...... Using the Notes Class Hierarchy in Visual Basic................ 90 ...... Error Handling.................. 95 ...... Compile Errors................ 95 ...... Run-time Errors............... 95 ...... Logic Errors.................. 97 ...... 5 Converting HiTest Applications.............. 99 .... Creating a Notes Application Using the HiTest Basic API............ 1 00 ..... Converting a HiTest Application Using Notes Classes in Visual Basic through OLE Automation..... 1 03 ..... Converting a HiTest Application to LotusScript in Notes......... 1 07 ..... 6 Accessing Notes Sessions113 ... Accessing Notes Sessions Using the HiTest Basic API............ 1 13 ..... Accessing Notes Session Properties1 14 ..... Accessing Notes Session Environment Values......... 1 15 ..... Accessing Notes Sessions in Visual Basic Using Notes Classes through OLE Automation..... 1 16 ..... Accessing Notes Session Properties1 18 ..... Accessing Notes Session Environment Values......... 1 19 ..... Accessing Notes Sessions in LotusScript................. 1 20 ..... 7 Accessing Notes Databases123 ... Accessing Notes Databases Using the HiTest Basic API............ 1 23 ..... Accessing Notes Database Properties1 23 ..... Opening and Closing a Database..1 25 ..... Creating a Notes Database.......1 25 ..... Accessing Notes Databases in Visual Basic Using Notes Classes through OLE Automation..... 1 26 ..... Accessing Notes Database Properties1 27 ..... Opening and Closing a Database..1 28 ..... Creating a Notes Database.......1 30 ..... Accessing Notes Databases in LotusScript................. 1 30 ..... Accessing Notes Database Properties1 30 ..... Opening and Closing a Database..1 31 ..... Creating a Notes Database.......1 32 ..... 8 Accessing Notes Views ... 135 ... Accessing Notes Views Using the HiTest Basic API............ 1 35 ..... Accessing Notes View Attributes..1 35 ..... Locating a View...............1 37 ..... Deleting a View ...............1 37 ..... Other Functions in HiTest for Working with Views......... 1 38 ..... Accessing Notes Views and Folders in Visual Basic Using Notes Classes through OLE Automation..... 1 38 ..... Accessing Notes View Properties..1 39 ..... Locating a View...............1 40 ..... Deleting a View...............1 40 ..... Accessing Notes Folders.........1 41 ..... Accessing Notes Views and Folders in LotusScript................. 1 42 ..... 9 Accessing Notes Documents............... 145 ... Accessing Notes Documents Using the HiTest Basic API............ 1 45 ..... Accessing the Document Properties1 46 ..... Creating a Document...........1 48 ..... Removing a Document..........1 49 ..... Copying a Document...........1 49 ..... Other Functions to Work with Documents................. 1 50 ..... vi LotusScript for Visual Basic Programmers Accessing Notes Documents in Visual Basic Using Notes Classes through OLE Automation..... 1 50 ..... Accessing the Document Properties1 52 ..... Creating a Document ...........1 53 ..... Removing a Document..........1 53 ..... Copying a Document...........1 54 ..... Accessing the Current Document..1 54 ..... Accessing Notes Documents in LotusScript................. 1 56 ..... Accessing the Document Properties1 56 ..... Creating a Document...........1 58 ..... 10 Accessing Notes Items...161 ... Accessing Notes Items (Fields) Using the HiTest Basic API......... 1 61 ..... Items........................1 61 ..... Fields.......................1 61 ..... Attachments..................1 62 ..... CDRecord....................1 62 ..... Composites...................1 62 ..... Copying an Item...............1 62 ..... Deleting an Item...............1 65 ..... Accessing Notes Items (Fields) in Visual Basic Using Notes Classes through OLE Automation..... 1 65 ..... Copying an Item...............1 67 ..... Deleting an Item...............1 68 ..... Accessing Notes Items (Fields) in LotusScript................. 1 69 ..... 11 Using Notes as an OLE 2 Automation Client: Creating Objects.................. 171 ... Creating an Embedded Object......1 71 ..... Embedding Part of a File in a Document................. 1 71 ..... Embedding an Entire File in a Document................. 1 74 ..... Embedding a New Object in a Document................. 1 75 ..... Creating a Linked Object...........1 76 ..... Linking Data to a Notes Document1 77 ..... Creating an Embedded Object Using LotusScript................. 1 78 ..... Embedding an Entire File in a Document................. 1 78 ..... Embedding a New Object in a Document................. 1 82 ..... Creating a Linked Object Using LotusScript................. 1 84 ..... 12 Using Notes as an OLE 2 Automation Client: Managing Objects.................. 189 ... Editing an Embedded Object.......1 89 ..... Creating a View...............1 89 ..... Editing the Object..............1 91 ..... Editing a Linked Object ...........1 92 ..... Editing an Embedded or a Linked Object Using LotusScript...... 1 94 ..... Deleting an Embedded or a Linked Object Using LotusScript...... 1 96 ..... More Examples................1 98 ..... Appendix A HiTest and LotusScript Notes Classes: Comparing Functions...... 203 ... Appendix B Special Notices.211 ... Appendix C Related Publications.............. 213 ... International Technical Support Organization Publications..... 2 13 ..... How To Get ITSO Redbooks.215 ... How IBM Employees Can Get ITSO Redbooks.................. 2 15 ..... How Customers Can Get ITSO Redbooks.................. 2 17 ..... Index....................Index-1 Contents vii Preface This redbook describes how to work with LotusScript, a BASIC-like, object-oriented programming language that comes as part of Lotus Notes Release 4 and other Lotus products. The introductory chapter compares LotusScript and Visual Basic. Other chapters cover Lotus Notes as an OLE 2 automation server and OLE 2 automation client. A description of the LotusScript Notes classes is also provided. The redbook focuses on how to convert HiTest applications, and how to access the major Notes elements using: The HiTest Basic API Notes classes in Visual Basic through OLE automation LotusScript in Notes. This redbook was written for Visual Basic programmers who want to learn about the features of LotusScript, and who are planning to migrate their HiTest applications. Some knowledge of the HiTest Basic API and of Visual Basic is assumed. Note This redbook is available in HTML format and in Adobe Acrobat format on the World Wide Web. The URL is http://www.lotus.com/devtools. Also, the code samples provided throughout the book are available for your use on http://www.lotus.com/redbook. How This Redbook Is Organized This redbook is organized as follows: Chapter 1, cLotusScript and Visual Basic: A Comparison d This chapter describes the differences and similarities between Visual Basic Release 4 and LotusScript. Chapter 2, cThe Notes Integrated Development Environment d This chapter looks at the Integrated Development Environment (IDE) for creating and programming Notes forms, which is the most complex application development environment. ix Chapter 3, cLotusScript Notes Classes d This chapter discusses the LotusScript database classes and UI classes, how to access the classes, and the properties and methods of the classes. Chapter 4, cLotus Notes as an OLE 2 Automation Server d This chapter describes how to develop Notes applications in Visual Basic using the Notes classes. Chapter 5, cConverting HiTest Applications d This chapter describes how to convert HiTest applications using the original HiTest code directly in Notes Release 4, using Notes classes in Visual Basic through OLE automation, and using LotusScript in Notes. Chapter 6, cAccessing Notes Sessions d This chapter discusses how to access Notes sessions in HiTest, using Notes classes through OLE automation in Visual Basic, and using LotusScript in Notes. Chapter 7, cAccessing Notes Databases d This chapter discusses how to access Notes databases in HiTest, using Notes classes through OLE automation in Visual Basic, and using LotusScript in Notes. Chapter 8, cAccessing Notes Views d This chapter discusses how to access Notes views and folders in HiTest, using Notes classes through OLE automation in Visual Basic, and using LotusScript in Notes. Chapter 9, cAccessing Notes Documents d This chapter discusses how to access Notes documents in HiTest, using Notes classes through OLE automation in Visual Basic, and using LotusScript in Notes. Chapter 10, cAccessing Notes Items d This chapter discusses how to access Notes items in HiTest, using Notes classes through OLE automation in Visual Basic, and using LotusScript in Notes. Chapter 11, cUsing Notes as an OLE 2 Automation Client: Creating Objects d This chapter describes how to create embedded and linked objects in a Notes document manually and using LotusScript. x Chapter 12, cUsing Notes as an OLE 2 Automation Client: Managing Objects d This chapter describes how to edit and update an embedded or linked object in a Notes document both manually and using LotusScript. Appendix A, cHiTest and LotusScript Notes Classes: Comparing Functions d This appendix lists equivalent functions in HiTest and LotusScript. The Team That Wrote This Redbook This redbook was produced by a team of specialists from around the world working at the International Technical Support Organization Cambridge Center. This project was designed and managed by: Marion Bergner-Hawker International Technical Support Organization, Cambridge, MA USA The authors of this document are: Stella Yuan IBM China Benjamin Sondakh IBM Indonesia Bill Shadish Fundamental Objects, Inc. bills@fo.com This redbook is the result of a residency conducted at the International Technical Support Organization, Cambridge, MA USA. Thanks to the following people for the invaluable advice and guidance provided in the production of this redbook: Alex Neihaus Notes Product Marketing, Lotus Development David Rosenbaum Notes Product Management, Lotus Development Gary Devendorf Notes Product Management, Lotus Development Graphic Services Lotus Development xi Comments Welcome We want our redbooks to be as helpful as possible. Should you have any comments about this or other redbooks, please send us a note at the following address: redbook@vnet.ibm.com. Your comments are important to us! xii Chapter 1 LotusScript and Visual Basic: A Comparison This chapter describes the differences and similarities between Visual Basic Release 4 and LotusScript, which comes as part of Lotus Notes Release 4 and other Lotus products, such as Word Pro, Freelance, and Approach. We will compare the syntactical language portions of LotusScript and Visual Basic. We will also look at the environments that these languages work within. Visual Basic relies on the Visual Basic design environment, access to external controls and host applications such as Excel. LotusScript relies on Notes, Word Pro and other Lotus products to provide the user interface it needs to operate within. So, while the primary focus will be on the syntax, we will often explain the advantages gained by using these external tools with both LotusScript and Visual Basic. Some of the topics covered are: A syntactical language comparison The programming model of each language The Object-Oriented development characteristics of each External objects; such as servers, controls, components that add to the language. History Microsoft released Visual Basic in 1989, but the language has actually been in use since the 1960s. In fact, there are now many versions of BASIC available, with implementations found in tools such as Powerbuilder, ToolBook, Visual Basic and Lotus Notes Release 4. Prior to Release 4 of Notes, Lotus applications used a macro command language as the method of development. While this macro language is fairly robust in power, professional developers have come to prefer a more powerful development language. 1 LotusScript With Lotus Notes Release 4 and other Lotus desktop applications in SmartSuite, Lotus has added LotusScript as a version of BASIC that can be used to extend the functionality of the applications and to integrate with other software. This is actually Release 3 of LotusScript. Lotus had released LotusScript Release 1 in Improv, with Release 2 appearing in Lotus Forms and Notes ViP, an earlier development tool created to interoperate with Notes. (Notes ViP is now developed and marketed exclusively by Revelation Technologies, Inc. as Revelation ViP for Lotus Notes.) The ViP version of BASIC was the first to truly implement Object-Oriented Programming (OOP) features, much of which has been carried forward into the current version of LotusScript. The implementation of LotusScript within Lotus Notes delivers an impressive combination of workgroup capabilities, programming environment and the standard reporting and database features necessary for application development. This chapter will use Lotus Notes to describe user interface features and LotusScript in the comparison to Visual Basic. Visual Basic There are three versions of Visual Basic: VBScript, VBA and VB. VBScript is the object-enabling language that is used within Web browsing tools to allow objects to be loaded, change their properties and react to changes (events) within the objects. VBA is a superset of VBScript, providing interaction with Microsoft 9s application tools. Visual Basic is a full development tool that provides reporting, database interoperation and screen design. Programming Model Differences There are some differences in the general flow of using LotusScript when compared to Visual Basic. Some of the more salient points are: Interface Tools Used Visual Basic (the package) supplies the ability to create user interface elements, like forms and dialog boxes. LotusScript depends upon Notes or the containing Lotus application to provide the actual user interface. Visual Basic allows you to create run time, royalty-free applications. These applications are distributed as pseudo-compiled modules and interpreted before being executed, at run time. LotusScript currently works within Lotus Notes and Smart Suite and is distributed to users of those applications. Note that LotusScript cscripts d are in fact compiled. 2 LotusScript for Visual Basic Programmers Object-Oriented Terminology LotusScript uses the term cclass d to describe the ccontract d defining the properties, methods and potentially the events related to an object. Microsoft uses the term object in this case and uses Class to describe underlying low-level language constructs. LotusScript has the term Inheritance in its vocabulary 4 Visual Basic does not. Screen flow Notes screens flow in a manner similar to a script-enabled help file, within one form replacing several windows of a traditional, dialog-based application. A good deal of information (potentially screens 9 worth) is often placed onto one form in Notes. This differs from the one main screen with supporting dialogs approach used by Visual Basic. One major reason for the single-screen approach is that a large amount of information can be placed onto the screen and then cscrolled d or graphically navigated to, as opposed to the more traditional dialog-box presentation of the data. A second major reason is that the data is then relatively flexible when presented into different screen resolutions or even different operating system environments. Presentation actually becomes more an issue of style and user training than one way being necessarily better than the other. This is something that will take a little getting used to from the design side as well as the eventual usage of your application. Control Placement When designing your screens in Notes, you will place controls in positions relative to other controls or text on the screen. Rather than worrying about finite twip or pixel level placement, you will just put a button to the right of the prior button or to the left of the button that comes next. Notes handles the final placement of the control, to resolve potential cross-platform resolution dependencies that occur when you specify the coordinate system within your application itself. If you really want to decide where things sit on the screen, you can add spaces or tabs between fields and controls to change the presentation of the controls. OLE 2 Support Notes will allow you to place OLE 2.0 controls on the screen. As of Notes Release 4.1, Notes is a full OCX container. For example, events are not handled in exactly the same way and it is more difficult to change the properties of existing controls. Lotus is working on a Component Software Development Kit (SDK) to enable OLE control developers to create controls within Notes. This SDK will also allow Chapter 1: LotusScript and Visual Basic: A Comparison 3 you to react to events generated within these controls, in the same way as other OLE2 containers do now. Structure With Release 4 of Lotus Notes, both LotusScript and VisualBasic operate within the same type of development environments. Each has a layer to present and retrieve information to the user and an underlying layer to store this information. With Release 4 of Notes, Lotus has added the LotusScript programming layer to bind together the Lotus applications packages as well as to increase the ability to use other packages with Notes as well, via OLE Automation. Language Syntax Comparison This section contains a comparison of the statements and functions making up LotusScript and Visual Basic. Other References This section covers the low-level syntactical language differences between LotusScript and Visual Basic. Much of the material in this section will be covered at a level just high enough to explain the basic concepts involved. If you wish to read more about the language specifics, see the LotusScript Language Reference (also available within the Notes Help database) and the LotusScript Programmer 9s Guide. The LotusScript manuals are available as a documentation pack from Lotus: they are not packaged inside Notes boxes. See the Visual Basic 4.0 Language Reference for more on the Visual Basic language. The respective web sites of Lotus (http://www.lotus.com/devtools) and Microsoft (http://www.microsoft.com) will offer the most up-to-date material and announcements about each language and their supporting tools. 4 LotusScript for Visual Basic Programmers There are many good examples of how to extend the use of LotusScript by adding LotusScript Notes classes found in the Notes Programmer 9s Guide, Part 1 - Chapter 4. Data Types The data types supported under LotusScript and Visual Basic are very similar. Typeless or Typed variables Declaring the type of data that a variable holds is not strictly a requirement in the typeless, variant data type declarations possible in both LotusScript and Visual Basic. While you are able to specify what type of data a variable holds, in both languages you can also reserve a 16-byte piece of storage by simply using the variable without a type. You then assign the ctype d of data for this variable whenever you first load actual data into the variable. For example in the first block of code, you 9ll notice that UserID is used without first being declared. Dim rc' dim a return code as variant UserID = "Bob Sands"' a variant is created and 'typed' ' as a string" rc = Int(UserID) ' this will fail at run time since ' since UserID is now a string; which ' is an invalid parm for Int( ). whereas the following code will both work and will actually catch the error at design time when compiled, not just at run time: Dim rc' dim a return code as variant Dim UserID#' a double is created UserID = 22.34 ' rc = Int(UserID)' this will work as expected. UserID = "Bill Sands"' and this will be caught at design ' time. Chapter 1: LotusScript and Visual Basic: A Comparison 5 Both LotusScript and Visual Basic provide a statement which, when entered in the general declarations sections of the code, will force the developer to explicitly declare the type of data of a variable when declared. The LotusScript equivalent of Visual Basic 9s Option Explicit is Option Declare , which forces the developer to declare all variables before they are used. Data Type LS VBSuffixStorage SizeRangeNotes Byte X none1 byte0 to 255 Integer XX %2 bytes-32,768 to 37,767 Long (long integer) XX &4 bytes-2,147,483,648 to 2,147,483,647 Short integer (2 byte whole number). In 32-bit Windows , VB4 represents a n int with a 4 byte number. Single (floating point) XX !4 bytes-3.402823E38 to -1.401298E-45 or negative values; 1.401298E-45 to 3.402823E38 for positive values. Double (floating point) XX #8 bytes-1.79769313486232E308 to -4.94065645841247E-324 for negative values; 4.94065645841247E-324 to 1.79769313486232E308 for positive values. Currency (scaled integer) XX @8 bytes-922,337,203,685,477.5808 to 922,337,203,685,477.5807. String XX $2 bytes per character* 10 bytes + string length 0 to approximately 2 billion (approximately 65,400 for Microsoft Windows versio n 3.1 and earlier) Variant XX none16 bytes user-defined XX none As determined by its elements Date X none8 bytesJanuary 1, 100 to December 31, 9999 Boolean X n/a2 bytesTrue or False 6 LotusScript for Visual Basic Programmers LotusScript only allows arrays and lists up to 64k in size. Providing a way around this restraint should provide a nice after-market for Lotus add-in component builders. Visual Basic and LotusScript support UNICODE strings. Unicode allow you to handle complex languages such as Japanese and Chinese using DBCS (double-byte, or more, character set) encoding. These languages require more than one byte of storage to represent all possible language characters. However, this requires the allocation of an extra byte (or more) of storage for each one desired by the programmer. This also requires separate sets of functions to csee d the number of bytes or characters expected. For example: LEN ( str$ ) Returns the number of characters in a string, or the number of bytes used to hold a numeric value. LENB ( str$ ) Determines the length of a string in bytes rather than in characters. The following code demonstrates the difference in returning byte counts or character counts for a string. Notice that the numeric expression returns 4 bytes (the size allocated for a single data variable) in each case. Dim s As Single Dim strTemp As String * 20 strTemp$ = "hello" s = 12345 Msgbox(Format$(Len(s))) ' returns 4 Msgbox(Format$(Len(strTemp$))) ' returns 20 Msgbox(Format$(Lenb(s))) ' returns 4 Msgbox(Format$(Lenb(strTemp$))) ' returns 40 Defining Default Variables Both LotusScript and Visual Basic provide a way to determine default ranges for integer and other variable types. For example, saying DefInt a-z in your code will result in single letter variables from a to z being ctyped d as integers when used, even if not explictly declared with dim x as integer or dim x% statements in your code. You can set up one-character variables to automatically represent the other basic datatypes, thereby avoiding possible portability problems when writing your code. For example, DefCur defines Currency variables in the same way DefInt defines Integer variables. Chapter 1: LotusScript and Visual Basic: A Comparison 7 DefCur A-D sets the characters A, B, C and D to be typed as currency data types automatically. As with DefInt, subsequent reference to A through D will be treated as currency types. Notice that character settings are case sensitive; A-Z and a-z represent two possible sets of variables that can be defined through these DefType statements. Collections Collections is a Visual Basic Release 4 addition that allows you to set up array-like constructs; it can hold multiple types of data elements including class-based objects that you create yourself. Collections is handy in Visual Basic and has a number of operations (such as .Add, .Delete, etc.) that can be performed directly against the collection, but collection processing can be somewhat slower than processing against more traditional array constructs. The Visual Basic Collection keyword is not supported in LotusScript. Using the line Dim myUsers as New Collection results in a cClass or type name not found: COLLECTION d message. LotusScript handles collections as a Notes class. Visual Basic collection-based code will need to be changed to array-based logic when ported to LotusScript. Operators Both Visual Basic and LotusScript share the same + - / * ^\ MOD operators, which have the same precedence. The Visual Basic XOR, AND, NOT, OR, EQV and IMP operators are also found in LotusScript and support bit-wise operations. Both languages provide the Like pattern-matching operator for use on strings. Commands LotusScript uses most of the same syntactical statements and structures that you will find in Visual Basic. A very short list of LotusScript supported statements and functions includes: Fix , FreeFile , GetObject , Hour , InStr , IsDate , Kill , LBound , Mid , Option Base , ReDim , Seek and Val . Now even returns the system date and time in the same format as Visual Basic. Both LotusScript and Visual Basic support multi-line statements, using the 8_ 9 character to end the line, preceded by white space. LotusScript uses the C-like %Rem...%End Rem statements to comment or uncomment more than one contiguous line at once. 8 LotusScript for Visual Basic Programmers File I/O Code such as the following, to open and convert an ASCII text file to UNIX format, works exactly the same in both LotusScript and Visual Basic: Dim i% Dim j% Dim strChar$ Dim lLOF As Long Dim iWinFilePtr% Dim iUnixFilePtr% ' ... skipping the read from input file in here... Open strFilename & ".htm" For Output _ Access Write As #iUnixFilePtr lLOF = LOF(iWinFilePtr%) For j% = 1 To lLOF strChar$ = Input(1, #iWinFilePtr%) If Asc(strChar$) = 13 Then Beep Else Print #iUnixFilePtr%, strChar$; End If Next j% Close iWinFilePtr% Close iUnixFilePtr% LotusScript and Visual Basic share the ability to Lock and Unlock files processed in this way. This ensures that the records you are trying to process are not overwritten by others while you are working on them. On a binary file, you can lock a record at a time. In an ASCII file, you lock and unlock the entire file at the same time. Lock Read, Lock Write, Lock Read Write are available in both Visual Basic and LotusScript as parameters to the Open statement, to control locking when initially opening a file. Chapter 1: LotusScript and Visual Basic: A Comparison 9 Other Recent Language Additions Recent VBA and VB4 syntactical enhancements have been included in the current release of LotusScript. Statements like With and ForAll are found in LotusScript. As an example, ForAll allows you to easily do something to every item within a LotusScript collection, such as a list or an integer array: dim iSalary(20) as integer forall x in iSalary x = x * 1.5 ' let 9s give them a raise they won 9t forget! end forall Other interesting statements include Datatype (variable) which returns the datatype associated with the object you pass it. Datatype is similar to Visual Basic 9s If TypeOf statement, but requires a lot less work. Note that the LotusScript End statement is not directly equal to Visual Basic 9s End . The End statement in LotusScript stops the currently executing script, and to exit the application in the way you would with Visual Basic 9s End , you generally use the appHalt function. If you are within Lotus Notes, you can use the Close macro to easily (and safely) shut the application down. Error Handling LotusScript provides the same type of error handling syntax as Visual Basic Release 4, allowing for Err, Erl, Error, Resume, Resume Next, On Error Goto label, and so on. For example, the following code can be used in both LotusScript and Visual Basic. Sub cmdUpdateDB_Click ( ) On Error GoTo cmdUpdateDBErr: ' process database updates here... Exit Sub cmdUpdateDBErr: ' The HandleErr( ) call provides a way to ' centralize your error processing. The code for ' the HandleErr call is shown in the ' object-oriented section below. If HandleErr(Err, Error$, _ 10 LotusScript for Visual Basic Programmers "frmMain::cmdUpdateDB_Click") then resume Else resume next EndIf End Sub The code for the HandleErr function is broken out and defined for you in the Object-Oriented programming section below. On...GoSub On...GoSub exists in both variations of Basic as well. On...GoSub allows you to jump (and later return from) different routines using a Select Case type of structure. All of the labels referenced must reside within the same procedure. On x% GoSub Label1, Label2, Label3 Label1: ' do stuff return Label2: ' do stuff return On...GoTo Chapter 1: LotusScript and Visual Basic: A Comparison 11 Conditional Compilation Conditional compilation provides a way for developers to code in platform or similarly specific sections of code, with only the code pertaining to the runtime platform actually being compiled when executed. The following LotusScript If statements, preceded by c% d character, are used for conditional compilation. %If %ElseIf %End If The above statements provide conditional compilation support and work in the same way as the #If ... #End If statements do within Visual Basic 4.0. You follow the %If or the %ElseIf with a constant that is provided by the language or declared explicitly by the developer. Visual Basic allows you to define your own constants using a #Const compiler directive. This allows you to add #If DEBUGGING type of logic in the application, providing a way to compile out all debugging code simply by removing a #Const DEBUGGING line. Otherwise, both LotusScript and Visual Basic come with preset constants to use with conditional compilation statements. Code written like this shows the Win32 and OS/2 conditional compilation constants in use: %If Win32 messageBox("Running on Win32") %ElseIf %If OS/2 messageBox("Running on OS/2") %End If %End If This will display a message box telling the user what platform the code is running on. The unreachable code is not executed at all. Lotus recognizes more platforms than Microsoft as being legitimate porting possibilities. Microsoft supports Win32 and Win16 as constants provided by the language. In LotusScript you will find compiler directives for almost everything from SOLARIS to OS/2. Lotus also adds the MAC as a real alternative to Win cxx d as well. Using LotusScript within Notes provides a way to build truly cross-platform, portable applications. The %If, %End If statements are not provided in Lotus Notes. 12 LotusScript for Visual Basic Programmers MessageBox Visual Basic developers will note the MessageBox statement in the preceding code. LotusScript defaults to using MessageBox rather than MsgBox, although the latter command actually works as well in Lotus Notes. Ported MsgBox statements will work, using the parameters specified for MessageBox. Visual Basic 9s message box statement adds support for two new parameters; a helpfile file name and helpcontext id. These are used to refer to a specific help topic within the named helpfile, if the user pushes F1 for help over the message box at run time. LotusScript allows you to make the MessageBox dialog an application modal or system modal dialog. With Visual Basic, it is always an application modal dialog. Constants Both LotusScript (with LTSSL30.LSS and LSCONT.LSS) and Visual Basic (WIN16API.TXT and WIN32API.TXT) provide a number of platform specific constants and Application Programming Interface (API) declarations in a standardized format. Visual Basic extends this idea by bundling a number of the constants into the development environment, providing several useful features: Teams do not have to guess at a naming sequence for constants as they add them to their projects. Code becomes easier to share. The space wasted by unused constants is eliminated. Examples of this include the vbHourglass and vbYesNo internal constants. Errors, Error Constants Both Visual Basic and LotusScript define constants that map to trappable internal error codes, that may occur at run time. Both languages allow you to handle system, OLE and data access errors using code-based error handling routines at run time. The Basic On Error statement provides the means to trap for these errors. Having both languages represent the same type of internal errors with the same numbers is an important step in being able to share code from one of the BASIC implementations to the other. As an example, a cDevice Unavailable d error occurs if your application tries to write to a drive that is not ready. This will happen if you try to copy files to the floppy A: drive without a diskette in this drive. Rather than simply displaying a system error message and ending the application, Visual Basic and LotusScript treat this as a trappable error, and each gives the developer Chapter 1: LotusScript and Visual Basic: A Comparison 13 the chance to deal with it by adding an error handler. If the developer does not add the error handler, the application will then display the system error message and most likely terminate the application. Visual Basic represents the Device Unavailable error with an internal number 68. LotusScript also represents this error with the internal number 68. Most of the system-oriented errors that are trappable errors in Visual Basic can be handled by LotusScript as well, using the same numbers. LotusScript provides an ASCII file LSERR.LSS, that defines the system errors it allows you to trap. Visual Basic provides a list of system, Access and OLE errors that it allows you to trap on as part of its online documentation. There is a general guideline to how the trappable errors are grouped. The Visual Basic error groupings are: 1-94System Errors 260-428 DDE or Form Errors 429-451OLE Automation Errors 444-521System Errors 2400-3622Data Access Errors 4000-Notes Container Errors 31000-31050OLE Container Errors Lotus maps a number of the trappable errors for you into constants declared in the LSERR.LSS file. A snippet of the errors defined within this file are shown in the following listing: 'Run Time LOI Errors Public Const ErrFileAlreadyExists = 58 Public Const ErrBadRecordLength = 59 Public Const ErrDiskFull = 61 Public Const ErrInputPastEndOfFile = 62 Public Const ErrBadRecordNumber = 63 Public Const ErrBadFileName = 64 Public Const ErrTooManyFiles = 67 Public Const ErrDeviceUnavailable = 68 14 LotusScript for Visual Basic Programmers Visual Basic provides the ability to Raise an error for an object, which allows you to handle the error through external applications or OLE servers. The code for this looks like this: object.Raise(Number, Source, Description, HelpFile, HelpContext) and works in a similar fashion to using the Error errNumber statement within Basic code. The system believes that the error has occurred once you issue the Error statement or .Raise method for an object, with all expected error traps enabled as well. Note that you can generate your own application-level errors in both Visual Basic and LotusScript, by using the Error statement with an unused error number. For example, if you have an appropriate On Error Goto trap in a section of code, the statement ERROR 147 will generate a user-defined error in both languages. In Visual Basic you 9ll receive the error string cApplication-Defined or Object-Defined Error d. In LotusScript the error message generated would be cUser-defined error d. This allows you to define errors that can be handled the same way, sharing the user-defined error numbers across multiple applications. Extending the Code Anyone developing complex applications knows that you will need more than just the BASIC language syntax itself, in order to add complex or custom processing to your program. Usually this means accessing the underlying environment 9s API calls, accessing external data engines or using the many custom controls available from third-party companies. Application Programming Interface Calls Using API calls allows you to extend your programming reach into the system-oriented functions, available in the underlying operating systems. Note that once you code an API call in a language like LotusScript or Visual Basic, you have added complexity as well as reliance on the presence of the underlying service. LotusScript and Visual Basic differ on how APIs are enabled in the respective languages . 32-bit issues An example of this can again be found in the WriteProfileString API call. In Windows 3.1x, this API call places a string into the WIN.INI ASCII parameter file. GetProfileString can be later used to retrieve the string. Chapter 1: LotusScript and Visual Basic: A Comparison 15 If you move your code to Win32 (Windows 95 or Windows NT) the API call no longer works. A new API call GetProfileStringA has been created to handle the UNICODE requirements of strings under the 32-bit platform. New Visual Basic Statements In its most recent release, Visual Basic now supports GetSetting, SaveSetting and DeleteSetting commands that provide access to the registry on a 32-bit platform (in order to save parameters) and to standard INI files on 16-bit platforms. Wrapper Examples Lotus provides LotusScript wrappers around a number of common APIs, such as the Win16 WriteProfileString , in an .LSS file called LTSSL30.LSS. If you desire to use the WriteProfileString, GetProfileInt, GetProfileString API calls directly in Visual Basic, you will need to provide wrapper functions similar to those provided in the Lotus LTSSL30.LSS file. ' 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 ' GetProfString ' This function returns a profile string from the specified ' ini file. If the filename passed is "", then the string will ' be searched for in the WIN.INI file ' 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 Public Function GetProfString(Section as String, Entry as String, Filename as String, DString as String) as String Dim retstr as String*256 Dim retval as Integer If filename = "" then retval = GetProfileString(Section, Entry, DString, retstr, 256) Else retval = GetPrivateProfileString(Section, Entry, DString, retstr, 256,Filename) End If GetProfString = Left$(retstr, retval) End Function 16 LotusScript for Visual Basic Programmers Lotus Components You can add Windows OCX controls into Lotus Notes today. They will visually react when clicked on, but you cannot easily react to events fired within the control itself. For example, you will see the arrow depress if you add a spin button to Notes and click on the arrow. But there is no easy way to add code to handle this event when it occurs. Lotus Components Software Development Kit (SDK) is the way Lotus will provide to support controls within Notes. The SDK enables you to build controls. Automation Servers Sub Click(Source As Button) Dim session As New NotesSession Dim db As NotesDataBase Dim doc As NotesDocument Set db = session.currentDatabase Set doc = New NotesDocument (db) doc.Form = "Memo" doc.Subject = "Look at the attached code for the " & _ "way to mail information within code ..." doc.Memo = "This code explains how to use " & _ "automation to create a mail message." Call doc.Send (False, "Shadish") End Sub Execute Text Execute allows you to create a temporary module, at run time, that executes and is released when done. Vertical bars | | or { } are used to allow the text to execute to span several lines. The Execute doc.txtScript line below pulls script from a text box (txtScript) on the form and executes it at runtime. Sub Click(Source As Button) Print "Starting Script" Dim ws As New NotesUIWorkspace Dim uidoc As NotesUIDocument Chapter 1: LotusScript and Visual Basic: A Comparison 17 Dim doc As NotesDocument Set uidoc = ws.CurrentDocument Set doc = uidoc.Document Execute doc.txtScript Print "Completed Script" End Sub Other Interesting LotusScript Commands The Width #filenumber, Width statement forces a set ASCII file width, with autowrap to the beginning of the next line when the width has been exceeded. The YIELD statement is equivalent to doEvents in Visual Basic 4. And the Yield statement requires a return value, unlike the doEvents in Visual Basic, but equivalent to Visual Basic 9s doEvents function. The TypeName (strFileName$) statement will return the word cSTRING d. This allows you to determine the datatype of a variable at run time, which is useful when you have passed variables that may contain any type of data in them. LotusScript cfeels d a little more like C++ than like BASIC sometimes. Beyond the standard BASIC keywords, LotusScript provides for additional syntax such as cDeclare ding a forward reference to a function or subroutine. This allows you to code and test the sub or function before it 9s actually included in your main app 4 something that 9s particularly useful in team development environments. Developers familiar with Object-Oriented programming will quickly find themselves creating and instantiating objects using new (constructors), delete (destructors), and data-hiding features you would expect to see in C++. On Event Click from <object> call <routine name> allows you to react to events happening in other Lotus products. For example, this would allow you to create a page-turning presentation to use in a Lotus Notes training application. Evaluate (Macro, object) allows you to easily call another (Lotus only) product macro. This allows you to pass a string of numbers to a spreadsheet to be totaled, etc. The % Include command gives you the ability to include LotusScript variable, constant and API declarations into your code from external ASCII files. This allows you to sort through all of the various files provided by 18 LotusScript for Visual Basic Programmers Lotus, creating a cut-down version that contains just the statements that you need. You can then add all of this to a new application with one line of code: % Include cMY-DEFS.LSS d . This behaves the same as if you were using <include mydefs.h> files in C or <include mydefs.hh> files in C++. The % Include command can only be used in the general declarations sections of an object; not within the event code itself. Uni ( strExp ) and UChr ( longValue ) functions work together like Visual Basic 9s Asc and Char statements, but for Unicode characters. Uni ( ) returns the Unicode numeric character code for the first character passed as the string parameter. UChr ( ) returns the character represented by the long number passed as an argument. Using the Print stringRef command in LotusScript by itself will place the string in the last message status bar area of Lotus Notes, as is shown in this figure. This makes for a useful display area when debugging your program and is a good place to drop critical run time messages if you are writing code for agents, monitors or other background tasks. Other Interesting Visual Basic Commands Visual Basic supports Named and Optional parameters in its subs, functions and property procedures, allowing you to specify the parameters in any order and to choose which parameters you actually want to call the routine with. Visual Basic allows you to create OLE Servers (EXEs and DLLs in the 32-bit version). Object-Oriented Programming (OOP) Object-oriented (OO) development features include inheritance, polymorphism, data encapsulation and creating classes. Classes A class can be thought of as a template that can be used to create multiple instances of objects at run time. Each object contains its own copy of data, which can be changed via properties provided externally to the user (or Chapter 1: LotusScript and Visual Basic: A Comparison 19 developer). The objects also contain code, which is used to manipulate or inspect this data at run time. A very simple example might be to create a class to display a message. We 9ll do this in LotusScript by creating a class called DisplayMsg. In the following listing, the DisplayMsg class is shown, where you will see a property called Text and a method called Display . Class DisplayMsg ' Declare member variables in a LotusScript class mMsg As String mMsgNumber As Integer Public Property Set Text As String mMsg = Text End Property Public Sub Display Msgbox(mMsg) End Sub End Class The text for the class is entered into the declarations of a Notes form. The code in the next listing is entered into the Sub Click event of a button on this Notes form. Here you will see a variable created as a variant called objMsg, which will be used to hold the instance of our message object. The set objMsg = New DisplayMsg line actually creates the instance of the object and loads a reference of it into the objMsg variable. Sub Click (Source As Button) Dim objMsg as Variant Set objMsg = New DisplayMsg objMsg.Text = "(" & Format$(68) & ") - " & Error$(68) objMsg.Display Delete objMsg End Sub 20 LotusScript for Visual Basic Programmers Once you have created the object, you can set the text property by referring to it as object.property, or objMsg.Text in this case. You can cause the code in the Display method (function) to execute using the same process. While this is a simple example, you might easily imagine additional possibilities here. The message may actually be cdisplayed d on a pager, or logged to a database, all by adding more code to this basic structure. The mechanism to create the object, load its properties and call its methods remains the same. LotusScript will allow you to use most of the most important OO constructs, like: Building classes, Private and Public data within objects and instantiating an object (stored outside your application) from within a running application. LotusScript also supports single inheritance. LotusScript Notes classes support inheritance with the ability to create classes and then subclasses of objects . Note that the embedding product (in this case, Notes) exposes the products 9 functionality as a set of classes. It is these cproduct classes d that can be inherited into your own private classes. Visual Basic supports all of the object-oriented features above, with the exception of inheritance. Visual Basic Class Modules Visual Basic classes are handled through a new cclass d of code module, a .CLS file. The CLS file is called a Class file. Class files behave like .BAS code modules in structure. The code within the class is used by creating an object at run time and then referring to the object 9s methods and properties. Special code is executed when you create an instance of the object. Similar code is executed when you delete the object. Visual Basic classes have a Class object, which holds Class_Initialize and Class_Termination events. Whenever you create a new object, the initialization event is executed. When you delete an object, either by leaving the scope where the object was created or explicitly by saying Set objRef = Nothing , the termination event is executed. LotusScript Notes Classes Classes within LotusScript are added inline, directly within the code modules themselves. Like Visual Basic, LotusScript provides initialization and termination procedures within the classes; in this case, called Sub Delete and Sub New and Sub Delete. Like Visual Basic, code within these procedures is executed automatically. Sub New is executed whenever you create an object from the class. Sub Delete is executed whenever you destroy the object using the Lotus Delete object statement. Chapter 1: LotusScript and Visual Basic: A Comparison 21 The following example shows how to create and use a LotusScript class to create an error handling object. This will demonstrate the use of the HandleErr ( ) function in error processing. We 9ll show the class ErrObject, which will be used to hold and display errors. This code was ported from Visual Basic and the comments following the class describe the changes that were made to allow the port. This is followed by the actual HandleErr function call; that would be called by the code in our error-handling discussion earlier. Class ErrObject Private mErrLogFile As String Private mErrNumber As Long Private mErrMsg As String Private mErrLocation As String Private mErrLogMethod As Integer Private mErrSeverity As Integer ' change dim to private Public Property Get ErrMsg ErrMsg = mErrMsg End Property Public Property Get ErrNumber ErrNumber = mErrNumber End Property Public Property Set ErrNumber ' changed let to set mErrNumber = ErrNumber End Property Public Property Set ErrMessage ' changed let to set mErrMsg = ErrMessage End Property 22 LotusScript for Visual Basic Programmers Public Function PostError(ErrNumber As Variant, ErrLocation As Variant, LogMethod As Variant) As Integer ' pulled the optionals and boolean PostError = RESUME_NEXT_AFTER_ERR ' use object properties if parameters were ommitted. If Isempty(ErrNumber) Then ErrNumber = mErrNumber If Isempty(ErrLocation) Then ErrLocation = _ mErrLocation If Isempty(LogMethod) Then LogMethod = mErrLogMethod ' build the message. Note, DB, file output may differ ' slightly, as Date/Time, Err, etc may be written to ' separate columns (fields) mErrMsg = Error$(ErrNumber) & " (#" & _ Format$(ErrNumber) & ") " & "occurred at " & _ Format$(Now, "mm-dd-yy hh:mm:ss") _ & "; at location->" & ErrLocation & "." Select Case LogMethod Case LOG_DISPLAY_MESSAGE Beep Msgbox (mErrMsg) Case LOG_TO_DISK Dim iLogPtr% iLogPtr% = Freefile Open mErrLogFile$ For Append Access _ Write As #iLogPtr% Print #1, mErrMsg Chapter 1: LotusScript and Visual Basic: A Comparison 23 Close #iLogPtr% Case LOG_TO_DB ' not implemnented Case LOG_SEND_TO_PAGER ' not implemented Case LOG_SEND_EMAIL ' not implemented Case Else Msgbox (mErrMsg) End Select Select Case ErrNumber Case 5 ' invalid procedure call ErrSeverity = RECOVERABLE PostError = SHUTDOWN_AFTER_ERR Case 68 ' device not available (like when user ' accesses A: without a diskette. Show a ' message and then resume. ErrSeverity = SHUTDOWN_APP PostError = RESUME_AFTER_ERR Case Else ErrSeverity = RECOVERABLE PostError = RESUME_NEXT_AFTER_ERR End Select End Function End Class In moving the code from Visual Basic to LotusScript, we make the following slight modifications. 24 LotusScript for Visual Basic Programmers 1. Consts move out of the class into the scope of the object the class is in. 2. Dim statements within the class change to Private. 3.isMissing is not provided. Replace isMissing with isEmpty . 4. Optional arguments are not available. Replace Optional with explicit variable declarations. 5. For property functions, Set is used, rather than Let. Set does not have the special (but rarely used) object passing features that are present in Visual Basic. Function HandleErr (iErr%, strErrLocation$, iAction%) As Integer On Error Goto MetaErr Dim objErr Set objErr = New ErrObject rc = objErr.posterror (iErr%, strErrLocation$, iAction%) Delete objErr Exit Function MetaErr: ' An error here might come from a failure to create the object. Msgbox(Format$(Err) & ", " & Error$(Err)) Resume Next End Function The only real change in moving HandleErr from Visual Basic to LotusScript is that the object is destroyed explicitly with the Delete objErr statement. Notice that the MsgBox call comes across without change. Using HandleErr () results in a message box that looks like this: Chapter 1: LotusScript and Visual Basic: A Comparison 25 CreateObject, GetObject One advantage for both language dialects is that external OLE servers can be added into your applications using these statements. This exposes the full power of OLE automation servers, like Word Pro and Notes, to applications written in BASIC. Mail Enabling Fortunately, the ability to create and send e-mail is fairly easy in both LotusScript and Visual Basic. In LotusScript, to send a message in Notes requires the following type of code: Sub Click (source as Button)' a button to send info with... dim session as new NotesSession dim db as NotesDataBase dim doc as NotesDocument set db = session.currentDatabase set doc = new NotesDocument (db) doc.Form = "Memo" if txtSubject = "" then doc.Subject = "Here is a quick thought ..." else doc.Subject = txtSubject.text endif if txtMemo = "" then doc.Memo = "Example Text" else doc.Memo = txtMemo.text endif Call doc.Send (False, "Shadish") End Sub 26 LotusScript for Visual Basic Programmers In Visual Basic sending a message is equally easy, as a mail control is available that embodies much of the mail system 9s features. The following Visual Basic code demonstrates a MAPI-based mail transfer. If you wish to handle cc:Mail or pass through a generic VIM layer, to move mail from a Visual Basic system to a VIM-based system, third-party controls are also available to do this. After dropping the mail control on your form, enter this code behind the send button: Sub cmdSend_Click frmMain.MapiMess.Action = MESSAGE_COMPOSE frmMain.MapiMess.RecipDisplayName = Address$ frmMain.MapiMess.Action = MESSAGE_RESOLVENAME if txtSubject = "" then frmMain.MapiMess.MsgSubject = _ "Here is a quick thought ..." else frmMain.MapiMess.MsgSubject = txtSubject.text endif if txtMemo = "" then frmMain.MapiMess.MsgNoteText = "Example Text" else frmMain.MapiMess.MsgNoteText = txtMemo.text endif frmMain.MapiMess.Action = MESSAGE_SEND End Sub Code Sharing Concerns As far as the languages 9 syntax itself, this is not a major area of concern. Much of the code written for Visual Basic should be able to move relatively easily into LotusScript. There are some things that might need to be pointed out. Close but Different Obviously, the code associated to user interface elements will need to be reviewed and most likely rewritten. The way controls are handled in Lotus Chapter 1: LotusScript and Visual Basic: A Comparison 27 Notes differs significantly from Visual Basic. It is easier to change the properties of controls in Visual Basic when compared to LotusScript. Different Windows events are provided for the same controls and the names of these events are also sometimes different. For example, a button in Visual Basic has the following events: Click DragDrop DragOver GotFocus KeyPress KeyDown KeyUp LostFocus MouseDown MouseMove MouseUp In addition, you can cause the Visual Basic Button_Click event to execute by setting the implied .Value property of the button to true, as in cmdCancel = True . In LotusScript, the events provided for a button are: Click Terminate Initialize ObjectExecute Options Declarations Notice the ability to include declarations directly within an object, such as a button. 28 LotusScript for Visual Basic Programmers Where LotusScript commands and syntax are like Visual Basic 9s (for example, the %If ... %Endif as compared to the #If ... #End If conditional compilation commands), they will need to be converted, redone or not used in order to create code that is truly portable between Visual Basic and LotusScript. Unlike Visual Basic, LotusScript is not centered around the Properties, Methods, and Events metaphor. LotusScript is built around interacting with the objects provided within the respective host application and development tools provided by Lotus. For example, objects don 9t have Tags or Captions. A static text object uses a text property rather than a caption property to read and change its value. So any Visual Basic code that refers to captions for labels needs to be changed. Similarly, LotusScript doesn 9t support the tag property. But LotusScript does have a Name(variable) function that returns an item 9s name, which can then be used to operate on objects dynamically at runtime. Control Arrays LotusScript does not support control arrays or indexes on individual objects in the same way as Visual Basic. So your Visual Basic code that sets up an array of text objects with a common code routine 4 as with Sub txtAmtField_Click (amtIdx as index) 4 will need to be rewritten. Buttons under LotusScript are set up as individual buttons or to act as group or checkbox buttons when they are placed onto the screen. Visual Basic Environment Constants If you are using any of the new Visual Basic embedded constants, you will need to provide a translation file of codes for anything that you want to move to LotusScript. Or you can simply choose not to use the Visual Basic constants in the first place. For example, you might be using things like this in Visual Basic 4 applications now: If rc = vbYes or rc = vbAbort Then ' add processing here. EndIf You will need to add constant declarations for vbYes and vbAbort in code ported to LotusScript; otherwise the references to vbYes and vbAbort would prove invalid. Caution If you are not using Option Declare in your LotusScript or Option Explicit in your Visual Basic modules and move the code shown above, it may compile and give you erroneous results. Both vbYEs and vbAbort would be treated as uninitialized variables and both contain a 0. The code Chapter 1: LotusScript and Visual Basic: A Comparison 29 would execute but give incorrect results since you would always compare whatever the contents of rc was to zero. Const vbAbort = 3 Const vbRetry = 4 Const vbIgnore = 5 Const vbYes = 6 Const vbNo = 7 Summary It 9s probably safe to say that a lot of your Visual Basic calculation code will port across to LotusScript, but that your interface code will not move as easily. LotusScript is enough like Visual Basic 9s BASIC language implementation that you will have few problems porting code from one tool to the other 4 if you recognize these differences before building any code. With a little care, you will be able to easily create routines that can be called from either Visual Basic or LotusScript without change. The problem for the Visual Basic developer writing code to share with LotusScript will not be what cannot be moved into LotusScript. Rather, it will be in deciding not to use some of the appealing LotusScript extensions that are now available 4 like class inheritance, the include% features and some of the LotusScript Notes classes. 30 LotusScript for Visual Basic Programmers Chapter 2 The Notes Integrated Development Environment Introduction Lotus Notes provides a complete application development environment. A Notes application consists of several or all of the following: Forms 4 which provide the templates through which data in the application is entered and displayed. Unlike a traditional template, forms can also act on the data. For example, when a user inputs information in the form, the form might, depending on the contents, send an e-mail message to another user. Views and folders 4 which provide different ways of looking at all or part of your data, according to specified criteria. A view might be thought of as similar to a report in a traditional database program, except that the view is dynamic and includes links to information in the application. Navigators 4 which provide graphical means of moving between views. Agents 4 which add functi

less