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

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.

2 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 Description
OBJ_TYPE A handle to an OLE object
LIST_TYPE 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.

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

 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 5

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

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 ole2.list_type;
BEGIN

-- 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

6 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 7

 -- 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

8 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 9
 -- 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 Description
ACTIVATE_SERVER 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.
EXEC_VERB 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.
CLOSE_SERVER Deactivates an OLE server application associated with an
OLE container item. Terminates the connection between
the OLE server and the OLE container.

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 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);

-- 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: Guide to OLE Automation - Oracle Forms to Microsoft Word
Author: David Booth, Oracle Corporation (UK) Ltd.
Updated: 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 (+1) 415.506.7000
Fax (+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