|
Overview
PowerBuilder 5.0 non-visual objects may be driven through OLE (Object Linking and Embedding) automation. By driven, we mean that any client program capable of OLE automation may create an instance of that type and read or write properties or invoke its methods.
A Visual Basic programmer may do just this using the syntax below:
Dim PBObject as object
PBObject = CreateObject("uo_1")
if PBObject is nothing then
REM handle the error
else
PBObject.SomeAttribute = 5
PBObject.DoSomething(12, 14, "Hello")
PBObject = nothing
end if
A PowerBuilder programmer would use the following syntax to accomplish the same task:
oleObject PBObject
long status
PBObject = create oleObject
status = PBObject.ConnectToNewObject("uo_1")
if (status < 0) then
// handle the error
else
PBObject.SomeAttribute = 5
PBObject.DoSomething(12, 14, "Hello")
PBObject.Disconnect()
end if
destroy PBObject
In both cases above, the script attempts to create an instance of the object and, if successful, sets an attribute and then calls a function.
OLE automation, while available for embedded and linked objects and for OLE Custom Controls, is not limited to visual controls. The PowerBuilder implementation provides automation clients with access to non-visual objects using the same technology. Non-visual objects may be deployed as In-Process OLE Automation Servers.
In order to make PowerBuilder objects available to OLE, registry entries must be created to help OLE find the PowerBuilder object. The entries translate the programmatic identifier (“uo_1” in the example above) into a globally unique identifier. That unique identifier is used by OLE services to locate the PowerBuilder DLL (Dynamic Link Library) required. Additional entries are then used by PowerBuilder to set the library list and executable type (pCode or machine code), start a run-time and then finally to create the appropriate object instance and return it for use by the client.
PowerBuilder.Application
A more advanced service is also available for driving PowerBuilder objects. With the OLE automation programmatic identifier PowerBuilder.Application you can connect an automation client program to a PowerBuilder run-time. After setting the LibraryList property, you can create instances of non-visual objects with the CreateObject method. CreateObject takes a PowerBuilder class name as a string. While this approach is more complex to use, it provides more flexibility at run time and does not require that the translation information described previously be recorded in the registry. In effect, the classes may be private and need not be made available to other OLE clients.
A Visual Basic programmer may do this using the syntax below:
Dim PBObject as object
Dim PBNVObject as object
PBObject = CreateObject(“PowerBuilder.Application”)
if PBObject is nothing then
REM handle the error
else
PBObject.LibraryList = “c:\myappl\mylibrary.dll”
PBNVObject = PBObject.CreateObject(“nvo_myobject”)
if PBNVObject is nothing then
REM handle the error
else
PBNVObject.DoSomething(12, 14, “Hello”)
PBNVObject = nothing
end if
PBObject = nothing
end if
Properties of PowerBuilder.Application
string LibraryList
This property contains the library list to be searched for classes when creating object instances. The list must be assigned prior to the creation of the first object. Once an object has been instantiated the library list is fixed and the attribute will be ignored.
boolean MachineCode
This property defaults to TRUE. If you wish to instantiate pCode objects you must set the attribute to FALSE. As with the LibraryList attribute, this attribute is ignored once the first object instance is created. All subsequent object instances must be of the same type (pCode or machine code).
Methods of PowerBuilder.Application
automationobject CreateObject(string PowerBuilderClassName)
CreateObject accepts a PowerBuilder class name and attempts to create an instance of that class. PowerBuilder will search the library list set prior to the creation of the first object instance.
Return Values: Returns the object requested or a null object (in VB this is “nothing”).
long GenerateGUID(REF string GUID)
GenerateGUID creates a new Globally Unique Identifier and returns the string representation of that identifier in a reference parameter. This identifier should then be passed on to GenerateReg
Return Values:
0 GUID generated successfully
-1 Unable to load required DLL to generate the GUID
-2 No network card was found. Unable to generate GUID.
-3 Create GUID failed.
-9 Unknown error.
long GenerateRegFile(string GUID, // As created by GenerateGUID above
string ClassName, // PowerBuilder NVO Class Name
string ProgID, // OLE Programmatic Identifier
integer MajorVersion, // Major Version
integer MinorVersion, // Minor Version
string Description // Descriptive name to be displayed by OLE
string TargetFile) // Text file to create
GenerateRegFile creates a file with registry update instructions for deploying an object as an OLE Automation server object.
Return Values:
0 Target registry file created successfully
-1 Memory allocation error.
-2 No target file name provided.
-3 Unable to open target file.
-9 Unknown error.
Notes:
1. The LibraryList and MachineCode attributes must be set to the desired values before making this call.
2. GUID is a string of the format {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}. Make a call to GenerateGUID prior to calling GenerateRegFile to generate a new GUID.
Creating PowerBuilder Non-visual Objects For Use As OLE Automation Servers
To create and install a PowerBuilder non-visual object for use by OLE Automation clients, you must complete the following steps:
- Create a Non-visual class.
- Define any functions that you want exposed through OLE Automation to be “public” scope.
- Define any attributes that you want exposed through OLE Automation to be “public” scope.
- Create the appropriate registry file (.REG file) using a unique identifier.
- Merge the registry file into the registry on the target machine.
Assuming the first three steps are understood, the remaining question is how to create the registry file and merge it.
The OLE Automation object PowerBuilder.Application exposes two methods which can be used to create the appropriate unique identifier (GUID - Globally Unique Identifier) and then to create a registry file that can be used to update the registry on the client machine.
A sample PowerBuilder script for creating a GUID and then generating a registry file for a pCode object:
oleObject PBObject
string GUID
long result
PBObject = create oleObject
// Establish a connection with PowerBuilder.Application
result = PBObject.ConnectToNewObject(“PowerBuilder.Application”)
if result < 0 then
// handle the error
else
PBObject.LibraryList = “c:\myappl\mylibrary.dll”// Set the library list
PBObject.MachineCode = false // This is a pCode object
result = PBObject.GenerateGUID(REF GUID)
if (result < 0) then
// handle the error
else
result = PBObject.GenerateRegFile( GUID, “nvo_mypbclassname”, “MyProgrammable.Object”
1, 0,
“This is my first OLE Automation Object”,
“C:\myproj\mynvo.reg”)
end if // GUID created successfully
end if // Connection to PowerBuilder.Application established successfully
Notes:
1. See Appendix B for a sample of the registration file produced by this script.
2. After creating the registration file, it can be merged into the registry of the client machine by running REGEDIT.
PBGENREG.EXE Sample:
Installation and Deployment Issues
PowerBuilder Installation
Two new files need to be included in the both PowerBuilder development environment installation and the run-time deployment installation.
PBAPPL.REG The English language registration file for PowerBuilder.Application.
PBAEN050.TLB The English language type library for PowerBuilder.Application
When the application is installed, PBAPPL.REG must be merged into the registry and the path for PBROI050.DLL and PBAEN050.TLB must be updated to reflect the installed directory.
Notes:
1. PBAPPL.REG and PBAEN050.TLB need only be installed for run-times which need access to PowerBuilder.Application. This could be made optional.
Deployment of PowerBuilder Non-Visual Objects
For each Non-Visual object deployed, a customer generated registry file (.REG file) must be installed. Presumably the companion product PBSetup will offer this capability.
Limitations and Other Considerations
Are automation objects pCode or machine code? Do I have a choice?
OLE Automation created by PowerBuilder may be either pCode or Machine Code objects
For objects accessed through programmatic identifiers in the registry, the registry entry indicates the binary type of the object (pCode or machine code).
The object PowerBuilder.Application defaults to a machine code implementation. To use pCode objects (PBDs or PBLS) you must set the MachineCode attribute of the instantiated object to FALSE prior to creating the first object.
Can I mix pCode and machine code objects?
Yes and no.
Each object created through a programmatic identifier gets its own run-time session. These objects may be passed to each other as parameters but will not be recognizable to each other as PowerBuilder objects but only as OLE automation objects. As a result, mixing the two types is perfectly acceptable since they will interact only as OLE automation objects.
You cannot create both a pCode and a machine code object from the same object instance of PowerBuilder.Application. If you create more than one PowerBuilder.Application object instance, they may be used to create instances of different types (pCode or machine code).
|
