Using PowerBuilder as an automation server

Using PowerBuilder.Application as an automation server involves
these steps:

1. Define the objects
   you will access.
2. Build the runtime libraries for those objects.
3. Write code in the client that connects to PowerBuilder,
   creates the objects, and accesses their methods and properties.

Creating the user objects you will access

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.

Objects created via automation

When the client instantiates multiple objects in the same
server runtime session, you can pass references to those objects,
enabling the objects to work together.

You can make a PowerBuilder object you create from the client
aware of another by passing it that reference. When the objects
exist in the same session, PowerBuilder accepts the OLE object reference
and also recognizes the underlying PowerBuilder object data type.
This reference gives access to the first object’s properties
and methods just as in any PowerBuilder application.

Keeping this technique in mind, you can define functions for
the user object that accept object references passed from the client,
assign them to the correct variable type, and treat the references
as instantiated PowerBuilder objects, which they are.

Building runtime libraries

After you have defined your objects, use the Library painter
to build PowerBuilder dynamic libraries (PBDs) or compiled libraries
(DLLs). All the libraries accessed in the same PowerBuilder.Application
session must be the same type. The reasons for choosing either type,
Pcode or compiled machine code, are the same as for building any PowerBuilder application.

Here’s a quick overview of what you need to do to
build each library in the Library painter.

1. In the Library painter,
   select the library name.
2. Select Library>Build Runtime Library.
3. 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
   .
4. Click OK to build the library.
5. Repeat steps 1 to 4 for each library specified in
   the LibraryList property of PowerBuilder.Application.
6. Put the resulting PBDs or DLLs in the desired directory.
   The client application will specify the paths so that the server
   can locate them.

For more information about building an application
in the Project painter, see the PowerBuilder User’s
Guide
.

Writing client code that accesses PowerBuilder and
user objects

A client application that wants to establish a PowerBuilder.Application
session needs code to:

• Connect to the server
• Set properties for the server
• Instantiate objects
• Access those objects

All the steps of the process should be accompanied by error
checking because there are any number of reasons why server sessions
can fail.

The following steps with code examples illustrate how to do
it. The first set of steps shows client code for PowerBuilder. A Visual
Basic example follows.

PowerBuilder as a client

To establish a server automation session with PowerBuilder.Application
and access objects, you need code for each of these steps:

1. Declare one OLEObject
   variable for PowerBuilder.Application. Declare additional OLEObject
   variables for each object you will create.
   PowerBuilder

   OLEObject ole_pba, ole_analyze

   1	OLEObject ole_pba, ole_analyze

   If you want to handle errors in the OLEObject ExternalException
   and Error events, use a user object inherited from OLEObject instead.

2. Start the automation server and check that the connection
   was established. A status of 0 indicates success.
   PowerBuilder

   ole_pba = CREATE OLEObject

   1	ole_pba = CREATE OLEObject

   PowerBuilder

   li_status = ole_pba.ConnectToNewObject &amp;<br /> ("PowerBuilder.Application")

   1	li_status = ole_pba.ConnectToNewObject &amp;<br />    ("PowerBuilder.Application")

   PowerBuilder

   IF li_status &lt; 0 THEN

   1	IF li_status < 0 THEN

   PowerBuilder

   MessageBox("No Server", &amp;

   1	MessageBox("No Server", &

   PowerBuilder

   "Can't connect to PowerBuilder.Application.")

   1	"Can't connect to PowerBuilder.Application.")

   PowerBuilder

   RETURN

   1

   RETURN

   PowerBuilder

   END IF

   1

   END IF

3. Set the properties of PowerBuilder.Application, establishing
   the libraries you will access. You cannot change these property
   values after you create objects.
   PowerBuilder

   ole_pba.LibraryList = &amp;

   1	ole_pba.LibraryList = &

   PowerBuilder

   "c:pb9myobjserv1.dll;c:pb9myobjserv2.dll"

   1	"c:pb9myobjserv1.dll;c:pb9myobjserv2.dll"

   PowerBuilder

   ole_pba.MachineCode = TRUE

   1	ole_pba.MachineCode = TRUE

