2. PB 9 Web Service Client

3. 66 - 2 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. n John Strano n PowerBuilder Evangelist n StranoJ@Sybase.com

4. 66 - 3 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Module Objectives n Give an overview on how Web Services client works in PowerBuilder 9.0 n Provide the information on how to generate proxies for the Web Services n Provide the information on how to use Web Services in PowerScript n Cover installation/configuration/troubleshooting information

5. 66 - 4 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Skills Prerequisites n Experience with PowerBuilder 8.0 n Basic knowledge of the standards of Web Services l WSDL(Web Service Description Language) l XML and XML schema l SOAP (Simple Object Access Protocol) n If you want to produce Web Service from PB component on EAServer, you need to get familiar to EAServer 4.2 Web Service Package, please refer to EAServer documents.

6. 66 - 5 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Definitions -- WSDL n WSDL -- Web Services Description Language l Defined the rule of describing the underneath components in XML format. l Must include: s Service name and ports(endpoints) s Binding information -- transport protocol (soap, http get, http post, or others) s PortType -- define all operations in this service s Messages -- data exchanged between client and server side such as parameters of functions, return value. s Namespaces and Schema -- refer to well known data types or define new data types such as structure, array.

7. 66 - 6 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Definitions -- XML Schema n XML Schema l The rule of defining new data types and complex types such as array, structure, enumeration, and composed data types. l There are several standard schemas, which have already defined the well known data types such as string, integer, etc. s W3C schema 1999 s W3C schema 2000/10 s W3C schema 2001 s SOAP schema

8. 66 - 7 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Definitions -- SOAP n SOAP -- Simple Object Access Protocol l A lightweight XML-based protocol l All messages exchanged between SOAP client and server are in XML format. And SOAP can use HTTP, FTP, SMTP, and other transport protocols. l It is platform and language independent l Use Envelop/Header/Body to represent the messages.

9. 66 - 8 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Definitions -- Web Service Proxy n Web Service Proxy In PowerBuilder 9 l A PB object to represent the remote Web Service l It includes: s All functions exposed by Web Services and their signature s Complex data types used by the Web Services s Namespaces and schemas used by the Web Services s Default Endpoint

10. 66 - 9 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Module Map n Introduction to PB Web Service Client l How Web Services work l PB Web Service client internals l Standards used in PB Web Service Client l Strong/Weak Points of PB Web Service Client n Create Web Services proxy in PowerBuilder 9 n Using Web Services in PowerScript n Where to get help

11. 66 - 10 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Introduction to Web Service Client n How Web Services work 5. Create WS proxy from WSDL 6. Use proxy to invoke Web Services Web service Proxy 1. Create Server Side components 2. Wrap to WS 3. Generate WSDL 4. Publish Web service Stub Invoke Data PowerScript NVO or Other components 1 2 3 WSDL Files Client Side Server Side 5 6

12. 66 - 11 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. PB Web Service Client Internals n Web Service Wizard l Collect information such as the location of WSDL, service, ports, etc. n Proxy Generator l Create WS proxy based on the information above n Universal SOAP Client l Instantiate WS proxy, communicate to WS server n Error Handling l Capture exception/error Web Service Wizard Proxy Generator Universal Soap Client Exception Processor Generator Data Store PB Proxy Info Proxy Instance WSDL file PowerScript PB 9

13. 66 - 12 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Sample -- How to invoke WS SoapConnection conn // Define SoapConnection (Universal Soap Client) demo_ieuroport proxy_obj // Define proxy long rVal real amount conn = create SoapConnection//Instantiated soap client rVal = Conn.CreateInstance(proxy_obj, " demo_ieuroport") // // Create proxy object try amount = proxy_obj.toeuro(100, “DEM”) // Invoke service // use the amount …. catch ( SoapException e ) messagebox (“Error”, “Cannot invoke WS”)// error handling end try destroy conn

14. 66 - 13 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Standards Used In PB Web Service Client n Standards supported in PB 9 l XML Schema 1.1 l WSDL 1.1 l SOAP 1.1 over HTTP n Standards not supported in PB9 l UDDI

15. 66 - 14 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Good/Weak points of PB WS Client n Strong Points l Generic s Conform to W3C standards s Can make use of any Web services no matter the services are created in PowerBuilder,.Net, Java, or other third party tools l Easy to use s There is a Wizard to help user generate proxy s Good error handling system n Weak Points l Only support SOAP messaging; don’t support HTTP Get/Post l Don’t support UDDI l Not support for all XML data types

