forms word

Developer/2000White Paper

Guide to OLE Automation -Oracle Forms to Microsoft Word

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

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

2 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 OLEautomation facilities within Oracle Forms V4.5 to automate Microsoft Word. Code examples areincluded.

2. Basic OLE Automation principles

Objects are the fundamental components of OLE applications. Every element of an OLE serverapplication 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 otherWindows applications. OLE client applications can programmatically manipulate OLE serverapplications 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 knownas 'OLE Automation'.

The original OLE ('Object Linking and Embedding') specification, created in 1991 concentrated onthe creation of compound documents via the linking or embedding of server application documentsinside 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 anumber of other extensions to the original OLE specification. Only applications supporting theOLE2 specification can therefore participate in OLE automation. Separate aspects of the OLE2specification cover OLE automation client and OLE automation server functionality so anapplication must support the respective aspects of the OLE2 specification to function as an OLEautomation client, OLE automation server or both.

Before writing code to perform OLE automation, it is necessary for an application developer tounderstand 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 OLEautomation server's objects

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


3. The Microsoft Word Object Model

Microsoft Word can function as an OLE automation client or OLE automation server. This sectiondescribes 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 classesin the Object Model (e.g. Worksheets, Charts, Titles in Excel) which can be individuallymanipulated via their properties and methods. However, in Microsoft Word there is just one objectof interest. This is the WordBasic interpreter used by Microsoft Word to execute commands writtenin Word's own macro language, WordBasic. Instead of executing methods or setting properties forspecific objects (e.g. Document, Header, Footer, Paragraph) within a Word document, WordBasicmacro statements are sent to the WordBasic interpreter to perform the requested tasks on behalf ofthe OLE client application.

Although this method of automation doesn't strictly comply to the spirit of OLE, it does make theprocess of remote automation of Word simple. All that is required is to create an OLE object of theclass "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 orcontrol an OLE automation server such as Word within a Forms module, but you cannot embed norcontrol a Forms module from within Word.

OLE automation client functionality is implemented in Oracle Forms through a number of built-inPL/SQL procedures and functions contained in the OLE2 PL/SQL package. The OLE2 PL/SQLpackage provides a PL/SQL API for creating OLE automation server objects and accessing theproperties and methods of these objects.

The OLE2 PL/SQL package defines two additional PL/SQL datatypes which are used by the OLE2built-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 withits PL/SQL specification:

Object Management

CREATE_OBJ Creates an OLE object and returns an object handle.

CREATE_OBJ(OBJECT IN VARCHAR2) RETURNOBJ_TYPE

RELEASE_OBJ Releases all resources for an OLE object created byCREATE_OBJ and destroys the object handle.


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

SET_PROPERTY(OBJECT IN OBJ_TYPE, PROPERTY INVARCHAR2, VALUE IN NUMBER, ARGLIST INLIST_TYPE)

or

SET_PROPERTY(OBJECT IN OBJ_TYPE, PROPERTY INVARCHAR2, VALUE IN VARCHAR2, ARGLIST INLIST_TYPE)

Object Method Execution

INVOKE Executes a method of an OLE object which returns nothing.

INVOKE(OBJECT IN OBJ_TYPE, METHOD INVARCHAR2, ARGLIST IN LIST_TYPE)

INVOKE_CHAR Executes a method of an OLE object which returns a characterstring.

INVOKE(OBJECT IN OBJ_TYPE, METHOD INVARCHAR2, ARGLIST IN LIST_TYPE) RETURNVARCHAR2

INVOKE_NUM Executes a method of an OLE object which returns a number.

INVOKE(OBJECT IN OBJ_TYPE, METHOD INVARCHAR2, ARGLIST IN LIST_TYPE) RETURN NUMBER

INVOKE_OBJ Executes a method of an OLE object which returns an objecthandle.

INVOKE(OBJECT IN OBJ_TYPE, METHOD INVARCHAR2, ARGLIST IN LIST_TYPE) RETURNOBJ_TYPE


Argument List Management

CREATE_ARGLIST Creates an argument list to be used by an invoked method andreturns an argument list handle.

CREATE_ARGLIST RETURN LIST_TYPE

ADD_ARG Appends a number or character string argument to an argumentlist.

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 examplesof 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 automationserver application. It can also be used to automate an embedded or linked OLE object associatedwith an OLE container item in an Oracle Forms application. The remainder of this article will lookat 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. Thecreation of this WordBasic OLE object (and an object handle for it) establishes an entry point toWord from which OLE automation can begin.

