Building COM/MTS 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/MTS Project wizard to create
one. You can also set up a project to build a COM or MTS component
directly in the Project painter by selecting the COM/MTS
Component icon on the Projects tab.
If you have already created a COM/MTS 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/MTS 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
MTS 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” MTS deployment and package options “Deploying components to
MTS”MTS transaction settings “Specifying whether a component
supports transactions “MTS 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 MTS package properties can only be set 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 MTS and MTS is installed
and running on the computer where you are generating the component,
the component is deployed directly to the MTS server and additional
MTS 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 plus an embedded type library.
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 toMTS
If MTS administration objects are installed on your computer,
you can deploy components to MTS automatically when a build is successful.
You can also export the package to a PAK file that you can use to
import the package into an MTS server on another computer, and create
a client configuration utility file.
About the client configuration utility
The client configuration utility is an executable file that
adds to a client computer all the information required to use the
components in the package, including registry information and the
component’s type library. The client configuration utility
file has the same name as the PAK file plus the extension EXE and
is created in a subdirectory called clients.
Creating a type library for clients
You can choose to create a separate type library file to be
used by client applications. If you do not, the client configuration
utility will obtain type library information by including the DLL
for the COM server. The version of the PowerBuilder virtual machine
(PBVM70.DLL) used by the COM server must also be installed
on the client if you do not provide a separate type library.
For more information about deploying to MTS, see “Deploying PowerBuilder COM
objects to MTS”.
Choosing a custom or dualinterface
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 data types.
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
5.
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 embeddedPBD
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”.