16. 66 - 15 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Module Map n Introduction to PB Web Service Client n Create Web Services proxy in PowerBuilder 9 l Using Web Service Proxy Wizard to collect information s Using Web Service Proxy Wizard s Data types supported s Data types not supported s Schemas supported s Troubleshooting l Using Proxy Generator to create Web Service proxy n Using Web Services in PowerScript n Where to get help

17. 66 - 16 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Using Web Service Proxy Wizard n Purpose of Web Service Proxy Wizard l Collects information such as location of WSDL file, service, port(s), proxy name, and target library l Create a proxy generator object in PowerBuilder library n To Start The Wizard l Select the Web Service Proxy Wizard icon from Project page of the New dialog box n Information collected includes: l The location of the WSDL file, it could be a local file or an URL. l Service -- Only one service can be selected in this wizard. l Port(s) -- One service may be exposed to several ports. Only SOAP ports can be used in PB. l Proxy name -- Give a prefix, which will be added to the default proxy name to avoid the name conflict. Default proxy name is the port name. l Library name -- Where to deploy the proxy. l Project name -- A project to store all these information.

18. 66 - 17 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Using Web Service Proxy Wizard n Demo

19. 66 - 18 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Primitive Data Types Supported n XML Primitive Data Types Supported and PB Types Mapping XML TypePB Type boolean byte unsignedByte short unsignedShort int unsignedInt long unsignedLong integer boolean int (-128~127) uint (0~255) int uint long ulong longlong longlong (*) longlong XML TypePB Type double string date time datetime duration base64Binary hexBinary base64 double string date time datetime double blob decimal floatreal * 1~ 2 64 -1

20. 66 - 19 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. l Enumeration String Composed Data Types Supported n XML Composed Data Types Supported and Mapping XML TypePB Type Its base type1. enumeration n Examples

21. 66 - 20 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. l XML Complex Type(structure) $PBExportHeader$ s__soapstruct.srs $PBExportComments$Proxy imported from Web Service via Web Service Proxy generator. global type s__SOAPStruct from structure string varString long varInt real varFloat end type Composed Data Types Supported (con’t) n XML Composed Data Types Supported and Mapping XML TypePB Type 2. complex type (structure))structure n Examples

22. 66 - 21 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. l 1-dimension array “int []” Composed Data Types Supported (con’t) n XML Composed Data Types Supported and Mapping XML TypePB Type array3. 1-dim unbounded array n Examples

23. 66 - 22 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Data Types Not Supported n PB 9 doesn’t support: l Any other primitive data types except for those included in previous pages l Multi-dimension array

24. 66 - 23 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Schemes Supported n PB 9 supports following schemas: l W3C XML schema 1999 l W3C XML schema 2000/10 l W3C XML schema 2001 l SOAP schema n PB9 doesn’t support: l Private schemas l Messages use different schema from the complex data type definition

25. 66 - 24 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Troubleshooting & Output n Error Messages l The Wizards will give error message when fail to parse the WSDL file n Output l If everything went well, the proxy generator project will be create by Wizard

26. 66 - 25 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Module Map n Introduction to PB Web Service Client n Create Web Services proxy in PowerBuilder 9 l Using Web Service Proxy Wizard to collect information l Using Proxy Generator to create Web Service proxy s Using Proxy Generator s Change properties s Change Service/Ports s Generate proxy n Using Web Services in PowerScript n Where to get help

27. 66 - 26 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Using Proxy Generator n Purpose of Web Service Proxy Generator l Advanced user can modify any information in Generator project, which was collected by Wizard l Advanced user can create a Generator project form scratch. l Create Web Service proxy and structure if needed n Proxy Generator Mini-Toolbar Save the Project Close project Display & change service/ports 2 Change properties 1 Generate proxy 3

28. 66 - 27 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Change Properties n Change properties -- General n Deployment PBL -- Where to put your proxy in when generate n If the same proxy exists, do you want to clear the old one? n Need to be confirmed explicit?

29. 66 - 28 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Change Properties (con’t) n Change properties -- Web Service n WSDL Location -- Where is the WSDL file. Could be a local file or URL.

30. 66 - 29 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Change Service/Ports n Display & change service/ports

