Using a user object as an automation server
Accessing a registered user object as an automation server
involves these steps:
- Create the object you
will access. - Build the object’s runtime library.
- Register the object.
- Write code in the client that connects to and uses
the object.
Creating a class user object to be a server
How you define user objects for an automation server depends
mainly on your application design. The object must be a custom class
user object. You define instance variables and functions for the
object. The object can declare and instantiate other objects for
its own use.
No references to visual objects The class user object you use as an automation server cannot
contain any references to visual objects such as message boxes or
windows.
Objects on the client
You can pass your object references to other objects in the
client application. Those references are of type OLEObject, and
your object can use automation syntax to access properties and methods
of the object. (Automation accesses the object’s instance
variables as properties.)
Testing the user object
Before you try accessing your user object as a server, test
its design and functions in a simpler environment. You can build
an application for testing the user object locally.
Building the object’s runtime library
After you have defined your object, use the Library painter
to build a dynamic library (PBD) or compiled library (DLL). The
reasons for choosing either type (Pcode or compiled machine code)
are the same as for building any PowerBuilder application.
For more information, see “Compiler basics”.
You may want to use the Library painter to reorganize libraries
so that your object and any other objects it instantiates are in
a library by themselves. Otherwise, your library will be bigger
than it needs to be.
Here’s a quick overview of what you need to do to
build your library in the Library painter:
- In the Library painter,
select the library name. - Select Library>Build Runtime Library.
- Check or clear the Machine Code checkbox to correspond
to your decision about PBDs versus DLLs.
Other options in the dialog box are not essential
to this process. For information about them, click the Help button
or see the PowerBuilder User’s Guide
. - Click OK to build the library.
- Move the library to the directory you want it to
be registered in.
Registering the object
To use your object, you have to register it in the registry.
You can also create a type library that provides information to
registry browser applications about your object’s properties
and functions.
For more information, see “More about user objects
and the registry “.
The Automation Server project wizard makes registering and
creating type libraries easy.
To create registry information and register your
object:
-
Select the Automation Server wizard from
the Project tab in the New dialog box. -
Complete all the pages in the wizard.
Use the following table to help you:
Page What to specify Select component Select the object you want to use as
an automation server. You can only select one object. For when to
specify PowerBuilder.Application, see “Creating and using
a named server “Specify Program Identifier Specify an identifier for the object
such as Mycompany.Myapp. Do not supply a version number. PowerBuilder
constructs a version-dependent entry using the version number you
specify on another screen. The identifier can contain up to 39 characters,
must not contain any punctuation apart from the period between vendor
and application, and must not start with a digitSpecify Registry File and Object GUID If the GUID textbox is empty, click Generate
to generate a new globally unique identifier (GUID). The new GUID
will be the class identifier (CLSID) for your object. If you specified
an existing programmatic identifier, the GUID will be filled in.
You can create a new GUID if you don’t want to reuse the
existing one. For information about reusing GUIDs, see “Multiple versions and updates”.The registry update file is a text file containing information for
updating the registry. Typically it has the same name as the library
and the suffix .REGCreate Type Library File You need to create a type library only
if you want OLE browsers to display information about the properties
and methods of your objectSpecify Build Options Check the machine code DLL checkbox if
you built a DLL instead of a PBD file -
Select File>Open from the menu bar and
select the project created by the wizardor
Double-click the Build Project item on the ToDo list.
-
Select Design>Build Project from the
menu bar in the Project painter to generate the registry and type
library files. -
Run the registry file to add information to the
registry.
For more information about the registry and
writing your own registration tool, see “Creating registry
information”.
Writing client code that accesses the user object
The client code for accessing a registered user object is
simpler than the code for accessing PowerBuilder.Application. The
library list and machine code properties are already determined
and stored in the registry. All you need to do is connect to the
object and use automation to access its properties and methods.
PowerBuilder as client
To establish a server automation session with your user object,
you will need code for these steps.
- Declare an OLEObject
variable for your user object:
1OLEObject ole_analyze
- Connect to your object, using its programmatic identifier
(ProgID) and check that the connection was established. A status
of 0 indicates success:1ole_analyze = CREATE OLEObject
1li_status = ole_analyze.ConnectToNewObject &<br /> ("MyCompany.Analyze")
1IF li_status < 0 THEN
1MessageBox("No Server", &
1"Can't connect to MyCompany.Analyze.")
1RETURN
1END IF - Access functions or properties of the object using
automation syntax:1ld_avg = ole_analyze.uof_average()
1ole_analyze.Projection = TRUE
1li_status = ole_analyze.uof_RTFreport(REF ls_rpt)
If you want to handle errors in the OLEObject ExternalException
and Error events, use a user object inherited from OLEObject instead
of declaring an OLEObject variable:
- Open the User Object
painter and create a standard class user object inherited from OLEObject. - Write scripts for the Error and ExternalException
events. - Use the name of the new class instead of OLEObject
in the declaration:1uo_oleobject ole_analyze
Visual Basic as client
Similar code in Visual Basic connects to your registered object.
- Declare an object variable
for your user object:1Dim ole_analyze As Object - Connect to your object, using its programmatic identifier
(ProgID) and check that the connection was established:1Set ole_analyze = CreateObject("MyCompany.Analyze")
1If ole_analyze Is Nothing Then
1REM Handle the error
1End If - Access functions or properties of the object using
automation syntax:1ld_avg = ole_analyze.uof_average()
1ole_analyze.Projection = TRUE
1li_status = ole_analyze.uof_RTFreport(REF ls_rpt)