Description
Associates an OLE object with a PowerBuilder OLEObject variable and starts the server application. The OLEObject variable and ConnectToObject are used for OLE automation, in which the PowerBuilder application asks the server application to manipulate the OLE object programmatically.
Applies to
OLEObject objects
Syntax
oleobject.ConnectToObject ( filename {, classname } )
|
Argument |
Description |
|---|---|
|
oleobject |
The name of an OLEObject variable which you want to connect to an OLE object. You cannot specify an OLEObject that is the Object property of an OLE control. |
|
filename |
A string whose value is the name of an OLE storage file. You can specify the empty string for filename, in which case you must specify classname. Oleobject is connected to the active object in the server application specified in classname. |
|
classname (optional) |
A string whose value is the name of an OLE class, which identifies an OLE server application and a type of object that the server can manipulate via OLE. If you omit classname, PowerBuilder uses the extension of filename to determine what server application to start. |
Return value
Integer.
Returns 0 if it succeeds and one of the following negative values if an error occurs:
-1 -- Invalid call: the argument is the Object property of a control
-2 -- Class name not found
-3 -- Object could not be created
-4 -- Could not connect to object
-5 -- Ca not connect to the currently active object
-6 -- Filename is not valid
-7 -- File not found or file could not be opened
-8 -- Load from file not supported by server
-9 -- Other error
-15 -- COM+ is not loaded on this computer
-16 -- Invalid Call: this function not applicable to OLETxnObject
If any argument's value is null, ConnectToObject returns null.
Usage
After you have created an OLEObject variable and connected it to an OLE object and its server application, you can set properties and call functions supported by the OLE server. PowerBuilder's compiler will not check the syntax of functions that you call for an OLEObject variable. If the functions are not present when the application is run or the property names are invalid, an execution error occurs.
Declare and create an OLEObject variable
You must use the CREATE statement to allocate memory for an OLEObject variable, as shown in the example below.
When you create an OLEObject variable, make sure you destroy the object before it goes out of scope. When the object is destroyed it is disconnected from the server and the server is closed. If the object goes out of scope without disconnecting, there will be no way to halt the server application.
Check the documentation for the server application to find out what properties and functions it supports. Some applications support a large number. For example, Excel has approximately 4000 operations you can automate.
The OLEObject datatype supports OLE automation as a background activity in your application. You can also invoke server functions and properties for an OLE object in an OLE control. To do so, specify the Object property of the control before the server function name. When you want to automate an object in a control, you do not need an OLEObject variable.
For example, the following changes a value in an Excel cell for the object in the OLE control ole_1:
ole_1.Object.application.cells(1,1).value = 14
Examples
This example declares and creates an OLEObject variable and connects to an Excel worksheet, which is opened in Excel. It then sets a value in the worksheet, saves it, and destroys the OLEObject variable, which exits the Excel:
integer result OLEObject myoleobject myoleobject = CREATE OLEObject result = myoleobject.ConnectToObject( & "c:\excel\expense.xls") IF result = 0 THEN myoleobject.application.workbooks(1).& worksheets(1).cells(1,1).value = 14 myoleobject.application.workbooks(1).save() END IF DESTROY myoleobject
This example connects to an Excel chart (using a Windows path name):
integer result OLEObject myoleobject myoleobject = CREATE OLEObject result = myoleobject.ConnectToObject( & "c:\excel\expense.xls", "excel.chart")
This example connects to the currently active object in Excel, which is already running:
integer result
OLEObject myoleobject
myoleobject = CREATE OLEObject
result = myoleobject.ConnectToObject("", &
"excel.application")See also