31. 66 - 30 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Generate Proxy n Generate proxy

32. 66 - 31 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Module Map n Introduction to PB Web Service Client n Create Web Services proxy in PowerBuilder 9 n Using Web Services in PowerScript l Universal SOAP Client in PB 9 s SoapConnection Class s SoapException Class l Using SOAP Client & WS Proxy s Sample code l Troubleshooting n Where to get help

33. 66 - 32 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Universal SOAP Client n Soap Client l Packaged into PBSoapClient90.pbd & PBSoapClient90.Dll l PBSoapClient90.Dll MUST be deployed with PB application n New Classes in PB 9 to support SOAP Messaging l SoapConnection class s Used to instantiated the proxy object and populated SOAP options l SoapException class s Used to capture runtime errors/exceptions when calling Web Services

34. 66 - 33 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. SoapConnection Class n Functions in SoapConnection class l CreateInstance --Instantiate WS proxy l SetOptions -- Set options such as log file, userID, password n CreateInstance l CreateInstance(proxyObj, ProxyType) s Create a proxy object using default endpoint l CreateInstance(proxyObj, ProxyType, endpoint) s Create a proxy object using specified endpoint n SetOptions l SetOptions(optionString) l Format of optionString is Name/value pairs. For example: s “SoapLog=~”C:\kt.log~”, userID=~”sa”, Password=~”sybase~”” s “SoapLog=‘C:\kt.log’, userID=‘sa’, Password=‘sybase’”

35. 66 - 34 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. SoapException Class n SoapException Class l SoapException inherited from PowerBuilder RuntimeError object l Errors that occur in the execution of a method of Web service are converted to SoapException objects and thrown to the calling script n In PowerScript l Use try-catch block to capture the exceptions l Unhandled exception will be propagate to PB and cause SystemError event to be executed

36. 66 - 35 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Module Map n Introduction to PB Web Service Client n Create Web Services proxy in PowerBuilder 9 n Using Web Services in PowerScript l Universal SOAP Client in PB 9 s SoapConnection Class s SoapException Class l Using SOAP Client & WS Proxy s Sample code l Troubleshooting n Where to get help

37. 66 - 36 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Using SOAP Client & WS Proxy n Procedure l Include PBSoapClient90.pbd to your PB target l Create an instance of SoapConnection l Set options for the Connection l Create an instance of WS proxy using SoapConnection l Call the function of the proxy to invoke Web Service

38. 66 - 37 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Sample SoapConnection conn // Define SoapConnection demo_ieuroport proxy_obj // Define proxy long rVal real amount conn = create SoapConnection//Instantiated soap connection conn.SetOptions(“SoapLog=‘c:\kt.log’, userID=‘sa’,Password=‘sybase’”) // Set options rVal = Conn.CreateInstance(proxy_obj, " demo_ieuroport") // // Create proxy object try amount = proxy_obj.toeuro(100, “DEM”) // Invoke service // use the amount …. catch ( SoapException e ) messagebox (“Error”, “Cannot invoke WS”)// error handling end try destroy conn

39. 66 - 38 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Module Map n Introduction to PB Web Service Client n Create Web Services proxy in PowerBuilder 9 n Using Web Services in PowerScript l Universal SOAP Client in PB 9 s SoapConnection Class s SoapException Class l Using SOAP Client & WS Proxy s Sample code l Troubleshooting n Where to get help

40. 66 - 39 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Troubleshooting n Use SetOptions to set log file, which will capture the raw SOAP data exchange between client and server

41. 66 - 40 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Module Map n Introduction to PB Web Service Client n Create Web Services proxy in PowerBuilder 9 n Using Web Services in PowerScript n Where to get help

42. 66 - 41 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Where to go for help n For Wizard, Generator, Universal Soap Client l PB 9 manual and online help l PB 9 Functional Specification n For Standards l XML Schema 1.1 s http://www.w3.org/XML/Schema l WSDL 1.1 s WSDL --- http://www.w3.org/TR/2003/WD-wsdl12-20030124/ s Binding --- http://www.w3.org/TR/2003/WD-wsdl12-bindings-20030124/ l SOAP 1.1 s http://www.w3.org/TR/2002/CR-soap12-part0-20021219/

43. 66 - 42 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. Q & A n John Strano n PowerBuilder Evangelist n StranoJ@Sybase.com