The WordBasic interpreter is not visible. If you want to display the Word application on the screenduring 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 anddisplays the main application window for Word on the screen:


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 theoperations that can be performed from Word's File menu (e.g. create/open a document, create/opena template, execute a macro). To perform more extensive OLE automation, a Word document needsto be opened. The following PL/SQL example extends the previous example by creating a newdocument and inserting some text ( comments are preceded by -- ) :

DECLARE



-- Declare handle to the OLE argument list

args ole2.list_type;

BEGIN




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


ole2.add_arg(args, 'EXAMPLE.DOC');

ole2.invoke(application, 'FileSaveAs', args);


-- Release the OLE object


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 minimiseWindows resource usage and at the very least these objects should be released at the end of thePL/SQL procedure.

• Although the macro above identifies each argument by name, when invoking Word.Basic fromForms, 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 FileNewcommand it was not necessary to specify which document template should be used as thisdefaults to Normal.dot).

• The WordBasic arguments are position dependant so ensure values are supplied for all argumentsup 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 andrecreate the argument list. Failing to do this will result in a new set of arguments being appendedto 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 procedureillustrates the use of a predefined bookmark in a Word document:

DECLARE






BEGIN




-- Open a Word document


ole2.add_arg(args, 'C:\TEMP\EXAMPLE.DOC');

ole2.invoke(application, 'FileOpen', args);


-- Navigate to the bookmark called 'LetterHead'


ole2.add_arg(args, 'LetterHead');

ole2.invoke(application, 'EditGoto', args);


-- Insert text at the bookmark location


ole2.add_arg(args, 'OLE Automation Limited');





END;

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

DECLARE






-- Declare the PL/SQL variable to receive the font name

fontname VARCHAR2(30);

BEGIN




-- Open a Word document


ole2.add_arg(args, 'C:\TEMP\EXAMPLE.DOC');


OLE2.DESTROY_ARGLIST(args);

-- Display the font in use at the insertion point

fontname:=ole2.invoke_CHAR(application, 'Font$');

MESSAGE(fontname);



END;

The following points are worth noting:

• To call a WordBasic function, the OLE2.INVOKE_CHAR or OLE2.INVOKE_NUM proceduresare used instead of the OLE2.INVOKE procedure.

• To determine whether to use OLE2.INVOKE_CHAR or OLE2.INVOKE_NUM you need toknow the datatype of the item being returned from the WordBasic function. You can derive thisfrom the WordBasic function name. Functions returning a character string have a $ as the lastletter 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 mailmerge in Word. The example assumes that the main and data source documents have already beencreated and the placeholders for data source fields have been created in the main document (refer tothe Word online help for details of setting up mail merge documents). The PL/SQL proceduresimply populates the data source document with data from the Oracle database, invokes the mailmerge and saves the resulting file.

DECLARE






-- Declare a SQL cursor to be used to fetch the records from

-- the database.

CURSOR emp_cursor IS select ename, sal from emp;

BEGIN




-- Open the mail merge data source document


ole2.add_arg(args, 'C:\TEMP\MERGE1.DOC');



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


-- Insert employee name


ole2.add_arg(args, emp_record.ename);



-- Move to next column of data table


-- Insert salary


ole2.add_arg(args, TO_CHAR(emp_record.sal));




END LOOP;

-- Open the mail merge main document





-- Perform the mail merge to create the merged document

ole2.invoke(application, 'MailMergeToDoc');

-- Save the merged document to disk





-- Close all three documents without prompting to save any changes

-- ( FileCloseAll 2 = close all without saving changes )


ole2.add_arg(args, 2);

ole2.invoke(application, 'FileCloseAll', args);




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 a temporary local variable for returned text

sel_text VARCHAR2(1000);

BEGIN

-- Start WordBasic


-- Create a temporary document to do the spell check in


-- Insert the text of field CONTROL.LONGFIELD into temporary document


ole2.add_arg(args, :CONTROL.LONGFIELD1);



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


-- 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 automationto Word is to use Word's own macro recorder to record a WordBasic macro for the required actionsand convert the resulting WordBasic macro into a series of OLE2.INVOKE,OLE2.INVOKE_CHAR and OLE2.INVOKE_NUM statements, using argument lists whereappropriate.

If the tasks you want to perform in Word are completely self-contained and do not require anyparameters to be passed in from Oracle Forms, it may be preferable to create a WordBasic macro


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

DECLARE





BEGIN




-- Create a new document


-- Execute the macro called MyMacro


ole2.add_arg(args, 'MyMacro');


ole2.invoke(application, 'ToolsMacro', args);


END;

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


6. Automating Embedded or Linked OLE2 objects

