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 PB100.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("PB100.employee")

     1	Dim EmpObj As Object<br />Set EmpObj = CreateObject("PB100.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 10 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 10 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_ROOTPB100.<i>objectname</i><br />HKEY_CLASSES_ROOTPB100.<i>objectname</i>.<i>version_number</i><br />HKEY_CLASSES_ROOTCLSID{<i>objects_clsid</i>}

  1	HKEY_CLASSES_ROOTPB100.<i>objectname</i><br />HKEY_CLASSES_ROOTPB100.<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 6 or greater clients can use the ConnectToNewRemoteObject function
to activate remote objects, as shown in this code fragment:

For PowerBuilder 7 or greater clients, the remote object’s
CLSID string can be used 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:

---