E175 Introduction to PBNI

1
E175 Introduction to PBNI

• Xue-song Wu
• Staff Software Engineer
• Sybase Asia Development Centre
• Enterprise Solutions Division
• xue-song.wu_at_sybase.com

2
Topics

• Why need PBNI?
• What is PBNI?
• What can we do with PBNI?
• The future of PBNI

3
Three Questions

• Have you ever asked the following questions?
• Is it possible to call C/C functions from
  PowerScript?
• Is it possible to call external component, such
  as EJB, WebService, Java, and so on, from
  PowerScript?
• Is it possible to call PowerScript from C/Java?

4
Calling C/C functions from PowerBuilder

• Existing solution external functions
• External functions allow you to call C functions
  from PowerScript.
• Examples
• FUNCTION ulong GetSysColor (int index) LIBRARY
  "USER32.DLL
• FUNCTION boolean sndPlaySoundA (string
  SoundName, uint Flags) LIBRARY "WINMM.DLL"

5
Calling C/C functions from PowerBuilder

• Limitation of external functions
• Its not possible to declare an external function
  that requires a callback function.BOOL
  EnumWindows(WNDENUMPROC lpEnumFunc, LPARAM
  lParam)
• Some C data types cannot be mapped to
  PowerBuilder data types, such as double.
• It is not object-oriented.
• You have to declare the external functions
  whenever you want to use them.

6
Calling EJBs, WebServices, and so on from
PowerBuilder

• You can call EJBs through COM to EJB bridge.
• You can call Web Services using CSXtend from
  Cynergy Systems.
• But there is not an easy and standard way for
  third parties to implement the features that can
  marshal PowerBuilder requests to other components
  and unmarshel the result back to PowerBuilder.

7
Calling PowerScript from C/Java

• You can call a NVO from VB/C by making the NVO
  an OLE automation server.
• But there is not an easy and standard way to do
  that.

8
PBNI is the answer

• PBNI (PowerBuilder Native Interface) is a
  standard interface that allows third parties to
  extend the functionalities of PowerBuilder.
• PBNI opens two doors from PowerBuilder to outside
  world

IPB_Session
IPB_VM
C/Java Application
PBVM
PB Extension
IPB_Session
IPBX_NonVisualObject
9
The elements of PBNI

• Interfaces IPB_VM, IPB_Session, IPB_Value,
  IPB_Arguments, IPBX_NonVisualObject, and
  IPBX_Marshaler.
• Structures PBCallInfo and PBArrayInfo.
• Global Functions PBX_GetDescription(),
  PBX_CreateNonVisualObject(), and
  PBX_InvokeGlobalFunction()
• Helper classes, such as PBObjectCreator,
  PBObjectFunctionInvoker, PBArrayAccessor, and so
  on.

10
What can we do with PBNI?

• Create PB extensions
• Create PB marshaler extensions
• Embed PB into C/Java applications

11
PB Extension

• A PB Extension is a DLL that provides one or more
  native classes to be used as normal PowerBuilder
  classes.
• A PB extension must expose the following
  functions
• PBXEXPORT LPCTSTR PBXCALL PBX_GetDescription()
• PBXEXPORT PBXRESULT PBXCALL PBX_CreateNonVisualObj
  ect(...)

12
Creating a PB Extension

• Steps for creating a PB extension
• Write the description of the PB Extension.
• Implement a C class for each native class
  described.
• Implement the required global functions, such as
  PBX_GetDescription(), PBX_CreateNonVisualObject(),
  and so on.
• Build the DLL.
• Generate a .PBD file for the DLL by using pbx2pbd
  tool.

13
Creating a PB Extension

• Describing a PB Extension
• class xmlevent from nonvisualobject
• event boolean startdocument(string docname)
• event boolean enddocument(string docname)
• event boolean startelement(string elementName)
• event boolean endelement(string elementName)
• end class
• class xmlparser from nonvisualobject
• function boolean parse(xmlevent handler, string
  xmlFileName)
• end class

14
Creating a PB Extension

• Implementing the native classes
• class CXmlParser public IPBX_NonVisualObject
• enum mParse 0
• Public
• PBXRESULT Invoke(pbobject obj, pbmethodId mid,
  PBCallInfo ci)
• virtual Destroy()

15
Creating a PB Extension

• Implementing the Invoke() function
• PBXRESULT CXmlParserInvoke(pbobject obj,
  pbmethodID methodId, PBCallInfo ci)
• PBXRESULT result PBX_OK
• switch(methodId)
• case mParse
• result parse(ci)
• break
• return result

16
Creating a PB Extension

• Implementing the parse() function
• void parse(PBCallInfo ci)
• IPB_Arguments args ci-gtpArgs
• pbobject handler args0-gtGetObject()
• pbstring fileName args1-gtGetString()
• long result parse(handler, fileName)
• ci-gtreturnValue-gtSetLong(result)
• return PBX_OK

17
Creating a PB Extension

• Generating .PBD file for a PB Extension

PBX2PBD Tool
PB Extension DLL
PBX_GetDescription()
Generates .PBD file
D\xmlparser\pbx2pbd pbsax.pbd pbsax.dll
18
Using a PB Extension