The original concept behind OLE concerned the embedding or linking of objects created by an OLEserver application inside a document created by a different application (referred to as an OLEcontainer application). It is possible to combine this aspect of OLE with OLE automation toautomate an embedded or linked object.

Oracle Forms includes a special OLE container item into which an OLE object can be embedded orlinked. The OLE object classes which can be embedded or linked into an OLE container areregistered 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 containsand must be one of those listed in the OLE registration database. The 'OLE Tenant Types' propertyindicates whether the OLE container holds an embedded or linked OLE object. The 'OLE In-PlaceActivation' property indicates whether the OLE server application shares the Oracle Formsapplication 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 embeddedor 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 beperformed via the 'Word.Basic' class.

To automate an embedded or linked Word document, the OLE2 PL/SQL package must be used inconjunction with the following PL/SQL procedures from the separate PL/SQL built-in packageFORMS_OLE:

Name Description

ACTIVATE_SERVER Activates an OLE server application associated with anOLE container item and prepares it for OLE automation.Takes the name or item id of an Oracle Forms OLEcontainer item as an argument.

EXEC_VERB Causes an OLE server to execute a verb identified by averb name or verb index. An OLE verb specifies an actionyou can perform on an OLE object.

CLOSE_SERVER Deactivates an OLE server application associated with anOLE container item. Terminates the connection betweenthe OLE server and the OLE container.

The following example illustrates how the FORMS_OLE and OLE2 procedures are used to automatean embedded or linked Word document (in this case a standard letter template). The document isstored 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 OracleForms fields to bookmarks in the document. The resulting document is then saved to disk, thechanges undone to restore the template to its original state and the document is closed:

DECLARE






BEGIN

-- Activate Word

forms_ole.activate_server('OLEWORD.DOC');

-- Start WordBasic


-- Open the embedded document for editing

forms_ole.exec_verb('OLEWORD.DOC',1);

-- Go to EmployeeName bookmark


ole2.add_arg(args, 'EmployeeName');



-- Transfer contents of the EMP field to document


ole2.add_arg(args, :EMP.ENAME);



-- Go to Salary bookmark


ole2.add_arg(args, 'Salary');



-- Transfer contents of Salary field to document


ole2.add_arg(args, TO_CHAR(:EMP.SAL));



-- Save the completed document to disk


ole2.add_arg(args, 'C:\TEMP\LETTER1.DOC');



-- Restore the letter template to it's original state

ole2.invoke(application, 'EditUndo');


ole2.invoke(application, 'EditUndo');



-- Close Word

forms_ole.close_server('OLEWORD.DOC');

END;


• The ACTIVATE_SERVER, CREATE_OBJ and EXEC_VERB commands must be performed inthe order given. Due to the relationship between the 'Word.Document' and 'Word.Basic' objectclasses, failure to use this sequence may cause unexpected behaviour (e.g. the Word applicationwindow 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 Wordvisible.

• There is no need to close the embedded document via WordBasic. This is done implicitly by theCLOSE_SERVER command.

• In place of the FileSaveAs command a FilePrint could have been used to send the document tothe printer rather than disk.

• If the embedded Word document is attached to a Word template (.DOT file), a copy of the .DOTfile must exist on all PCs using the document from within Oracle Forms. The .DOT file is notstored 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 beinaccessible.

• 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 doesnot 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 issuedvia 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 someunknown reason) still disallows the use of the FileSave and FileSaveAs commands directly againstan embedded or linked document. However, the FileNew command can be used so a workaround tothis limitation is to create a temporary copy of the embedded or linked document via OLEautomation and work on that. This has the effect of reenabling the restricted commands. Thefollowing PL/SQL procedure illustrates the previous example modified to work with Word V6.0:

DECLARE






BEGIN

-- Activate Word

forms_ole.activate_server('OLEWORD.DOC');

-- Start WordBasic


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


ole2.add_arg(args, 'EmployeeName');



-- Transfer contents of the EMP field to document


ole2.add_arg(args, :EMP.ENAME);



-- Go to Salary bookmark


ole2.add_arg(args, 'Salary');



-- Transfer contents of Salary field to document


ole2.add_arg(args, TO_CHAR(:EMP.SAL));




-- Save the completed document to disk


ole2.add_arg(args, 'C:\TEMP\LETTER1.DOC');



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



ole2.invoke(application, 'FileClose', args);


-- Close the embedded document

forms_ole.close_server('OLEWORD.DOC');



END;


• 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 thisis implicitly closed by the CLOSE_SERVER command.

7. Conclusion

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


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 changewithout notice. Please report any errors to Oracle Corporation. Oracle Corporation does not provide anywarranties 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 theirrespective owners.

forms word

Documents