For programmers and systems integrators, learning about new programming environments is one of the never-ending joys of the job. Each environment has its own tools, its own quirky interface, and—if you’re successful at figuring it out—its own rewards. Lotus Notes is no exception. Since Notes is rapidly becoming an integrated part of the AS/400 system, understanding how to program in Notes is becoming a topic of concern for many Client Access/400 integrators. Consequently, we’re including this brief tutorial to whet your appetite.

The Components of Lotus Notes

Notes is divided into four major functional components: a document database, forms, views, and agents. The document database contains the usual types of fields available to most databases: numeric fields, character fields, key fields, and special “rich text” fields into which you can embed Object Linking and Embedding (OLE) objects. The document database is created through the use of templates called forms. Forms are the functional equivalent of DDS specifications in OS/400; they define the structure of individual documents as they are created and added to the document database. However, each element and field within a form is fully programmable using the Notes design tools. In a similar manner, a Notes view is akin to an AS/400 logical file; it organizes the logical path into the document database so that documents appear in a desired group. Views are also fully programmable using the Notes design tools. Notes agents are self-contained programs that are pure program scripts. The agent scripting language is an extension of the Basic language, but, unlike traditional QBASIC, Notes Basic is a full object-oriented implementation using object classes. The programming interface of Notes agents is also made available through the Notes design tools. There are other design tools besides forms, views, and agents, but for this discussion, we’ll focus on the major ones. In this article,

I’ll explain the process of programming a Notes form, which will introduce you to the concepts used when programming agents and views.

Accessing the Notes Programming Tools—Working in Forms When a Notes programmer wants to affect the structure of a particular Notes database, he double-clicks on the design frame within the database itself to expand the hierarchy of design tools. He then chooses a particular form to modify. This is shown in Figure 1.

Opening the form displays the structure of the Notes database in a two-paned window. The upper portion of the window shows the layout of the document created by the form. The lower pane is the programming interface that contains the code for controlling the form. The AS/400 equivalent of this interface would be screen design aid (SDA), in which you place fields and constants on the screen and then modify the programmed functionality of those fields using the SDA menus. In the Notes interface, however, both the design screen and the programmed functions of the fields are presented at the same time. This is shown in Figure 2.

To create constant text on a form, you simply key it into the upper pane. To create a new field, you click the menu bar and then click Create Field. A new untitled field is added to the form at the location of your cursor. The lower pane of the interface automatically moves its focus to the newly created field, allowing you to program the “default value” event.

Notes has a complete event-driven user interface that allows you to write formulas and scripts for input translation, input validation, cursor entrance or exit, termination, and more. Each event can contain a trigger, a formula, or a script, just like an RPG subroutine that is triggered when the user hits a command key.

Syntax and Field Properties

There are two types of program syntax that can be activated by a field event: formula syntax or script syntax. First of all, formulas use a macro syntax composed of @Functions keywords. These are highly developed—and extremely powerful—preprogrammed functions that have evolved through Notes’ long development history. The complete list is available by pressing the Fields and Functions button at the bottom of the screen. The second syntax is Lotus Script, the highly developed programming extension of Basic mentioned earlier. Lotus Script is extremely powerful for establishing highly complex program flows, such as retrieving data through ODBC and displaying subwindows. Examples of a Lotus formula and a Lotus script are shown in Figures 3 and 4.

The properties of a field (its name, type, and style, and the security attributes associated with it) are controlled by the Properties box. To access these properties, you double-click the field on the form and a floating tabbed folder is displayed. Learning about the power of field properties is one of the great mysteries that—when revealed—will make you a true believer in the Notes interface.

Working with Keywords—Fast Subfiles at the Click of a Button

Let’s assume you want to create a simple selection list. By changing the field type to keywords, you’re presented with five different types. You can choose Enter Choices (one per line) to force the user to select a constant value; you can choose Use Formula for Choices, which allows you to calculate a variety of selections based upon other fields in the document; you can choose Use Address Dialog for Choices, which will display a subwindow connected to the Notes Address book; you can choose Use Access Control List, which displays a subwindow connected to the Notes Security Access Control List; or—most powerful of all—you can choose Use View Dialog for Choices, which gives you

access to a predefined logical view of the database you’ve created. This last choice is the equivalent to creating a subfile program in RPG and making it available with a click of the button. You can see the properties folder in Figure 5. A sample of how this subfile-like feature works in action is shown in Figure 6. In this example, the user clicks on a selection field called “topic” and a preprogrammed view allows him to choose the appropriate element of the file.

The Notes Debugger

When you’ve finished creating, programming, modifying, or tailoring the fields of the form, it’s time to test them. Notes has some solid debugging tools built right into the programming interface. To activate the debugger, you select Tools from the File menu, then choose the Debug Lotus Script option. Then, you select Design and click Test Form. Notes asks you if you want to save the form, and—if you say yes—it compiles it and activates it to create a new Notes document. The Debugger window pops up and walks you through the flow of the document creation process, showing you each step. This is shown in Figure 7. You can set breakpoints, show the values of individual fields and variables, or change the flow of the program on the fly. It even allows you to control the processing of subforms that may be embedded with a master form. All told, it’s an extremely powerful tool.

Accessing the Power of Notes and Beyond

This is only a very brief overview of the power of the Notes programming interface. In fact, it’s only a beginning of learning something that will soon become an integrated part of your AS/400 client environment. How does Notes work with the AS/400? In the next issue of Client Access/400 Expert, Timothy Laurent, a leading AS/400 Notes programmer, will show you exactly how this interface can be used to access data on the AS/400.

Figure 1: Altering the Notes Database Structure Using the Design Frame

Figure 2: The Notes Programming Interface Figure 3: A Sample Notes Formula Using @Functions

Figure 4: A Sample Notes Script Using Lotus Script Figure 5: Notes Field Properties Box

Figure 6: View Dialog Processing Figure 7: Notes Debugger in Action