OLEObject object type
PowerBuilder’s OLEObject object type is designed for automation.
OLEObject is a dynamic object type, which means that the compiler will
accept any property names, function names, and parameter lists for the
object. PowerBuilder does not have to know whether the properties and
functions are valid. This allows you to call methods and set properties
for the object that are known to the server application that created the
object. If the functions or properties do not exist during execution,
you will get runtime errors.
Using an OLEObject variable involves these steps:
-
Declare the variable and instantiate it.
-
Connect to the OLE object.
-
Manipulate the object as appropriate using the OLE server’s
properties and functions. -
Disconnect from the OLE object and destroy the
variable.
These steps are described next.
Declaring an OLEObject
variable
You need to declare an OLEObject variable and allocate memory for
it:
|
1 2 |
OLEObject myoleobject myoleobject = CREATE OLEObject |
The Object property of the OLE container controls (OLEControl or
OLECustomControl) has a datatype of OLEObject.
Connecting to the server
You establish a connection between the OLEObject object and an OLE
server with one of the ConnectToObject functions. Connecting to an
object starts the appropriate server:
|
When you want to |
Choose this function |
|---|---|
|
Create a new object for an OLE server that you |
ConnectToNewObject |
|
Create a new OLE object in the specified remote |
ConnectToNewRemoteObject |
|
Open an existing OLE object from a file. If you do |
ConnectToObject |
|
Associate an OLE object with a PowerBuilder |
ConnectToRemoteObject |
After you establish a connection, you can use the server’s command
set for automation to manipulate the object (see OLE objects in
scripts).
You do not need to include application qualifiers for the
commands. You already specified those qualifiers as the application’s
class when you connected to the server. For example, the following
commands create an OLEObject variable, connect to Microsoft Word ‘s OLE
interface (word.application), open a document and display information
about it, insert some text, save the edited document, and shut down the
server:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 |
OLEObject o1 string s1 o1 = CREATE oleobject o1.ConnectToNewObject("word.application") o1.documents.open("c: emp emp.doc") // Make the object visible and display the // MS Word user name and file name o1.Application.Visible = True s1 = o1.UserName MessageBox("MS Word User Name", s1) s1 = o1.ActiveDocument.Name MessageBox("MS Word Document Name", s1) //Insert some text in a new paragraph o1.Selection.TypeParagraph() o1.Selection.typetext("Insert this text") o1.Selection.TypeParagraph() // Insert text at the first bookmark o1.ActiveDocument.Bookmarks[1].Select o1.Selection.typetext("Hail!") // Insert text at the bookmark named End o1.ActiveDocument.Bookmarks.item("End").Select o1.Selection.typetext("Farewell!") // Save the document and shut down the server o1.ActiveDocument.Save() o1.quit() RETURN |
For earlier versions of Microsoft Word, use word.basic instead of
word.application. The following commands connect to the Microsoft Word
7.0 OLE interface (word.basic), open a document, go to a bookmark
location, and insert the specified text:
|
1 2 3 4 |
myoleobject.ConnectToNewObject("word.basic") myoleobject.fileopen("c: empletter1.doc") myoleobject.editgoto("NameAddress") myoleobject.Insert("Text to insert") |
Do not include word.application or word.basic (the class in
ConnectToNewObject) as a qualifier:
|
1 2 |
// Incorrect command qualifier myoleobject.word.basic.editgoto("NameAddress") |
Microsoft Word 7.0 implementation
For an OLEObject variable, word.basic is the class name of Word
7.0 as a server application. For an object in a control, you must use
the qualifier application.wordbasic to tell Word how to traverse its
object hierarchy and access its wordbasic object.
Shutting down and disconnecting from the
server
After your application has finished with the automation, you might
need to tell the server explicitly to shut down. You can also disconnect
from the server and release the memory for the object:
|
1 2 3 |
myoleobject.Quit() rtncode = myoleobject.DisconnectObject() DESTROY myoleobject |
You can rely on garbage collection to destroy the OLEObject
variable. Destroying the variable automatically disconnects from the
server.
It is preferable to use garbage collection to destroy objects, but
if you want to release the memory used by the variable immediately and
you know that it is not being used by another part of the application,
you can explicitly disconnect and destroy the OLEObject variable, as
shown in the code above.
For more information, see Garbage collection and memory
management.