4. Create the first object you want to use and check
   for success. Specify the object’s name as defined in the
   library:
   PowerBuilder

   ole_analyze = ole_pba.CreateObject("uo_analyze")

   1	ole_analyze = ole_pba.CreateObject("uo_analyze")

   PowerBuilder

   IF IsNull(ole_analyze) THEN

   1	IF IsNull(ole_analyze) THEN

   PowerBuilder

   MessageBox("No Object", &amp;

   1	MessageBox("No Object", &

   PowerBuilder

   "Can't create object uo_analyze.")

   1	"Can't create object uo_analyze.")

   PowerBuilder

   RETURN

   1

   RETURN

   PowerBuilder

   END IF

   1

   END IF

5. Access functions or properties of the object using
   automation syntax. (These properties and methods are hypothetical.)
   PowerBuilder

   ld_avg = ole_analyze.uof_average()

   1	ld_avg = ole_analyze.uof_average()

   PowerBuilder

   ole_analyze.Projection = TRUE

   1	ole_analyze.Projection = TRUE

   PowerBuilder

   li_status = ole_analyze.uof_RTFReport(REF ls_rpt)

   1	li_status = ole_analyze.uof_RTFReport(REF ls_rpt)

6. Disconnect from PowerBuilder.Application and destroy
   the objects when you are done. (Exiting your application also accomplishes
   this.)
   PowerBuilder

   DESTROY ole_analyze

   1	DESTROY ole_analyze

   PowerBuilder

   ole_pba.DisconnectObject()

   1	ole_pba.DisconnectObject()

   PowerBuilder

   DESTROY ole_pba

   1	DESTROY ole_pba

Visual Basic version

This example shows typical Visual Basic client code for establishing
a server automation session with PowerBuilder.Application. The steps
are similar to those for PowerBuilder above.

1. Declare an object variable
   for the PowerBuilder.Application. Declare additional object variables
   for each object you will create.
   PowerBuilder

   Dim ole_pba As Object

   1	Dim ole_pba As Object

   PowerBuilder

   Dim ole_analyze As Object

   1	Dim ole_analyze As Object

2. Start the automation server and check that the connection
   was established. A status of 0 indicates success.
   PowerBuilder

   Set ole_pba = CreateObject_<br /> ("PowerBuilder.Application")

   1	Set ole_pba = CreateObject_<br />    ("PowerBuilder.Application")

   PowerBuilder

   If ole_pba Is Nothing Then

   1	If ole_pba Is Nothing Then

   PowerBuilder

   REM Handle the error

   1	REM Handle the error

   PowerBuilder

   End If

   1

   End If

3. Set the properties of PowerBuilder.Application, establishing
   the libraries you will access. You cannot change these property
   values after you create objects.
   PowerBuilder

   ole_pba.LibraryList = _

   1	ole_pba.LibraryList = _

   PowerBuilder

   "c:pbmyobjserv1.dll;c:pbmyobjserv2.dll"

   1	"c:pbmyobjserv1.dll;c:pbmyobjserv2.dll"

   PowerBuilder

   ole_pba.MachineCode = TRUE

   1	ole_pba.MachineCode = TRUE

4. Create the first object you want to use and check
   for success. You specify the object’s name as defined in
   the library:
   PowerBuilder

   Set ole_analyze = ole_pba.CreateObject _

   1	Set ole_analyze = ole_pba.CreateObject _

   PowerBuilder

   ("uo_analyze")

   1	("uo_analyze")

   PowerBuilder

   If ole_analyze Is Nothing Then

   1	If ole_analyze Is Nothing Then

   PowerBuilder

   REM Handle the error

   1	REM Handle the error

   PowerBuilder

   End If

   1

   End If

5. Access functions or properties of the object using
   automation syntax. (These properties and methods are hypothetical.)
   PowerBuilder

   ld_avg = ole_analyze.uof_average()

   1	ld_avg = ole_analyze.uof_average()

   PowerBuilder

   ole_analyze.Projection = TRUE

   1	ole_analyze.Projection = TRUE

   PowerBuilder

   li_status = ole_analyze.uof_RTFreport(REF ls_rpt)

   1	li_status = ole_analyze.uof_RTFreport(REF ls_rpt)

6. Destroy the objects. (Exiting the application also
   accomplishes this.)
   PowerBuilder

   Set ole_analyze = Nothing

   1	Set ole_analyze = Nothing

   PowerBuilder

   Set ole_pba = Nothing

   1	Set ole_pba = Nothing

For complete information about PowerBuilder.Application
functions and properties, see “Runtime
automation server reference “.

---