PowerScript Reference
PowerScript Functions

Description

Creates a new object in the specified server application and associates it with a PowerBuilder OLEObject variable. ConnectToNewObject starts the server application if necessary.

Applies to

OLEObject objects, OLETxnObject objects

Syntax

oleobject.ConnectToNewObject ( classname )

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

-9 -- Other error

-15 -- COM+ is not loaded on this computer

-16 -- Invalid Call: this function not applicable

If any argument's value is null, ConnectToNewObject returns null.

Usage

The OLEObject variable can be used for automation, in which the PowerBuilder application asks the server application to manipulate the OLE object programmatically. It can also be used to connect to a COM object that is registered on a local or remote computer or that is installed in COM+.

The OLETxnObject variable is used to provide COM+ transaction control to PowerBuilder clients. Calling ConnectToNewObject with an OLETxnObject variable creates a new object instance within the transaction context associated with the variable. If COM+ is not loaded on the client computer, the ConnectToNewObject call fails. Use SetAbort to abort the transaction or SetComplete to complete it if all other participants in the transaction concur.

For more information about automation and connecting to COM objects, see ConnectToObject.

Examples

This example demonstrates how to use OLE automation in PowerBuilder to start Microsoft Excel, create a workbook, write data to a worksheet, save the file, and properly close and release the Excel objects:

// Declare OLE object variables
OLEObject ole_excel, ole_workbook, ole_sheet
long ll_col, ll_row
integer li_ret

// Create OLE object instances
ole_excel = CREATE OLEObject
ole_workbook = CREATE OLEObject
ole_sheet = CREATE OLEObject

// Connect to Excel
li_ret = ole_excel.ConnectToNewObject("Excel.Application")
IF li_ret <> 0 THEN
    MessageBox("Error", "Unable to start Excel!")
    RETURN
END IF

// Set Excel to be visible
ole_excel.Application.Visible = True

// Add a new workbook
ole_workbook = ole_excel.Application.Workbooks.Add()
ole_sheet = ole_workbook.Worksheets(1)

// Write data
ole_sheet.Cells(1, 1).Value = "Name"
ole_sheet.Cells(1, 2).Value = "Age"
ole_sheet.Cells(1, 3).Value = "Department"

ole_sheet.Cells(2, 1).Value = "Sam"
ole_sheet.Cells(2, 2).Value = 25
ole_sheet.Cells(2, 3).Value = "Technical Department"

// Save the file
ole_excel.ActiveWorkbook.SaveAs("C:\work\ole2026.xlsx")

// Close Excel
ole_workbook.Close()
ole_excel.Quit()

// Disconnect the OLE objects
ole_excel.DisconnectObject()
ole_workbook.DisconnectObject()
ole_sheet.DisconnectObject()

// Destroy the objects
DESTROY ole_excel
DESTROY ole_workbook
DESTROY ole_sheet

This example creates an OLETxnObject variable and calls ConnectToNewObject to create and connect to a new instance of a COM object on a COM+ server

OLETxnObject ole_Obj
Integer li_rc, li_rtn
string ls_rtn
double ldb_area

ole_Obj  = CREATE OLETxnObject
li_rc = ole_Obj.ConnectToNewObject("ComServerTest.ClassName")
IF li_rc < 0 THEN
    DESTROY ole_Obj
    MessageBox("Connecting to COM Object Failed",  &
      "Error: " + String(li_rc))  
  Return
END IF 
// Perform some work with the COM object
...

// If the work completed successfully, commit
// the transaction and disconnect the object
li_rc = ole_Obj.SetComplete()
li_rc = ole_Obj.DisconnectObject()

Destroy ole_Obj

See also

ConnectToObject

DisconnectObject

SetAbort

SetComplete