Accessing PowerBuilder COM servers from clients

You can access the methods on a PowerBuilder COM component
from clients built with any COM-compliant tool. For COM+,
the client must have Microsoft Windows Installer. The COM server
must be registered on the client machine, or the COM+ application
proxy file must be installed.

For how to access PB COM servers from a remote client, see “Using PowerBuilder COM servers
and objects with DCOM”.

The following examples show how you access a PowerBuilder
COM object from Visual Basic or C++. They use
a PowerBuilder COM object that was generated from a user object
called ccuo_employee and has the Program
ID PB110.employee.

For information about building PowerBuilder clients and an
example using the same COM object, see Chapter 28, “Building a COM or COM+ Client.”

Visual Basic as client

In Visual Basic, you can connect to the registered object
using its program ID (late binding). In Visual Basic 5 or later,
you can also use its class name (early binding).

To access a PowerBuilder COM object in Visual
Basic:

1. Do one of the following:

   • Declare an object and connect
     to it using its program ID:
     PowerBuilder

     Dim EmpObj As Object<br />Set EmpObj = CreateObject("PB110.employee")

     1	Dim EmpObj As Object<br />Set EmpObj = CreateObject("PB110.employee")

   • Add a reference to the generated type library for
     the PowerBuilder COM object to your project, then declare an instance
     of the object using its class name (in Visual Basic 5 or later):
     PowerBuilder

     Dim EmpObj As New CoEmployee

     1	Dim EmpObj As New CoEmployee

2. Check that the connection was established:

   PowerBuilder

   Dim response<br />If EmpObj Is Nothing Then<br />response = MsgBox("Creating Employee Object", <br /> vbOKOnly, "Error")<br />End If

   1	Dim response<br />If EmpObj Is Nothing Then<br />response = MsgBox("Creating Employee Object", <br />      vbOKOnly, "Error")<br />End If

3. Access functions or properties of the object:

   PowerBuilder

   Dim units, time as Long<br />Dim DoubleReturn as Double<br />Dim StringReturn As String<br /> <br />DoubleReturn = EmpObj.f_calcdayavg units, time <br />StringReturn = EmpObj.f_teststring<br />EmpObj.ll_hours = 37

   1	Dim units, time as Long<br />Dim DoubleReturn as Double<br />Dim StringReturn As String<br /> <br />DoubleReturn = EmpObj.f_calcdayavg units, time <br />StringReturn = EmpObj.f_teststring<br />EmpObj.ll_hours = 37

4. Destroy the object:

   PowerBuilder

   Set EmpObj = Nothing

   1	Set EmpObj = Nothing

C++ as client

In C++, you use COM library functions to
create an instance of a PowerBuilder COM object. You also need to
use C/C++ definitions of the PowerBuilder COM
objects when you build the client. The Microsoft IDL (MIDL) compiler generates
these definitions from the IDL file created by the PowerBuilder COM
generator.

For example, using the IDL file generated for the Employee
PowerBuilder COM object:

The MIDL compiler generates a header file (employee.h)
containing definitions of the interfaces of all the objects in the
IDL file and a C file (employee_i.c)
that defines the CLSIDs and Interface IDs (IIDs) associated with
the object.

Additional files The MIDL compiler also generates proxy/stub code
(in employee_p.c and dlldata.c),
but you do not need to use the proxy/stub code to build
the C++ client executable or access the PowerBuilder
COM object.

Building a client To build a C++ client executable that can
access methods in a PowerBuilder COM object, you create a C++ source
file that includes the generated header file, compile both the C++ client
source file and the C file generated by the MIDL compiler, then
link the resulting object files to create the executable.

For the Employee example:

1. Create
   a C++ source file called client.cpp (shown
   below).
2. Compile client.cpp.
3. Compile employee_i.c.
4. Link client.obj and employee_i.obj to
   create an executable—for example, employee_ecl.exe.

Employee.h The following code fragments from the employee.h header
file generated by the MIDL compiler show the definitions to be used
by C++ clients:

Client.cpp The following sample client file uses the MIDL-generated C/C++ definitions
of PowerBuilder COM objects. For further information on the COM
API calls shown in client.cpp, see the Microsoft
Software Development Kit documentation.

Using PowerBuilder COM servers and objects with DCOM

A PowerBuilder COM object can be activated from remote clients
using DCOM. The object must be activated in a server process on
the designated host computer. Out-of-process servers (EXE files)
create a server process, but in-process servers (DLL files)
must be hosted in a surrogate process.

