Building COM/COM+ components in the Project painter
You build PowerBuilder COM servers in the Project painter.
If you did not create a project when you created the user
object, you can use the COM/COM+ Project wizard
to create one. You can also set up a project to build a COM component
directly in the Project painter by selecting the COM/COM+ Component
icon on the Projects tab.
If you have already created a COM/COM+ project
for one or more of the objects you want to build into a COM server,
you can modify it in the Project painter, adding additional objects
if necessary.
The Project painter workspace is a read-only display that
shows the options you selected in the wizard or in the Select Objects
and Properties dialog boxes in the painter. When you build a PowerBuilder COM
server, the workspace also displays an object inspection report
and the status of each phase of the build process.
To define and build a PowerBuilder COM server project:
-
Select COM/COM+ Component
Wizard from the Projects tab in the New dialog box. -
Specify project properties including the project’s
name and location. -
Select one or more objects that you want to build
into a server. -
Specify the properties of each object and optional
COM+ deployment options and click Finish.For help specifying properties, see the context-sensitive
Help in the wizard or the following topics:Property For information see Interface options “Choosing a custom or dual
interface” and “Instance variables”Build options “Setting up the embedded
PBD “Registering components “Registering components automatically” COM+ deployment and package
options“Deploying components to
COM+”COM+ transaction settings “Specifying whether a component
supports transactions “COM+ security “Security issues” -
Select File>Open and select the project
you just created to open the Project painter.You can verify that the correct objects are selected by selecting Edit>Select
Objects from the menu bar. -
Select Edit>Properties to verify and
optionally modify the properties you set in the wizard.Some advanced COM+ package properties can be set
only in the Project painter. -
Click the Build button in the Project painter
to build the PowerBuilder COM server.The build process creates an IDL file and a PowerBuilder COM
server (DLL) containing a PowerBuilder COM object for each user object
you selected. If you specified deployment to COM+ and it
is installed and running on the computer where you are generating
the component, the component is deployed directly to the server,
and additional deployment files can be created.The PowerBuilder COM server also contains an embedded PBD file
that contains the custom class user objects and any additional objects
they reference, and an embedded type library.
Building a project after calling an object When you call a COM object in the development environment,
the COM object stays in memory until you exit PowerBuilder, because
it is hosted in the same process as PowerBuilder. If you make a
change to the object after calling it and try to regenerate it in
the Project painter, you receive compile and link errors. Before
you build the project, shut down and restart PowerBuilder to free
the object from memory.
Registering components automatically
In the Project wizard or Project painter, you can choose to
register all generated PowerBuilder COM objects automatically when
a build is successful. This makes it easy to test the component
on your computer. To avoid making unnecessary registry entries on
your computer, select this option only when you are ready to test
the PowerBuilder COM server.
Deploying components to COM+
You can deploy components to
COM+ automatically when a build is successful. You can
also export the application to a Microsoft Windows Installer (MSI)
file that you can use to import the package into a COM+ server on
another computer, and export an application proxy as an MSI file
that can be installed on a client computer so that it can access
the COM+ server remotely. For more information about deploying
COM+ components, see the Microsoft COM+ documentation
in the MSDN Library
.
Choosing a custom or dual interface
When you generate a PowerBuilder COM object, you must choose
whether to expose a custom interface or a dual interface to clients.
In PowerBuilder COM objects, both interface types are currently restricted
to the use of standard OLE automation datatypes.
Custom interfaces
Custom interfaces provide access to server object virtual
function tables (VTBL), offering higher performance than dispatch-based
interfaces and a cleaner usage model than dual interfaces. Consider
using a custom interface if the intended client is in a compiled
language such as C++ or if you want to take advantage
of the support for custom interfaces in a tool such as Visual Basic.
PowerBuilder COM objects that use custom interfaces use the
standard marshaling provided by COM.
Dual interfaces
Dual interfaces allow programmers to call methods in the COM
object through virtual function tables as well as through the dispatch
interface. They support a wide range of clients and give fast access
to methods.
Setting up the embedded PBD
The COM server contains an embedded PowerBuilder dynamic library
(PBD) file that contains compiled versions of all the custom class
user objects you selected plus any dependent objects. You can include
additional, unreferenced objects in the PBD by selecting the library
that contains the objects on the Library properties page. All the
objects in selected libraries are included in the PBD.
You can specify the name of a PowerBuilder Resource (PBR) file
associated with the library. A PBR file is a text file that lists
dynamically assigned resources such as bitmaps. For more information,
see “About resources”.