Deploying an application that uses the automation server
When deploying your objects, you need to coordinate registry
entries with the locations of all the files.
PowerBuilder runtime files
For both PowerBuilder.Application and a registered user object
as a server, you need to deploy the PowerBuilder runtime environment
on each user’s machine.
For information about PowerBuilder deployment
and required files, see Part 9, “Deployment Techniques”.
Instead of the PowerBuilder executable, the registry looks for
the PowerBuilder virtual machine DLL, PBVM90.DLL, to start
the runtime environment. When you deploy, the path for this file
is recorded in the registry. Users should not move the file to another
directory–the registry entry would be made invalid.
Object library and type library
The registry records the location of the library containing
your object and the location of the type library.
Therefore, when you generate a registry update file on your
own computer, path information reflects the file location on your
machine. When you deploy, you can:
- Customize the registry
update file–it is an editable text file. - Make changes to the registry after it has been updated.
You do it programmatically using functions in PowerBuilder or the
Windows SDK or manually with the Registry Editor.
Multiple versions and updates
When you distribute a new version of an object, you can reuse
the GUID that was the CLSID for the previous version or you can
assign a new GUID. Your choice should depend on the degree of compatibility
between the versions.
| Option for the CLSID | Conditions |
|---|---|
| Reuse the GUID | The interface for the object is the same and existing applications can access the same properties and functions that were in the old version |
| Assign a new GUID | The interface has changed and existing applications will fail if they access the new version |
If you assign a new GUID so that the old object remains available
to existing applications, you need a new ProgID too. If the existing
application refers to the version-independent ProgID and you use
the same ProgID for the new version, the old application will connect
to the new object anyway.
When you design your server object, you need to think about
its future development and design current applications accordingly.
Runtime automation server reference
This section describes the PowerBuilder.Application runtime
automation server and its properties and functions:
- PowerBuilder.Application
server object - CreateObject
function - GenerateGUID function
- GenerateRegFile function
- GenerateTypeLib function
- Exception
codes - Sample registry
update file
PowerBuilder.Application server object
Description
PowerBuilder.Application is an automation server. The OLE client
that starts the automation server can be PowerBuilder or some other
client that supports automation and automation object types.
Accessing objects via the server You can access PowerBuilder objects via automation by:
- Connecting an OLEObject
(or the equivalent object type in other client applications) to PowerBuilder.Application,
which starts PowerBuilder as a server application. - Setting properties of PowerBuilder.Application to
specify the PowerBuilder libraries you want to access. - Calling functions that create class user objects
(nonvisual) in those libraries and assigning those objects to additional
OLEObject variables. - Accessing the properties and functions of the user
objects using automation syntax.
Programmable object in the registry PowerBuilder.Application is not a class in the PowerBuilder system
object hierarchy. It is a programmable object registered in the
Windows registry. To see it in the Browser, click the OLE tab and
expand the Programmable Objects category.
Properties
| Property | Data type | Description |
|---|---|---|
| LibraryList | String | A list of filenames separated by semicolons that are the DLLs or PBDs containing the objects you will access in your PowerBuilder.Application session. All the libraries should have the same executable type, either compiled machine code or PcodeSetting LibraryList is effective only before you create any object instances. After the first object is instantiated, changes are ignored |
| MachineCode | Boolean | Specifies whether the objects you will instantiate are generated with machine code or Pcode. Values are:
Setting MachineCode is effective only before you create any |
Functions
| Function | Data type returned | Description |
|---|---|---|
| CreateObject | OLEObject | Creates an instance of a class user object in an OLE server session. An object reference is returned to the client session so that the client can access its properties and functions via automation syntax |
| GenerateGUID | Long | Generates a globally unique identifier and puts the string representation of the identifier in a string variable passed by referenceA network card is required for this function to succeed |
| GenerateRegFile | Long | Generates a file that contains instructions for updating the registry with information about a PowerBuilder object that you want to deploy as an independent automation server |
| GenerateTypeLib | Long | Generates a type library file with browsing information about a PowerBuilder object that you want to deploy as an independent automation server |