Inbound OLE Automation
\The Sandbox \PB History & Future \New in PB 5 \Inbound OLE Automation
UI Changes
Code Generation
Distributed PB
Inbound OLE
Automation
Component
Gallery
PFC
ObjectCycle
DW
Enhancements
DB Changes
OO
Enhancements
Internationalization
PowerScript
Enhancements

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:

  1. Create a Non-visual class.
  2. Define any functions that you want exposed through OLE Automation to be “public” scope.
  3. Define any attributes that you want exposed through OLE Automation to be “public” scope.
  4. Create the appropriate registry file (.REG file) using a unique identifier.
  5. 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). 

PBL Peeper PB Help PB History
& Future About Us Feedback Site Map

Google
 
Web www.techno-kitten.com
www.sybase.com