COM provides a general-purpose surrogate host (DLLHOST.EXE)
that can be used to host PowerBuilder COM server DLLs. Marking PowerBuilder
COM servers to use a surrogate host is the primary step in enabling
remote client access to your PowerBuilder COM objects. You can use
the DCOM configuration utility (DCOMCNFG.EXE)
to change values for location, security, and identity, but in most
cases the defaults are adequate. For more information, see the online
Help for the DCOMCNFG utility.

Enabling PowerBuilder COM servers to use a surrogate
host

There are two ways to enable PowerBuilder COM servers to use
a surrogate:

• Use the registry editor (REGEDIT32.EXE)
  to edit the PowerBuilder COM server’s AppID registry entry.
• Use the OLE/COM Object Viewer (OLEVIEW.EXE)
  provided with Microsoft Visual C++ 5.0 or greater.

Using OLEVIEW is the preferred approach, because manually
editing your computer’s registry may render all or parts
of your computer’s configuration inoperable.

To enable a COM server to use a surrogate process
using the registry editor:

1. Open the project used to generate the server
   and copy the PowerBuilder COM server’s AppID value from
   the General property page.

2. Run REGEDIT.EXE, find the
   server’s AppID key in My ComputerHKEY_CLASSES_ROOTAppID,
   and select it.

3. Select Edit>New>String Value
   from the menu bar.

4. Enter the name DllSurrogate and
   leave the data field empty.

   An empty data field tells COM to use the default surrogate
   host (DLLHOST.EXE). The AppID value keys should
   look like this:

   Name	Data
   (Default)	PowerBuilder 11.0 generated server: servername.dll
   DllSurrogate	“”

To enable a COM server to use a surrogate process
using the OLE/COM Object Viewer:

1. Run OLEVIEW.EXE.

2. Expand the Automation Objects in the list view
   and select an object in your PowerBuilder COM server.

3. Select an object associated with your PowerBuilder
   COM server.

4. Select the Implementation tab.

5. Select the Inproc Server tab and check the Use
   Surrogate Process check box.

Configuring client computers to activate remote
PowerBuilder COM objects

To activate a remote component, a client application must
pass the object’s class identifier (CLSID) in the activation
request to the remote host.

Some clients, such as those built with PowerBuilder 11.0 or
C++, can use the object’s CLSID in the
method call when they create an instance of a remote object. These
client applications do not require any client-side configuration.

Most clients reference an object by its name (ProgID) rather
than its CLSID. In these cases the client computer’s registry
must contain the information necessary to map a ProgID to a CLSID
in order to make the remote activation request. You can use either
of two methods to add the required registry information to the client
computer:

• Register the PowerBuilder COM server
  on each client computer that requires remote access.
  To use this method, you must be able to locate the appropriate
  version of PBVMn0.DLL.
• On the host where the PowerBuilder COM server is
  registered, export the required registry information into .REG files
  using REGEDIT.EXE, then copy and import these
  files into the registry of each client computer that requires remote
  access.
  For each PowerBuilder COM object, export the following registry
  keys:
  PowerBuilder

  HKEY_CLASSES_ROOTPB110.<i>objectname</i><br />HKEY_CLASSES_ROOTPB110.<i>objectname</i>.<i>version_number</i><br />HKEY_CLASSES_ROOTCLSID{<i>objects_clsid</i>}

  1	HKEY_CLASSES_ROOTPB110.<i>objectname</i><br />HKEY_CLASSES_ROOTPB110.<i>objectname</i>.<i>version_number</i><br />HKEY_CLASSES_ROOTCLSID{<i>objects_clsid</i>}

  You may also need the following registry keys for the PowerBuilder
  COM server:

  PowerBuilder

  HKEY_CLASSES_ROOTTypeLib{<i>comserver_typelib_id</i>}<br />HKEY_CLASSES_ROOTAppID{<i>comserver_application_id</i>}

  1	HKEY_CLASSES_ROOTTypeLib{<i>comserver_typelib_id</i>}<br />HKEY_CLASSES_ROOTAppID{<i>comserver_application_id</i>}

Connecting to remote objects
using PowerBuilder

PowerBuilder clients can use the ConnectToNewRemoteObject function
to activate remote objects, as shown in this code fragment:

You can also use the remote object’s CLSID string
in the classname parameter:

The use of the object’s CLSID as the classname parameter
eliminates the need for any client-side configuration.

Connecting to remote objects using C++

C++ clients that use header files created
from the generated PowerBuilder COM server IDL file can use the
remote object’s CLSID in the activation request:

---