Custom LotusScript Functions and Routines

This chapter provides a number of predeveloped LotusScript functions and subroutines. It provides a general exposure to the language for novice programmers as well as a quick implementation solution for experienced Domino programmers. The chapter includes a wide variety of enhancements and working source code that can be incorporated into the project databases in this book or any other Notes database. All the source code provided in this section is self-contained and designed to work with no additional code. This means the code can be plugged into virtually any application and implemented with little to no additional work.

All code provided in this section is also provided on the companion Web site in a code library database. Where feasible, working buttons can be clicked to illustrate the various solutions. As a result, the code (and in some cases the buttons themselves) can be copied directly into your database. However, before implementing any of the solutions, let's spend a moment discussing how the information for the section will be presented.

• As a general reminder, the Use LIBRARY statement must be added to the global section of the design element when utilizing code stored in a LotusScript library. The library and related subroutines and functions must be created prior to adding the Use statement to the form, view, agent, or other Domino element.
• Each module provided in this book is designed to work "as is." However, when integrating into an existing application, you may need to comment out or remove duplicate statements. In LotusScript, an object can only be declared once within the routine. If multiple declaration statements are present, you will receive a compile error when you try to save the Domino design element.

  All duplicate statements will subsequently be highlighted in red. To correct this, we recommend commenting out the duplicate statements using the single quote or REM statement and test the code. For example, the NotesDatabase object is commonly found in LotusScript routines. The following illustrates how to comment out a single statement in LotusScript.

  REM db as NotesDatabase ' DIM db as NotesDatabase

  You can also use %REM and %ENDREM to comment out a block of test statements.

  %REM Dim w As New NotesUIWorkspace Dim s As New NotesSession Dim db As NotesDatabase %ENDREM

  After you have verified that the LotusScript code is working as intended, delete the commented statements from the code. If there are a significant number of lines to be deleted, make a copy of the database for historical purposes before removing the extra statements from the design.

• In some cases, integration of code into the Notes database may require a reference to a database object such as a form name, field name, view name, or target search string. All items that must be replaced with actual design elements from your database are illustrated in all bold, capital letters. The following are the replacement keywords used throughout this chapter.

DATABASE.NSFSubstitute with a valid Lotus Notes database file name

EMAILSubstitute with a valid Internet email address or Notes name

FIELDSubstitute with an actual field name

FORMSubstitute with an actual form name

PATHSubstitute with a valid directory path or folder name

SEARCHSTRINGSubstitute with a text string

SERVERSubstitute with a valid Domino server name

VALUESubstitute with a text string or numerical value

VIEWSubstitute with an actual view name

Finally, where feasible, an alternate implementation of many of the following LotusScript modules can also be found in Chapter 14, "Design Enhancements Using Formula Language."