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 |
OLEObject myoleobject<br>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 |
ConnectToNewObject |
|
Create a new OLE object in the specified |
ConnectToNewRemoteObject |
|
Open an existing OLE object from a file. |
ConnectToObject |
|
Associate an OLE object with a PowerBuilder OLEObject |
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 |
OLEObject o1<br>string s1<br>o1 = CREATE oleobject<br> <br>o1.ConnectToNewObject("word.application")<br>o1.documents.open("c: emp emp.doc")<br> <br>// Make the object visible and display the <br>// MS Word user name and file name<br>o1.Application.Visible = True<br>s1 = o1.UserName<br>MessageBox("MS Word User Name", s1)<br>s1 = o1.ActiveDocument.Name<br>MessageBox("MS Word Document Name", s1)<br> <br>//Insert some text in a new paragraph<br>o1.Selection.TypeParagraph()<br>o1.Selection.typetext("Insert this text")<br>o1.Selection.TypeParagraph() <br> <br>// Insert text at the first bookmark<br>o1.ActiveDocument.Bookmarks[1].Select<br>o1.Selection.typetext("Hail!")<br> <br>// Insert text at the bookmark named End<br>o1.ActiveDocument.Bookmarks.item("End").Select<br>o1.Selection.typetext("Farewell!")<br> <br>// Save the document and shut down the server<br>o1.ActiveDocument.Save()<br>o1.quit()<br>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 |
myoleobject.ConnectToNewObject("word.basic")<br>myoleobject.fileopen("c: empletter1.doc")<br>myoleobject.editgoto("NameAddress")<br>myoleobject.Insert("Text to insert") |
Do not include word.application or word.basic
(the class in ConnectToNewObject) as a qualifier:
|
1 |
// Incorrect command qualifier<br>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 |
myoleobject.Quit() <br>rtncode = myoleobject.DisconnectObject()<br>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”.