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:

Open the project used to generate the server and copy the PowerBuilder COM server’s AppID value from the General property page.
Run REGEDIT.EXE, find the server’s AppID key in My Computer\HKEY_CLASSES_ROOT\AppID, and select it.
Select Edit>New>String Value from the menu bar.
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.5 generated server: servername.dll

DllSurrogate

""

Name	Data
(Default)	PowerBuilder 10.5 generated server: servername.dll
DllSurrogate	""

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

Run OLEVIEW.EXE.
Expand the Automation Objects in the list view and select an object in your PowerBuilder COM server.
Select an object associated with your PowerBuilder COM server.
Select the Implementation tab.
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.5 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:
```
HKEY_CLASSES_ROOT\PB105.objectname
HKEY_CLASSES_ROOT\PB105.objectname.version_number
HKEY_CLASSES_ROOT\CLSID\{objects_clsid}
```
You may also need the following registry keys for the PowerBuilder COM server:
```
HKEY_CLASSES_ROOT\TypeLib\{comserver_typelib_id}
HKEY_CLASSES_ROOT\AppID\{comserver_application_id}
```

Connecting to remote objects using PowerBuilder

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

OLEObject remobj
remobj = CREATE OLEObject
remobj.ConnectToNewRemoteObject("myremotehostname",  &
    "PB105.employee")

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

remobj.ConnectToNewRemoteObject("myremotehostname",  &
    "clsid:0EA53FED-646A-11D2-BF8E-00C04F795006")

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:

COSERVERINFO ServerInfo;
MULTI_QI    mqi[1];
OLECHAR    wszHostName[MAXFILE];
LPTSTR     pszHost=NULL;

memset(&ServerInfo,0,sizeof(ServerInfo));
pszHost =GetUserRequestedHostName();
mbstowcs(wszHostName,pszHost,MAXFILE);

ServerInfo.pwszName = wszHostName;
mqi[0].pIID = &IID_Iemployee;
mqi[0].pItf = NULL;
mqi[0].hr   = S_OK;

// Create employee object on the desired server
hr = CoCreateInstanceEx(CLSID_Employee,NULL,
       CLSCTX_REMOTE_SERVER,&ServerInfo,1,mqi);