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, PBVM100.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 this 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 by means of the server You can access PowerBuilder objects using 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 | Datatype | Description |
|---|---|---|
| LibraryList | String | A list of file names 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 |
| 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 | Datatype 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 by means of automation syntax. |
| GenerateGUID | Long | Generates a globally unique identifier and puts the string representation of the identifier in a string variable passed by reference. A 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. |