TËCHNOLÔG¥ FÖR ALL

The LotusScript Integrated Development Environment (IDE) is a set of tools you can use to create and debug scripts in Lotus applications.

• The Script Editor lets you write scripts and check their syntax. It also lets you set, clear, enable, and disable breakpoints used in debugging scripts.
• The Script Debugger lets you set, clear, enable, and disable breakpoints and step through scripts to locate the source of problems in script execution.
• The Breakpoints, Browser, Output, and Variables panels help you create and debug scripts: The Breakpoints panel lists breakpoints set in scripts, and lets you navigate to breakpoints in scripts, as well as clear, enable, and disable breakpoints.
• The Browser panel lists LotusScript keywords, application script components, and type libraries and classes for OLE Automation objects, and lets you paste keywords, component names, and OLE application-class identifiers into a script.
• The Output panel displays output generated by LotusScript Print commands included in scripts.
• During debugging, the Variables panel displays information about variables in a script and lets you change variable values.

Working in the LotusScript IDE Window

Each document in an application has its own IDE window. When the document is active, you can open its IDE window and view, write, compile, and debug scripts for document objects. To work with scripts in another document, you must make the other document active and open its IDE window.

When you open the IDE, the Script Editor and the Breakpoints, Browser, and Output panels are displayed in separate panes of the window. When you debug a script, the Script Debugger and Breakpoints, Browser, Output, and Variables panels are displayed.

You can display one pane at a time by dragging the splitter that divides the panes.

When you close or deactivate the IDE, the following are completed automatically: %Rem blocks, multiline strings, object subs, functions, and property blocks, and user-defined types and classes blocks. Scripts are also reformatted to fix lines entered out of sequence or not indented properly, and all scripts for the document are saved.

If you try to close the IDE while the Script Debugger is running, a message lets you know that a script is executing and asks whether you want to stop the script.

The Script Editor

In the IDE Script Editor, you can write and edit scripts, check script syntax, and set breakpoints for debugging scripts. When the Script Editor is open:

• The Script menu is displayed in the main menu.
• The Browser, Output, and Breakpoints panels are accessible.
• A script is displayed in the script work area.

Using the Script menu

The Script menu contains commands you can use in the IDE to:

• Create new subs and functions
• Compile and test subs and scripts
• Access the Breakpoints, Browser, Output, and Variables panels

Opening the Script Editor from the main menu

When it is opened from the main menu, the Editor shows the script last edited:

• If no script has been edited, the Editor shows the sub for the current object's default event.
• If no default event is defined, the Editor shows (Declarations) for the object.

Opening the Script Editor from an object

When it is opened from an object's InfoBox or right-click menu, the Editor shows one of the following scripts:

• If the object has been selected during the programming session, the Editor shows the last script selected for that object, whether or not the script has been edited during the session.
• If the object has not been selected during the session, but contains a user-supplied script, the Editor shows (for the object) the first sub, function, or other group of statements that contains a user-supplied script.
• If the object has not been selected and does not contain a user-supplied script, the Editor shows the sub for the object's default event.
• If no default event is defined for the object, the Editor shows (Declarations) for the object.

The Script Debugger

In the IDE Script Debugger, you can set, clear, enable, and disable breakpoints and step through scripts to locate the source of problems in script execution. The Debugger opens when the first enabled breakpoint is encountered during script execution. The Debugger for a document also opens when one of its procedures is called from an executing script in another document.

When the Script Debugger is open:

• The Debug menu is displayed in the main menu.
• The Browser, Output, Breakpoints, and Variables panels are accessible.
• The script containing the breakpoint is displayed in the Debugger, and the breakpoint line is the current line.

Using the Debug menu

The Debug menu contains commands you can use in the IDE to:

• Set, clear, enable, and disable breakpoints for debugging
• Step through a script and stop script execution

Using Breakpoints in Debugging

You can set breakpoints in the Script Editor and Script Debugger on lines in all subs except the Terminate sub. When you set a breakpoint, it is, by default, enabled. When you are editing or debugging a script, you can disable, enable, and clear the breakpoint. You can also set other breakpoints.

