Developer/2000 White Paper

Guide to OLE Automation Oracle Forms to Microsoft Word

Table of Contents
1. INTRODUCTION __________________________________________________________________ 2 2. BASIC OLE AUTOMATION PRINCIPLES ____________________________________________ 2 3. THE MICROSOFT WORD OBJECT MODEL__________________________________________ 3 4. ORACLE FORMS AND OLE AUTOMATION__________________________________________ 3 5. AUTOMATING AN INDEPENDENTLY EXECUTING MICROSOFT WORD APPLICATION 5 6. AUTOMATING EMBEDDED OR LINKED OLE2 OBJECTS ____________________________ 14 7. CONCLUSION ___________________________________________________________________ 18

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

1.

Introduction This paper explains the basic concepts of OLE automation and in particular how to use the OLE automation facilities within Oracle Forms V4.5 to automate Microsoft Word. Code examples are included.

2.

Basic OLE Automation principles Objects are the fundamental components of OLE applications. Every element of an OLE server application can be represented as an object. Each of these objects is defined by its properties (physical and logical characteristics) and its methods (actions which the object can perform). OLE server applications expose the properties and methods of their component objects to other Windows applications. OLE client applications can programmatically manipulate OLE server applications through reading/writing their exposed properties and invoking their exposed methods. This process of 'remote control' of OLE server applications from OLE client applications is known as 'OLE Automation'. The original OLE ('Object Linking and Embedding') specification, created in 1991 concentrated on the creation of compound documents via the linking or embedding of server application documents inside container applications (a process from which OLE gained its original and now obsolete title). The much broader OLE2 specification introduced the concept of OLE automation along with a number of other extensions to the original OLE specification. Only applications supporting the OLE2 specification can therefore participate in OLE automation. Separate aspects of the OLE2 specification cover OLE automation client and OLE automation server functionality so an application must support the respective aspects of the OLE2 specification to function as an OLE automation client, OLE automation server or both. Before writing code to perform OLE automation, it is necessary for an application developer to understand the following things:
The object classes exposed by the OLE automation server and the relationships between them (the OLE automation server's 'Object Model') The properties of the OLE automation server's objects, their datatypes and valid values The methods of the OLE automation server's objects, their syntax and arguments The methods used by the OLE automation client to access the methods and properties of the OLE automation server's objects

This article will describe the Object Model of Microsoft Word and the methods used by Oracle Forms to perform OLE automation with Microsoft Word.

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

3.

The Microsoft Word Object Model Microsoft Word can function as an OLE automation client or OLE automation server. This section describes the Object Model which enables Word to be used as an OLE automation server. In most OLE server applications (e.g. Microsoft Excel) there are many different OLE object classes in the Object Model (e.g. Worksheets, Charts, Titles in Excel) which can be individually manipulated via their properties and methods. However, in Microsoft Word there is just one object of interest. This is the WordBasic interpreter used by Microsoft Word to execute commands written in Word's own macro language, WordBasic. Instead of executing methods or setting properties for specific objects (e.g. Document, Header, Footer, Paragraph) within a Word document, WordBasic macro statements are sent to the WordBasic interpreter to perform the requested tasks on behalf of the OLE client application. Although this method of automation doesn't strictly comply to the spirit of OLE, it does make the process of remote automation of Word simple. All that is required is to create an OLE object of the class "Word.Basic" and send WordBasic macro statements to this object for execution.

4.

Oracle Forms and OLE Automation Oracle Forms can operate as an OLE automation client only. In other words, you can embed or control an OLE automation server such as Word within a Forms module, but you cannot embed nor control a Forms module from within Word. OLE automation client functionality is implemented in Oracle Forms through a number of built-in PL/SQL procedures and functions contained in the OLE2 PL/SQL package. The OLE2 PL/SQL package provides a PL/SQL API for creating OLE automation server objects and accessing the properties and methods of these objects. The OLE2 PL/SQL package defines two additional PL/SQL datatypes which are used by the OLE2 built-ins:

Name OBJ_TYPE LIST_TYPE

Description A handle to an OLE object A handle to an OLE argument list

Each of the PL/SQL procedures and functions in the OLE2 package is described below along with its PL/SQL specification:

Object Management CREATE_OBJ Creates an OLE object and returns an object handle. CREATE_OBJ(OBJECT IN VARCHAR2) RETURN OBJ_TYPE RELEASE_OBJ Releases all resources for an OLE object created by CREATE_OBJ and destroys the object handle. 3

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

RELEASE_OBJ(OBJECT IN OBJ_TYPE)

Object Property Access GET_CHAR_PROPERTY Reads a character property of an OLE object. GET_CHAR_PROPERTY(OBJECT IN OBJ_TYPE, PROPERTY IN VARCHAR2, ARGLIST IN LIST_TYPE) RETURN VARCHAR2 GET_NUM_PROPERTY Reads a number property of an OLE object. GET_NUM_PROPERTY(OBJECT IN OBJ_TYPE, PROPERTY IN VARCHAR2, ARGLIST IN LIST_TYPE) RETURN NUMBER GET_OBJ_PROPERTY Reads an object property of an OLE object. GET_OBJ_PROPERTY(OBJECT IN OBJ_TYPE, PROPERTY IN VARCHAR2, ARGLIST IN LIST_TYPE) RETURN OBJ_TYPE SET_PROPERTY Sets the value of a number or character property of an OLE object. SET_PROPERTY(OBJECT IN OBJ_TYPE, PROPERTY IN VARCHAR2, VALUE IN NUMBER, ARGLIST IN LIST_TYPE) or SET_PROPERTY(OBJECT IN OBJ_TYPE, PROPERTY IN VARCHAR2, VALUE IN VARCHAR2, ARGLIST IN LIST_TYPE)

Object Method Execution INVOKE Executes a method of an OLE object which returns nothing. INVOKE(OBJECT IN OBJ_TYPE, METHOD IN VARCHAR2, ARGLIST IN LIST_TYPE) INVOKE_CHAR Executes a method of an OLE object which returns a character string. INVOKE(OBJECT IN OBJ_TYPE, METHOD IN VARCHAR2, ARGLIST IN LIST_TYPE) RETURN VARCHAR2 INVOKE_NUM Executes a method of an OLE object which returns a number. INVOKE(OBJECT IN OBJ_TYPE, METHOD IN VARCHAR2, ARGLIST IN LIST_TYPE) RETURN NUMBER INVOKE_OBJ Executes a method of an OLE object which returns an object handle. INVOKE(OBJECT IN OBJ_TYPE, METHOD IN VARCHAR2, ARGLIST IN LIST_TYPE) RETURN OBJ_TYPE 4
Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

Argument List Management CREATE_ARGLIST Creates an argument list to be used by an invoked method and returns an argument list handle. CREATE_ARGLIST RETURN LIST_TYPE ADD_ARG Appends a number or character string argument to an argument list. ADD_ARG(LIST IN LIST_TYPE, VALUE IN NUMBER) or ADD_ARG(LIST IN LIST_TYPE, VALUE IN VARCHAR2) DESTROY_ARGLIST Destroys an argument list created by CREATE_ARGLIST. DESTROY_ARGLIST(LIST IN LIST_TYPE)

Exception Handling LAST_EXCEPTION Returns the most recent OLE exception code. Some examples of conditions when OLE exceptions are raised are
sending OLE commands to an inactive server application invoking non-existent methods

LAST_EXCEPTION RETURN NUMBER

The OLE2 PL/SQL package can be used to automate an independently executing OLE automation server application. It can also be used to automate an embedded or linked OLE object associated with an OLE container item in an Oracle Forms application. The remainder of this article will look at automating Word using both methods.

5.

Automating an independently executing Microsoft Word application Before any OLE automation to Word can be performed, the WordBasic interpreter must be started. This is achieved through the creation of an OLE object representing the WordBasic interpreter. The creation of this WordBasic OLE object (and an object handle for it) establishes an entry point to Word from which OLE automation can begin. The WordBasic interpreter is not visible. If you want to display the Word application on the screen during OLE automation you will need to send the macro command 'AppShow' to WordBasic. The following PL/SQL example creates a WordBasic object, obtains an object handle to it and displays the main application window for Word on the screen:

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

DECLARE -- Declare the OLE object application BEGIN -- Start WordBasic and make Word visible application:= ole2.create_obj('Word.Basic'); ole2.invoke(application, 'AppShow'); END; ole2.obj_type;

At this point there are no open documents in Word and OLE automation is restricted to the operations that can be performed from Word's File menu (e.g. create/open a document, create/open a template, execute a macro). To perform more extensive OLE automation, a Word document needs to be opened. The following PL/SQL example extends the previous example by creating a new document and inserting some text ( comments are preceded by -- ) :

DECLARE -- Declare the OLE object application ole2.obj_type;

-- Declare handle to the OLE argument list args BEGIN ole2.list_type;

-- Start WordBasic and make Word visible application:= ole2.create_obj('Word.Basic'); ole2.invoke(application, 'AppShow');

-- Create a new Word document ole2.invoke(application, 'FileNew');

-- Insert the text 'Hello there!' into the Word document args:= ole2.create_arglist; ole2.add_arg(args, 'Hello there!'); ole2.invoke(application, 'Insert', args); ole2.destroy_arglist(args);

-- Save the document to the filesystem args:= ole2.create_arglist; ole2.add_arg(args, 'EXAMPLE.DOC'); ole2.invoke(application, 'FileSaveAs', args); ole2.destroy_arglist(args);

-- Release the OLE object

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

ole2.release_obj(application);

END;

The equivalent WordBasic macro for these actions is shown below:

Sub MAIN FileNew .Template = "C:\OFFICE95\Templates\Normal.dot", .NewTemplate = 0 Insert "Hello there!" FileSaveAs .Name = "EXAMPLE.DOC", .Format = 0, .LockAnnot = 0, .Password = "",.AddToMru = 1, .WritePassword = "", .RecommendReadOnly = 0, .EmbedFonts = 0, .NativePictureFormat = 0, .FormsData = 0, .SaveAsAOCELetter = 0 End Sub

The following points are worth noting :

It is important to release all OLE objects and argument lists as early as possible to minimise Windows resource usage and at the very least these objects should be released at the end of the PL/SQL procedure. Although the macro above identifies each argument by name, when invoking Word.Basic from Forms, argument names are not required for the WordBasic commands, just the values. Default values will be used in place of missing WordBasic arguments (e.g. in the FileNew command it was not necessary to specify which document template should be used as this defaults to Normal.dot). The WordBasic arguments are position dependant so ensure values are supplied for all arguments up to the highest positioned argument you wish to use. When using an argument list with a different set of arguments it is necessary to destroy and recreate the argument list. Failing to do this will result in a new set of arguments being appended to an old set.

Word bookmarks can be used to position the insertion point at a specific location within a document. These bookmarks can either be created and named in advance or can be created by macro commands (the latter is useful if you want to mark a location to revisit later). The following PL/SQL procedure illustrates the use of a predefined bookmark in a Word document:

DECLARE

-- Declare the OLE object application ole2.obj_type;

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

-- Declare handle to the OLE argument list args ole2.list_type;

BEGIN

-- Start WordBasic and make Word visible application:= ole2.create_obj('Word.Basic'); ole2.invoke(application, 'AppShow');

-- Open a Word document args:= ole2.create_arglist; ole2.add_arg(args, 'C:\TEMP\EXAMPLE.DOC'); ole2.invoke(application, 'FileOpen', args); ole2.destroy_arglist(args);

-- Navigate to the bookmark called 'LetterHead' args:= ole2.create_arglist; ole2.add_arg(args, 'LetterHead'); ole2.invoke(application, 'EditGoto', args); ole2.destroy_arglist(args);

-- Insert text at the bookmark location args:= ole2.create_arglist; ole2.add_arg(args, 'OLE Automation Limited'); ole2.invoke(application, 'Insert', args); ole2.destroy_arglist(args);

-- Release the OLE object ole2.release_obj(application);

END;

As well as executing WordBasic commands, it is possible to return information from Word to Oracle Forms by invoking WordBasic functions. For example, the WordBasic function FONT$() returns a character string with the name of the font in use at the insertion point of a document. The following PL/SQL example demonstrates how this function can be called via OLE automation:

DECLARE

-- Declare the OLE object application ole2.obj_type;

-- Declare handle to the OLE argument list

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

args

ole2.list_type;

-- Declare the PL/SQL variable to receive the font name fontname VARCHAR2(30);

BEGIN

-- Start WordBasic and make Word visible application:= ole2.create_obj('Word.Basic'); ole2.invoke(application, 'AppShow');

-- Open a Word document args:= ole2.create_arglist; ole2.add_arg(args, 'C:\TEMP\EXAMPLE.DOC'); ole2.invoke(application, 'FileOpen', args); OLE2.DESTROY_ARGLIST(args);

-- Display the font in use at the insertion point fontname:=ole2.invoke_CHAR(application, 'Font$'); MESSAGE(fontname);

-- Release the OLE object ole2.release_obj(application);

END;

The following points are worth noting:

To call a WordBasic function, the OLE2.INVOKE_CHAR or OLE2.INVOKE_NUM procedures are used instead of the OLE2.INVOKE procedure. To determine whether to use OLE2.INVOKE_CHAR or OLE2.INVOKE_NUM you need to know the datatype of the item being returned from the WordBasic function. You can derive this from the WordBasic function name. Functions returning a character string have a $ as the last letter of the function name whereas functions returning numbers do not. WordBasic functions are distinguished from commands by brackets following the function name. Do not use these brackets when referring to the function in a PL/SQL procedure.

The following PL/SQL procedure illustrates how OLE automation can be used to perform a mail merge in Word. The example assumes that the main and data source documents have already been created and the placeholders for data source fields have been created in the main document (refer to the Word online help for details of setting up mail merge documents). The PL/SQL procedure simply populates the data source document with data from the Oracle database, invokes the mail merge and saves the resulting file.

DECLARE

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

-- Declare the OLE object application ole2.obj_type;

-- Declare handle to the OLE argument list args ole2.list_type;

-- Declare a SQL cursor to be used to fetch the records from -- the database. CURSOR emp_cursor IS select ename, sal from emp;

BEGIN

-- Start WordBasic and make Word visible application:= ole2.create_obj('Word.Basic'); ole2.invoke(application, 'AppShow');

-- Open the mail merge data source document args:= ole2.create_arglist; ole2.add_arg(args, 'C:\TEMP\MERGE1.DOC'); ole2.invoke(application, 'FileOpen', args); ole2.destroy_arglist(args);

--

Move to end of first row in data table (merge field names)

ole2.invoke(application, 'NextCell');

---

Fetch each employee record and pass values of employee name and salary into the mail merge data table

FOR emp_record IN emp_cursor LOOP

--

Move onto next row of data table

ole2.invoke(application, 'NextCell'); -Insert employee name

args:= ole2.create_arglist; ole2.add_arg(args, emp_record.ename); ole2.invoke(application, 'Insert', args); ole2.destroy_arglist(args); -Move to next column of data table

ole2.invoke(application, 'NextCell'); -Insert salary

args:= ole2.create_arglist; ole2.add_arg(args, TO_CHAR(emp_record.sal)); ole2.invoke(application, 'Insert', args);

10

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

ole2.destroy_arglist(args);

END LOOP;

-- Open the mail merge main document args:= ole2.create_arglist; ole2.add_arg(args, 'C:\TEMP\MERGE2.DOC'); ole2.invoke(application, 'FileOpen', args); ole2.destroy_arglist(args);

-- Perform the mail merge to create the merged document ole2.invoke(application, 'MailMergeToDoc');

-- Save the merged document to disk args:= ole2.create_arglist; ole2.add_arg(args, 'C:\TEMP\MERGE3.DOC'); ole2.invoke(application, 'FileSaveAs', args); ole2.destroy_arglist(args);

-- Close all three documents without prompting to save any changes -- ( FileCloseAll 2 = close all without saving changes ) args:= ole2.create_arglist; ole2.add_arg(args, 2); ole2.invoke(application, 'FileCloseAll', args); ole2.destroy_arglist(args);

-- Release the OLE object ole2.release_obj(application);

END;

The following points are worth noting :

It is not possible to use a numeric datatype as an argument to the WordBasic Insert command. To insert a salary figure the TO_CHAR function was used to convert to a character string first.

The following example invokes Word to perform a spelling check against an Oracle Forms text field ('LONGFIELD1' in block 'CONTROL') and return the corrected text:

DECLARE

-- Declare the OLE object application ole2.obj_type;

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

11

-- Declare handle to the OLE argument list args ole2.list_type;

-- Declare a temporary local variable for returned text sel_text VARCHAR2(1000);

BEGIN

-- Start WordBasic application:= ole2.create_obj('Word.Basic');

-- Create a temporary document to do the spell check in ole2.invoke(application, 'FileNew');

-- Insert the text of field CONTROL.LONGFIELD into temporary document args:= ole2.create_arglist; ole2.add_arg(args, :CONTROL.LONGFIELD1); ole2.invoke(application, 'Insert', args); ole2.destroy_arglist(args);

-- Invoke the spell checker ole2.invoke(application, 'ToolsSpelling');

-- Return corrected text to Oracle Forms ole2.invoke(application, 'EditSelectAll'); sel_text:= ole2.get_char_property(application, 'Selection');

--Release the OLE object ole2.release_obj(application);

-- The text brought back contains an extraneous control character -- (a paragraph marker) so get rid of it :CONTROL.LONGFIELD1:=SUBSTR(sel_text, 1, (LENGTH(sel_text)-1) );

END;

Generally, the best approach for developing PL/SQL code to perform sophisticated OLE automation to Word is to use Word's own macro recorder to record a WordBasic macro for the required actions and convert the resulting WordBasic macro into a series of OLE2.INVOKE, OLE2.INVOKE_CHAR and OLE2.INVOKE_NUM statements, using argument lists where appropriate. If the tasks you want to perform in Word are completely self-contained and do not require any parameters to be passed in from Oracle Forms, it may be preferable to create a WordBasic macro 12
Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

within Word itself to perform these tasks and invoke the macro via OLE automation. The following example executes the WordBasic macro MyMacro after the creation of a new Word document:
DECLARE

-- Declare the OLE object application ole2.obj_type;

-- Declare handle to the OLE argument list args ole2.list_type;

BEGIN

-- Start WordBasic and make Word visible application:= ole2.create_obj('Word.Basic'); ole2.invoke(application, 'AppShow');

-- Create a new document ole2.invoke(application, 'FileNew');

-- Execute the macro called MyMacro args:= ole2.create_arglist; ole2.add_arg(args, 'MyMacro'); ole2.add_arg(args, 1); ole2.invoke(application, 'ToolsMacro', args); ole2.destroy_arglist(args);

END;

For further information on the syntax of WordBasic commands refer to Word's own online help and the documentation supplied with the Microsoft Office Developer's kit.

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

13

6.

Automating Embedded or Linked OLE2 objects The original concept behind OLE concerned the embedding or linking of objects created by an OLE server application inside a document created by a different application (referred to as an OLE container application). It is possible to combine this aspect of OLE with OLE automation to automate an embedded or linked object. Oracle Forms includes a special OLE container item into which an OLE object can be embedded or linked. The OLE object classes which can be embedded or linked into an OLE container are registered in the Windows OLE registration database when an OLE server application is installed. The 'OLE Class' property of an Oracle Forms OLE container indicates which object class it contains and must be one of those listed in the OLE registration database. The 'OLE Tenant Types' property indicates whether the OLE container holds an embedded or linked OLE object. The 'OLE In-Place Activation' property indicates whether the OLE server application shares the Oracle Forms application Window when it is activated or whether a separate Window is opened. For Word documents, the OLE container's 'OLE Class' property should be set to 'Word.Document'. However, Word's simplified OLE object model does not permit direct automation of the embedded or linked 'Word.Document' object class (unlike Excel which allows direct automation of the 'Excel.Worksheet' object class). All OLE automation against the 'Word.Document' class must be performed via the 'Word.Basic' class. To automate an embedded or linked Word document, the OLE2 PL/SQL package must be used in conjunction with the following PL/SQL procedures from the separate PL/SQL built-in package FORMS_OLE:

Name ACTIVATE_SERVER

Description Activates an OLE server application associated with an OLE container item and prepares it for OLE automation. Takes the name or item id of an Oracle Forms OLE container item as an argument. Causes an OLE server to execute a verb identified by a verb name or verb index. An OLE verb specifies an action you can perform on an OLE object. Deactivates an OLE server application associated with an OLE container item. Terminates the connection between the OLE server and the OLE container.

EXEC_VERB

CLOSE_SERVER

The following example illustrates how the FORMS_OLE and OLE2 procedures are used to automate an embedded or linked Word document (in this case a standard letter template). The document is stored in the Oracle database and displayed in the OLE container item 'DOC' of block 'OLEWORD'. The PL/SQL procedure opens the template document and fills it in by sending the contents of Oracle Forms fields to bookmarks in the document. The resulting document is then saved to disk, the changes undone to restore the template to its original state and the document is closed:

DECLARE -- Declare the OLE object application ole2.obj_type;

-- Declare handle to the OLE argument list

14

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

args BEGIN

ole2.list_type;

-- Activate Word forms_ole.activate_server('OLEWORD.DOC');

-- Start WordBasic application:= ole2.create_obj('Word.Basic');

-- Open the embedded document for editing forms_ole.exec_verb('OLEWORD.DOC',1);

-- Go to EmployeeName bookmark args:= ole2.create_arglist; ole2.add_arg(args, 'EmployeeName'); ole2.invoke(application, 'EditGoto', args); ole2.destroy_arglist(args);

-- Transfer contents of the EMP field to document args:= ole2.create_arglist; ole2.add_arg(args, :EMP.ENAME); ole2.invoke(application, 'Insert', args); ole2.destroy_arglist(args);

-- Go to Salary bookmark args:= ole2.create_arglist; ole2.add_arg(args, 'Salary'); ole2.invoke(application, 'EditGoto', args); ole2.destroy_arglist(args);

-- Transfer contents of Salary field to document args:= ole2.create_arglist; ole2.add_arg(args, TO_CHAR(:EMP.SAL)); ole2.invoke(application, 'Insert', args); ole2.destroy_arglist(args);

-- Save the completed document to disk args:= ole2.create_arglist; ole2.add_arg(args, 'C:\TEMP\LETTER1.DOC'); ole2.invoke(application, 'FileSaveAs', args); ole2.destroy_arglist(args);

-- Restore the letter template to it's original state ole2.invoke(application, 'EditUndo');

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

15

ole2.invoke(application, 'EditUndo');

-- Release the OLE object ole2.release_obj(application);

-- Close Word forms_ole.close_server('OLEWORD.DOC');

END;

The following points are worth noting:

The ACTIVATE_SERVER, CREATE_OBJ and EXEC_VERB commands must be performed in the order given. Due to the relationship between the 'Word.Document' and 'Word.Basic' object classes, failure to use this sequence may cause unexpected behaviour (e.g. the Word application window does not close when the CLOSE_SERVER command is issued). Verb index 1 is used by EXEC_VERB to open a Word document for editing. There is no need to use an AppShow command as the EXEC_VERB statement will make Word visible. There is no need to close the embedded document via WordBasic. This is done implicitly by the CLOSE_SERVER command. In place of the FileSaveAs command a FilePrint could have been used to send the document to the printer rather than disk. If the embedded Word document is attached to a Word template (.DOT file), a copy of the .DOT file must exist on all PCs using the document from within Oracle Forms. The .DOT file is not stored in the database with the embedded document. Without this file on the hard disk, macros, autoText entries and custom toolbar, menu and shortcut keys defined in the .DOT file will be inaccessible. With Word V7.0 for Windows 95, the previous example only works if the 'In-place Activation' property of the OLE container is set to 'False'. If this property is set to 'True', WordBasic does not permit the use of any commands available from the File menu (e.g. FileSave, FileSaveAs, FilePrint). These commands will just be ignored. If no commands from the File menu are issued via OLE automation, 'In-place Activation' can be set to 'True' or 'False'.

With Word V6.0 for Windows 3.x, even with 'In-place Activation' set to 'False' WordBasic (for some unknown reason) still disallows the use of the FileSave and FileSaveAs commands directly against an embedded or linked document. However, the FileNew command can be used so a workaround to this limitation is to create a temporary copy of the embedded or linked document via OLE automation and work on that. This has the effect of reenabling the restricted commands. The following PL/SQL procedure illustrates the previous example modified to work with Word V6.0:

DECLARE

-- Declare the OLE object application ole2.obj_type;

16

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

-- Declare handle to the OLE argument list args ole2.list_type;

BEGIN

-- Activate Word forms_ole.activate_server('OLEWORD.DOC');

-- Start WordBasic application:= ole2.create_obj('Word.Basic');

-- Open the embedded document for editing forms_ole.exec_verb('OLEWORD.DOC',1);

-- Create a temporary copy of the document to enable the FileSave command ole2.invoke(application,'EditSelectAll'); ole2.invoke(application,'EditCopy'); ole2.invoke(application,'FileNew'); ole2.invoke(application,'EditPaste');

-- Go to EmployeeName bookmark args:= ole2.create_arglist; ole2.add_arg(args, 'EmployeeName'); ole2.invoke(application, 'EditGoto', args); ole2.destroy_arglist(args);

-- Transfer contents of the EMP field to document args:= ole2.create_arglist; ole2.add_arg(args, :EMP.ENAME); ole2.invoke(application, 'Insert', args); ole2.destroy_arglist(args);

-- Go to Salary bookmark args:= ole2.create_arglist; ole2.add_arg(args, 'Salary'); ole2.invoke(application, 'EditGoto', args); ole2.destroy_arglist(args);

-- Transfer contents of Salary field to document args:= ole2.create_arglist; ole2.add_arg(args, TO_CHAR(:EMP.SAL)); ole2.invoke(application, 'Insert', args); ole2.destroy_arglist(args);

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

17

-- Save the completed document to disk args:= ole2.create_arglist; ole2.add_arg(args, 'C:\TEMP\LETTER1.DOC'); ole2.invoke(application, 'FileSaveAs', args); ole2.destroy_arglist(args);

-- Close the temporary document (without prompting to save any changes)

args:= ole2.create_arglist; ole2.add_arg(args, 2); ole2.invoke(application, 'FileClose', args); ole2.destroy_arglist(args);

-- Close the embedded document forms_ole.close_server('OLEWORD.DOC');

-- Release the OLE object ole2.release_obj(application);

END;

The following points are worth noting:

In this procedure there is no need to undo changes as the embedded document is never modified. Only the temporary document is modified which is discarded at the end. A FileClose is required to close the temporary document but not the embedded document as this is implicitly closed by the CLOSE_SERVER command.

7.

Conclusion This article has described the fundamental concepts of using the built-in OLE automation features of Oracle Forms V4.5 to manipulate Microsoft Word. Once these basic concepts and limitations are understood, the reader should be able to adapt the examples given in this article using the documentation provided with Microsoft Word to implement their specific OLE automation requirements.

18

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

Title:
Author: Updated:

Guide to OLE Automation - Oracle Forms to Microsoft Word

David Booth, Oracle Corporation (UK) Ltd. June 11, 1996

This document is provided for informational purposes only and the information herein is subject to change without notice. Please report any errors to Oracle Corporation. Oracle Corporation does not provide any warranties covering this document and specifically disclaims any liability in connection with this document.

Copyright Oracle Corporation 1996 All Rights Reserved Printed in the USA

Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 USA

Worldwide Inquiries: Phone Fax (+1) 415.506.7000 (+1) 415.506.7200

Oracle is a registered trademark and Oracle Forms, Oracle Graphics, Oracle Reports , Oracle Toolkit, Oracle7, PL/SQL, Developer/2000 are trademarks of Oracle Corporation.

All other company and product names are used for identification purposes only, and may be trademarks of their respective owners.

Developer/2000: Guide to OLE Automation - Oracle Forms to Microsoft Excel

19