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@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 • It’s 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_VM IPB_Session 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_CreateNonVisualObject(...);

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 CXmlParser::Invoke(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->pArgs; pbobject handler = args[0]->GetObject(); pbstring fileName = args[1]->GetString(); long result = parse(handler, fileName); ci->returnValue->SetLong(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 $PBExportHeader$Converter $PBExportComments$Proxy 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.Converter”) 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.