Note: For a continued line, a breakpoint is set on the last line.

Overview: Executing Scripts in the Debugger

The Script Debugger is opened when an enabled breakpoint is reached in an executing script. Once the Debugger is open, you can use commands in the Debug menu to step through a script, step into or over a procedure called in a breakpoint line, exit the procedure, continue script execution, or stop script execution.

You can also view information about the executing script in the Output and Variables panels.

Working with more than one Debugger

When a script you are debugging in one document steps into a script that belongs to another, unopened document, the Debugger for the second document opens and displays its script.

If Script Editors are aleady open for several documents when a breakpoint is reached in the executing document, Debuggers are displayed in place of the Editors, whether or not scripts for those documents are executing. The Calls drop-down box for each Debugger lists all executing procedures, regardless of the documents they belong to.

If script execution leads to a procedure for which source is not available, stepping continues until a displayable statement is reached or the script ends.

Fixing Errors Reported in the Script Debugger

When a run-time error occurs, the error is reported in a message box, and the current line indicator in the Script Debugger is positioned at the line containing the error. The format of the message is shown below:

• object: procedure: line#: message
• Press F1 to view Help for the message.

All Debug menu items are disabled except Stop Execution. When you choose Stop Execution, the script containing the error is displayed in the Script Editor if the Editor was open when debugging started; otherwise, the Script Debugger is closed.

When a compile-time error is encountered during debugging, script execution is terminated, the script containing the error is displayed in the Script Editor, and a message about the error is displayed in the Errors drop-down list box. You can view Help for the message by selecting the message and pressing F1.

Switching to Another Script in the Debugger

When an enabled breakpoint is reached during debugging, script execution is stopped and the script for the procedure containing the breakpoint is displayed in the Script Debugger. You can display another procedure by selecting it from the Calls drop-down list box at the bottom of the Debugger pane, or from the Script drop-down list box at the top right.

Using the Calls drop-down list box

You can switch to another procedure in the Script Debugger execution stack by selecting it from the Calls drop-down list box.

The Calls box lists the procedures that are currently executing, including procedures that belong to other documents. Each list item contains the name of the object the procedure is associated with and the name of the procedure. When you select a procedure in the list, its script is displayed in the script area of the Debugger.

A procedure that belongs to another document is dimmed in the list. A procedure whose source is not available (for example, an external script that is called from the procedure) is also dimmed. You cannot select these procedures.

When you select a procedure, its variables and their values are displayed in the Variables panel. You can use the Variables panel to view information about a variable or change its value in the executing procedure.

Using the Script drop-down list box

If you want to switch to a procedure that is not in the execution stack, you can use the Object and Script drop-down list boxes to navigate to the procedure. The script you select is displayed in the Script Debugger, but the Calls drop-down box and the Variables panel continue to display information for the executing procedure last selected in the Calls box.

Working with (Globals) and Objects in the IDE

The Object drop-down list box in the Script Editor lists the names of objects in the current document that you can associate scripts with.You select an object when you want to enter scripts for the object's events. Once you select the object, you can enter declarations in (Declarations) and define procedures that are used by the events. You can also set up variables declared in (Declarations) in the object's Initialize sub, clean up the variables in the Terminate sub, and enter options for your object scripts in (Options).

You select (Globals) in the Object drop-down list box when you want to enter declarations and procedures that are shared by all scripts in your document. You can set up variables declared in (Declarations) in the (Globals) Initialize sub, clean up variables in the Terminate sub, and enter options for your global scripts in (Options).

Displaying object scripts

When you select (Globals), one of the following is displayed:

• The last (Globals) script you accessed
• (Globals) declarations

When you select an object, one of the following is displayed:

• The last object script you accessed
• The sub for the object's default event
• Object declarations

When the expand symbol is displayed for an object in the list, you can click the symbol to display a group of related objects. If the expandable item is also an object with scripts, you can click the item to display its scripts.

Renaming objects

You cannot rename a product object in the IDE. If the object is renamed through the product, the object's scripts are automatically associated with the new name. You must, however, change references to the old name everywhere they appear in script text.

Creating Scripts in the Script Editor