• Steps for using a PB Extension
• Add the generated .PBD file to the library list
  of your PowerScript target.
• Place the PB extension DLL into a directory on
  the PATH.
• In PowerScript, create an instance of a native
  class provides by the PB extension, and call its
  functions.

19
Using a PB Extension

• Using xmlparser in PowerScript
• Create a NVO, myXmlEventHandler, inheriting from
  xmlevent, then you can write
• myXmlEventHandler eventHandler
• XmlParser parser
• eventHandler create myXmlEventHandler
• parser create XmlParser
• parser.parse(eventHandler, xyz.xml)

20
Using a PB Extension

• Using xmlparser in PowerScript

parser xmlparser
Eventhandler myEventHandler
startdocument()
startelement(elementName)
For each XML element
endelement(elementName)
enddocument()
21
What happens behind the scenes

• Creating an instance of xmlparser

PBVM
XMLParser Extension
CXmlParser
PBX_CreateNonVisualObject()
new
22
What happens behind the scenes

• Calling the xmlparser.parse() function

PBVM
CXmlParser
Invoke()
TriggerEvent()
For each XML event
23
What happens behind the scenes

• Destroying the instance of xmlparser

PBVM
CXmlParser
Destroy()
delete this
24
PB extension recap

• A PB extension can expose one or more native
  classes to be used by PowerBuilder as
  NonVisualObjects.
• A PB extension can callback into PowerBuilder to
  create an object, invoke a function, trigger an
  event,

25
PB marshaler extensions

• A PB marshaler extension is a PB extension that
  acts as a bridge between PowerBuilder and
  external components, such as EJBs, Java classes,
  CORBA objects, Web services, and so on.
• A PB marshaler extension should normally have a
  companion tool for generating proxies for the
  components to be called from PowerBuilder.
• A PB marshaler extension should have at least one
  class implementing the IPBX_Marshaler interface.

26
PB marshaler extensions

• Basic architecture of PB marshaler extensions

creates
invokes
1
PBVM
Creator NativeClass
creates proxy

1
creates
1
creates
creates
invokes


1
1
1
1
PBProxy
Marshaler
Foreign Component
delegates requests
invokes
27
Calling Java classes from PB

• Description
• class JavaObjectCreator from nonvisualobject
• function long createObject(ref PowerObject
  javaObject, string className
• end class

28
Calling Java classes from PB

• Implementing the C class
• class CJavaObjectCreator public
  IPBX_NonVisualObject
• PBXRESULT Invoke(pbobject obj, pbmethodID mid,
  PBCallInfo ci)

29
Calling Java classes from PB

• Implementing the mashaler class
• Class JavaMarshaler public IPBX_Marshaler
• PBXRESULT InvokeMethod(pbobject obj, LPCTSTR
  methodDesc, PBCallInfo ci)
• The InvokeMethod() function calls Java functions
  via JNI.

30
Calling Java classes from PB

• Generating proxies for Java classes
• Java class
• public class Converter
• public double dollarToYen(double dollar)
• public double yenToEuro(double yen)

31
Calling Java classes from PB

• The proxy for Java Converter class
• PBExportHeaderConverter
• PBExportCommentsProxy for Java class.
• global type Converter from NonVisualObject
• end type
• global Converter Converter
• forward prototypes
• public
• function dollarToYen(double ad_1) alias for
  "dollarToYen,(D)D"
• function yenToEuro(double ad_1) alias for
  "yenToEuro,(D)D"

32
Calling Java classes from PB

• PowerScript calling the Java Converter class
• JavaObjectCreator l_jc
• Converter l_conv
• double l_yen
• l_jc create JavaObjectCreator
• l_jc.createObject(l_conv, com.sybase.pbni.Convert
  er)
• l_yen l_conv.dollarToYen(100.0)

33
Calling Java classes from PB

• Collaboration diagram

1.1 Invoke(midCreateObject)
PBVM
CJavaObjectCreator
1.3 NewProxyObject
1.2 Create
1.6 SetMarshaler
2.1 Invoke
1.5 Create
1.4 Create
1.7 SetMarshaler
PB Converter
CJavaMarshaler
Java Converter
2.2 InvokeMethod
2.3 Invoke
34
PB marshaler extensions recap

• Main elements
• Creator native class.
• Marshaler class implementing IPB_Marshaler
  interface.
• PB Proxies for the foreign components.

35
Embedding PowerBuilder

• Steps for calling PowerScript from C
• Load the PBVM.
• Get the pointer to the IPB_VM interface.
• Create a session based on a library list, and get
  back a pointer to the IPB_Session interface.
• Create an instance of a NVO.
• Invoke the functions of the NVO.

36
Embedding PowerBuilder

• Calling PowerScript from Java

Java Native Method
JNI
PBNI
Java
PBVM
37
The potential of PBNI

• Anything that can be called from C can also be
  called from PowerScript.
• Anything that can call C can also call
  PowerScript.

38
The future of PBNI

• Support visual native classes
• PBNI will become the corner stone of
  PowerBuilder. The final goal is to stop the need
  of migration.