View figure.
OpenDoc allows you to create program scripts (routines) and attach them to events from within your application. Events change the state of a part. When an event is identified, the script implementing the event routine is called.
The following direct scripting systems are supported by OpenDoc:
If developing a script through Lotus Script, consult the Lotus Scripting guide for information.
If developing a script using Visual Basic, all normal rules pertaining to Visual Basic must be followed.
Through these systems, you can design, attach, and execute code to generate the events that a scriptable part identifies and invokes the methods of those parts.
An example of scripting would be to attach a script to a timer part. When the timer reaches a certain count, a script would run to back up a database.
The Lotus Script Interactive Development Environment (LS IDE) is a tool for managing BASIC scripts associated with various IBM and Lotus products. The LS IDE implements the Scripting Component interface. This interface is delivered as part of the base OpenDoc runtimes. The LS IDE provides a compact and effective user-interface for editing, debugging, and browsing the BASIC code associated with scripted OpenDoc parts. For additional information, see Script Component.
To participate in OpenDoc Direct Scripting, the LS IDE was extended to include SOM usage bindings. SOM usage bindings provide a language-native mechanism for creating, destroying, sending messages to, and invoking methods on SOM objects.
The following BASIC code fragment creates a SOM Object, sends the message SayHello, and deletes the object.
Dim helloWorld as New ASOMObject
helloWorld.SayHello
delete helloWorld
The LS IDE also serves as a debugger for the script code created. A complete set of help for the language and for the LS IDE is available online by running the LS IDE and selecting the Help menu item.
You can create references to OpenDoc parts in the following ways:
[Part_Spart].setcolor 255
dim lvar as ScriptableSimplePart
...
Set lvar = Bind ScriptableSimplePart ("Part_SPart")
...
lvar.setcolor 128
[Part_SPart].setcolor 128
Note:
The name of the object as used in this statement is a string expression and could be constructed, if appropriate.
The Initialize and Terminate events are generated by the Lotus Script IDE. They are not generated by the OpenDoc parts. The Initialize event provides a mechanism for your script code to establish a default running context, such as initializing globals or opening default files, when the part is initialized. The Terminate event enables your script to cleanup before the object is deleted.
The Initialize event is called once when the first event arrives to the part. The Terminate event is called when the part is deleted from the scripting component. Generally, the Terminate event occurs when a document is closed.
The Initialize and Terminate events may be called several times during the development of scripts. Editing a script will reset the object owning the event. Resetting an object send the Terminate event to the object owning the script and triggers the Initialize event when the first new event arrives on the part.
In a given scripting context, the Initialize and Terminate events are only generated for the root object in the scripting context. The contained objects' Initialize and Terminate events should not be scripted because they are not fired. To attach script code to embedded objects' Initialize and Terminate events simply edit the scripts for the embedded object.
The following sections describe parts of the Lotus Script language that have specific implementations for their use with OpenDoc.
The following list describes the mapping from CORBA data types (used by SOM and OpenDoc classes) to their Lotus Script equivalents:
| CORBA | Lotus Script Equivalent |
| tk_any | Not supported |
| tk_array | Not supported |
| tk_boolean | Short |
| tk_char | Short |
| tk_double | Double |
| tk_enum | Not supported |
| tk_float | Single |
| tk_long | long |
| tk_null | Not supported |
| tk_octet | Short |
| tk_objref | Object Reference |
| tk_pointer | Not supported |
| tk_Principal | Not supported |
| tk_sequence | A collection, see Sequence CORBA Data Type Mapping. |
| tk_short | Short |
| tk_string | String |
| tk_struct | Not supported |
| tk_TypeCode | Not supported |
| tk_ulong | Long, see Unsigned CORBA Data Type Mapping |
| tk_union | String |
| tk_ushort | Short, see Unsigned CORBA Data Type Mapping |
| tk_void | Void |
CORBA sequences are mapped to the collection data type in Lotus Script. This Lotus Script data type is the forall construct. Lotus Script collections are readonly and therefore cannot be changed. While the collection can not be modified, the items in the collection can be modified or accessed and methods can be invoked. For example:
forall item in obj.somSequence
item.HelloWorld
end forall
Lotus Script BASIC does not support unsigned data types. CORBA unsigned data types are mapped into signed Lotus Script types. The Scripting user must take special care when comparing unsigned data type values.
The SOM usage bindings for events supports the following return types for triggered events:
All other return types cause a registration failure on the event. When a non-conforming return type is encountered, the registration process does not add the event to the list of scriptable events.
The following sections describe the special considerations for using the LS IDE with OpenDoc and additions made to the LS IDE for OpenDoc. Review these consideration when developing scriptable interfaces for parts you plan to script with the LS IDE.
When designing the scriptable interface for a part you should keep the interface as straight forward as possible for the script writer. For example:
interface SimpleScriptablePartInterface {
attribute long Color;
#ifdef __SOMIDL__
implementation {
Color:ODId=1000
};
#endif
};
The above scriptable interface is presented to the LS IDE as:
class SimpleScriptablePartInterface
Dim Color as Long
end class
The out and inout parameter specification applied to objects is not supported by the Lotus Script engine.
The Lotus Script engine implements a garbage collected environment based on reference counting and language scoping rules. The lifecycles of objects created within the scripts are managed by the script engine using reference counting. Objects created by the Lotus Script engine can be destroyed by the script engine, but objects registered using the script component interface and objects returned to the scripting environment from methods are not destroyed by the script engine. In these cases, the script engine does not take ownership of the object as defined by CORBA. When a CORBA tk_string is returned to the Lotus Script engine ownership passes to the script engine. In all cases, the part developer should follow the CORBA ownership rules for parameters and return values.
Registering a class registers the superclasses of the class. Therefore, the superclasses must be accessible to the registration process. Ensure the superclasses of the class are placed into the SOM Interface Repository along with the class itself. Failure to register a parent class results in a failure to register the child class.
The LS IDE supports single inheritance. Therefore, only the leftmost branch of and object's parent chain will be registered.
The Lotus Script scripting component attempts to load the interface exposed by a scriptable object. When the Lotus Script engine encounters unsupported data types, the particular property, method, or event is not registered. However, the registration process is not terminated. The Lotus Script scripting component will register the total interface exposed by a scriptable object. The total interface encompasses the object's parents and the classes of object used in methods, properties and events. For example, in the following interface:
interface SimpleScriptableInterface {
AnotherObject ReturnObject()
#ifdef __SOMIDL__
implementation {
ReturnObject:ODId=2000;
};
#endif
};
Registering the method ReturnObject will cause the LS Scripting Component to also register the class AnotherObject. Therefore the meta-data describing AnotherObject must be available. If the meta-data for AnotherObject is not available the method will not be registered. Meta-data refers to the information maintained in the SOM Interface Repository when a part's IDL is compiled using the -u SOM compiler flags.
At runtime, the SOM Interface Repository is not consulted for the properties, methods, and events registered during design time. The information registered during design time is cached during the saving operation of the scripted OpenDoc document with the compiled scripts. Caching this information improves loading and running compiled scripts.
Note:
If the scriptable SOM interface for an object changes, ensure that the version number is set to reflect the new changes. Refresh the cache by recompiling the script. If you fail to recompile the script after an object changes, the object will use the previously cached version of the object description.
The following sections describe the modifications made to the Lotus Script IDE to support OpenDoc scripting. The modifications are mainly centered around the dialogs for loading, saving, and preference setting within the environment. For a complete description of the LS IDE's functioning, see the online help.
The LS IDE panel is shown in Figure 67. This section describes the menu structure for the LS IDE and what action each menu item invokes.
Figure 67. Lotus Script Interactive Development Environment
The File menu has the following items:
The Edit menu has the following items:
The Script menu has the following items:
The Run menu has the following items:
The Help menu has the following items:
This section describes the Script Properties dialog box (see Figure 68). The script properties affect the behavior of the LS IDE.
Figure 68. Script Properties Dialog
Note:
You can only use this field when you select UndoEnable.
Note:
You can only use this field when you select AutoIndenting.
To change the color of a category, select the color sample with the selection mouse button. You can change the color for the following members.
When you select the Font button from the Script Properties dialog box, it invokes the Platform Font Selection dialog for the font in which to display the source code. select the font you want to use. This font selected the new text font for the source code.
The Find/Replace dialog is available from the Edit submenu of the LS IDE menu. Use the dialog to search for a specified text string and optionally replace it with another. This dialog box contains the following input and selection fields:
The Options section specifies search parameters on the search string. These parameters are as follows:
The Part Scope and Section Scope sections specify which objects and scripts to search for the text string. A part equates to an object and a section equates to a script. The specifiers for these section are as follows:
This section contains instructions for doing OpenDoc scripting with Visual Basic. These instructions cover how to call your OpenDoc Part and how to access the OpenDoc Part properties inside a Visual Basic program.
Before reading this section, you should know how to program in Visual Basic, how to develop an OpenDoc Part, and the principles of OpenDoc Scripting.
To embed your part into a Visual Basic form, perform the following:
If there are no problems, the OLE object is created as olen, where n is a numeric value.
The Visual Program should contain the following sections.
You must declare and set an object to be the embedded OpenDoc Part. For example:
DIM obj as object Set obj = ole1.object
After the object has been set, you can use it as any other object. You could use it to get a property value, to set a property value, or to call a method. For example:
obj.method1 parameter1 obj.property1 = "abc" i = obj.property2
If your part supports event callback, you should not directly embed it as an OLE object. You should make your part as a custom control and add the control to the form. The procedure is as follows:
Note:
If your part is not in the list, run the scriptrg command.Click the OK button. A new control icon should show up in your toolbox.
View figure.