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.
You need to declare an OLEObject variable and allocate memory for it:
OLEObject myoleobject myoleobject = CREATE OLEObject
The Object property of the OLE container controls (OLEControl or OLECustomControl) has a datatype of OLEObject.
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 specify. Its purpose is similar to InsertClass for a control. |
ConnectToNewObject |
Create a new OLE object in the specified remote server application if security on the server allows it and associate the new object with a PowerBuilder OLEObject variable. |
ConnectToNewRemoteObject |
Open an existing OLE object from a file. If you do not specify an OLE class, PowerBuilder uses the file’s extension to determine what server to start. |
ConnectToObject |
Associate an OLE object with a PowerBuilder OLEObject variable and start the remote server application. |
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:
OLEObject o1
string s1
o1 = CREATE oleobject
o1.ConnectToNewObject("word.application")
o1.documents.open("c:\temp\temp.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:
myoleobject.ConnectToNewObject("word.basic")
myoleobject.fileopen("c:\temp\letter1.doc")
myoleobject.editgoto("NameAddress")
myoleobject.Insert("Text to insert")
Do not include word.application or word.basic (the class in ConnectToNewObject) as a qualifier:
// 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.
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:
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”.