The Script drop-down list box in the Script Editor lists the options, declarations, and subs associated with the object selected in the Object drop-down list box.

By default, an object's (Options) and (Declarations) and event subs are empty. (Globals) (Options) is an exception; it contains the Option Public statement by default, which makes all (Declarations) and procedures you create for (Globals) available to all scripts in the document.

When you create a new sub, function, or other procedure, the IDE inserts its name in the list of user-defined procedures at the bottom of the Script list.

Selecting bold and italicized list items

Items in the Script drop-down list box are displayed in different fonts to help you make selections quickly:

• Predefined items, including (Options), (Declarations), and Initialize, Terminate, and object event subs, are displayed in normal font. These items are displayed in bold font when they have been edited.
• Procedures you create are listed in bold italics.

(Options)

Put Option, Deftype, Use, and UseLSX statements, and Const statements associated with Use and UseLSX, in (Options).

(Declarations)

Put Private, Type, Class, and Declare (external C calls) statements, and Const statements not related to Use or UseLSX statements, in (Declarations). Put Public statements in (Globals) (Declarations). Put module-level Dim statements in (Declarations).

Initialize and Terminate subs

Use the (Globals) Initialize sub to set up data defined in (Globals) (Declarations). This sub executes before other procedures in (Globals) and before variables in (Globals) (Declarations) are accessed.

Use an object's Initialize sub to set up variables defined in the object's (Declarations). This sub executes before the object's events are executed.

Similarly, use the (Globals) and object Terminate subs to clean up variables defined in the corresponding (Declarations). The Terminate sub executes when a script is unloaded. An object script is unloaded when it is edited or when (Globals) is edited. A (Globals) script is unloaded when it is edited. Scripts are also unloaded when the application in which they are executed closes.

Event sub

In an object event sub, put statements you want executed when the event is raised for the object.

Procedure

In a sub, function, or other procedure you create, put statements you want executed when the procedure is called from another script.

Working with Directives in the Script Editor

You can enter %Include and %Rem directives in scripts you create in the IDE, but not %If (%Else, %ElseIf, %EndIf) directives. If you want to use %If directives, you must enter them in a file that you call with the %Include directive. When entered directly in IDE scripts, %If directives generate syntax and compile-time errors.

Entering %Rem and %End Rem

You can use the %Rem directive to enter a block of comments in any (Globals) or object script.

If you do not enter %End Rem to terminate the block, the IDE terminates it for you when you close the IDE, take focus away from the IDE, or check script syntax.

Working with %Include

When the IDE detects an error in a file called by %Include, it reports the error at the line that contains the directive. After you change an included file, you must press F2 to recompile all scripts for the object, or Shift+F2 to compile all scripts for the document, because there is no way for the IDE to know that these changes have been made.

Compiling and Testing Scripts in the Script Editor

As you create scripts for a document, you can test the scripts to make sure they work as you want them to. When you finish entering each line of script and move the insertion point off the line, the IDE tests the syntax and structure of the line and reports errors in the Errors drop-down list box.

You can also test subs and check all scripts for an object or document.

Testing a sub

You can choose Run Current Sub on the Script menu to execute a sub that has no parameters and test its structure and syntax without having to create an object and call the sub from an object event.

Checking all scripts for an object or a document

You can check all scripts for an object or for a document by choosing Check Scripts for Object or Check Scripts for document on the Script menu. You should use these commands to force a compile after you change a file that is called from a %Include directive. There is no other way for the IDE to know about or check the changes.

When you use Check Scripts commands, the IDE automatically reformats scripts to fix lines entered out of sequence or not indented properly, and completes any unterminated %Rem statements.

Viewing error messages

The IDE reports all compile-time errors in the Errors drop-down list box. The number of errors found is also displayed in a message box if you enable the box with the Script Editor Preferences command on the File menu.

Using the IDE Output Panel

When you execute scripts in a document, up to 1024 characters of output from each Print statement included in the scripts is displayed in the Output panel. This output is displayed in the order it is generated in the document.

You can review the output list to determine whether scripts are executing as you want them to.

When the document is closed, up to 500 lines of output are saved for the document.