PB 9 Web Service Client 66 - 2 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. n John Strano n PowerBuilder Evangelist n [email protected]

PB 9 Web Service ClientPB 9 Web Service Client

66 - 2©2003 Sybase, Inc. and its subsidiaries. All rights reserved.

John Strano PowerBuilder Evangelist [email protected]


Module Objectives Give an overview on how Web Services client works in PowerBuilder

9.0 Provide the information on how to generate proxies for the Web

Services Provide the information on how to use Web Services in PowerScript Cover installation/configuration/troubleshooting information


Skills Prerequisites Experience with PowerBuilder 8.0 Basic knowledge of the standards of Web Services

WSDL(Web Service Description Language) XML and XML schema SOAP (Simple Object Access Protocol)

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.


Definitions -- WSDL WSDL -- Web Services Description Language

Defined the rule of describing the underneath components in XML format. Must include:

Service name and ports(endpoints) Binding information -- transport protocol (soap, http get, http post, or others) PortType -- define all operations in this service Messages -- data exchanged between client and server side such as

parameters of functions, return value. Namespaces and Schema -- refer to well known data types or define new

data types such as structure, array.


Definitions -- XML Schema XML Schema

The rule of defining new data types and complex types such as array, structure, enumeration, and composed data types.

There are several standard schemas, which have already defined the well known data types such as string, integer, etc.

W3C schema 1999 W3C schema 2000/10 W3C schema 2001 SOAP schema


Definitions -- SOAP SOAP -- Simple Object Access Protocol

A lightweight XML-based protocol All messages exchanged between SOAP client and server are in XML

format. And SOAP can use HTTP, FTP, SMTP, and other transport protocols.

It is platform and language independent Use Envelop/Header/Body to represent the messages.


Definitions -- Web Service Proxy Web Service Proxy In PowerBuilder 9

A PB object to represent the remote Web Service It includes:

All functions exposed by Web Services and their signature Complex data types used by the Web Services Namespaces and schemas used by the Web Services Default Endpoint


Module Map Introduction to PB Web Service ClientIntroduction to PB Web Service Client

How Web Services workHow Web Services work PB Web Service client internalsPB Web Service client internals Standards used in PB Web Service ClientStandards used in PB Web Service Client Strong/Weak Points of PB Web Service ClientStrong/Weak Points of PB Web Service Client

Create Web Services proxy in PowerBuilder 9 Using Web Services in PowerScript Where to get help


Introduction to Web Service Client How Web Services work

5. Create WS proxy5. Create WS proxyfrom WSDLfrom WSDL6. Use proxy to 6. Use proxy to invoke Web Servicesinvoke Web Services

Web service Proxy

1. Create Server Side components2. Wrap to WS3. Generate WSDL4. Publish

Web service Stub

Invoke

Data

PowerScript NVO or Other components

12

3WSDL

Files

Client Side Server Side

5

6


PB Web Service Client Internals Web Service Wizard

Collect information such as the location of WSDL, service, ports, etc.

Proxy Generator Create WS proxy based on the

information above Universal SOAP Client

Instantiate WS proxy, communicate to WS server

Error Handling 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


Sample -- How to invoke WS

SoapConnection conn // Define SoapConnection (Universal Soap Client)demo_ieuroport proxy_obj // Define proxylong rValreal amountconn = create SoapConnection //Instantiated soap clientrVal = Conn.CreateInstance(proxy_obj, " demo_ieuroport") // // Create proxy objecttry amount = proxy_obj.toeuro(100, “DEM”) // Invoke service // use the amount ….catch ( SoapException e ) messagebox (“Error”, “Cannot invoke WS”)// error handlingend trydestroy conn


Standards Used In PB Web Service Client Standards supported in PB 9

XML Schema 1.1 WSDL 1.1 SOAP 1.1 over HTTP

Standards not supported in PB9 UDDI


Good/Weak points of PB WS Client Strong Points

Generic Conform to W3C standards Can make use of any Web services no matter the services are created in

PowerBuilder, .Net, Java, or other third party tools Easy to use

There is a Wizard to help user generate proxy Good error handling system

Weak Points Only support SOAP messaging; don’t support HTTP Get/Post Don’t support UDDI Not support for all XML data types


Module Map Introduction to PB Web Service Client Create Web Services proxy in PowerBuilder 9Create Web Services proxy in PowerBuilder 9

Using Web Service Proxy Wizard to collect informationUsing Web Service Proxy Wizard to collect information Using Web Service Proxy Wizard Data types supported Data types not supported Schemas supported Troubleshooting

Using Proxy Generator to create Web Service proxy Using Web Services in PowerScript Where to get help


Using Web Service Proxy Wizard Purpose of Web Service Proxy Wizard

Collects information such as location of WSDL file, service, port(s), proxy name, and target library

Create a proxy generator object in PowerBuilder library To Start The Wizard

Select the Web Service Proxy Wizard icon from Project page of the New dialog box

Information collected includes: The location of the WSDL file, it could be a local file or an URL. Service -- Only one service can be selected in this wizard. Port(s) -- One service may be exposed to several ports. Only SOAP ports

can be used in PB. 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. Library name -- Where to deploy the proxy. Project name -- A project to store all these information.


Using Web Service Proxy Wizard Demo


Primitive Data Types Supported XML Primitive Data Types Supported and PB Types Mapping

XML Type PB TypebooleanbyteunsignedByteshortunsignedShortintunsignedIntlongunsignedLonginteger

booleanint (-128~127)uint (0~255)intuintlongulonglonglonglonglong (*)longlong

XML Type PB Typedoublestringdatetimedatetimedurationbase64BinaryhexBinarybase64

doublestringdatetimedatetimedoubleblobblobblob

decimaldecimalfloat real

* 1~ 264-1


Enumeration<simpleType name="CurrencySymbol"> <restriction base="string"> <enumeration value=”USA" /> <enumeration value="BEF" /> <enumeration value="DEM" /> String

<enumeration value="ESP" /> </restriction>

</simpleType>

Composed Data Types Supported XML Composed Data Types Supported and Mapping

XML Type PB TypeIts base type1. enumeration

Examples


XML Complex Type(structure)<complexType name="SOAPStruct"> <all> <element name="varString" type="string"/> <element name="varInt" type="int"/> <element name="varFloat" type="float"/> </all>

</complexType>

$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) XML Composed Data Types Supported and Mapping

XML Type PB Type2. complex type (structure)) structure

Examples


1-dimension array<complexType name="ArrayOfint">

<complexContent> <restriction base="SOAP-ENC:Array"> <sequence> <element name="item" type="int" maxOccurs="unbounded"/> </sequence> “int []” <attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="int[]"/> </restriction></complexContent>

</complexType>

Composed Data Types Supported (con’t) XML Composed Data Types Supported and Mapping

XML Type PB Typearray3. 1-dim unbounded array

Examples


Data Types Not Supported PB 9 doesn’t support:

Any other primitive data types except for those included in previous pages

Multi-dimension array


Schemes Supported PB 9 supports following schemas:

W3C XML schema 1999 W3C XML schema 2000/10 W3C XML schema 2001 SOAP schema

PB9 doesn’t support: Private schemas Messages use different schema from the complex data type definition


Troubleshooting & Output Error Messages

The Wizards will give error message when fail to parse the WSDL file

Output If everything went well, the proxy generator project will be create by Wizard


Module Map Introduction to PB Web Service Client Create Web Services proxy in PowerBuilder 9Create Web Services proxy in PowerBuilder 9

Using Web Service Proxy Wizard to collect information Using Proxy Generator to create Web Service proxyUsing Proxy Generator to create Web Service proxy

Using Proxy Generator Change properties Change Service/Ports Generate proxy

Using Web Services in PowerScript Where to get help


Using Proxy Generator Purpose of Web Service Proxy Generator

Advanced user can modify any information in Generator project, which was collected by Wizard

Advanced user can create a Generator project form scratch. Create Web Service proxy and structure if needed

Proxy Generator Mini-Toolbar

Save the Project

Close project

Display & change service/ports2

Change properties1

Generate proxy3


Change Properties Change properties -- General

Deployment PBL -- Where to put your proxy in when generate

If the same proxy exists, do you want to clear the old one?

Need to be confirmed explicit?


Change Properties (con’t) Change properties -- Web Service

WSDL Location -- Where is the WSDL file. Could be a local file or URL.


Change Service/Ports Display & change service/ports


Generate Proxy Generate proxy


Module Map Introduction to PB Web Service Client Create Web Services proxy in PowerBuilder 9 Using Web Services in PowerScriptUsing Web Services in PowerScript

Universal SOAP Client in PB 9Universal SOAP Client in PB 9 SoapConnection Class SoapException Class

Using SOAP Client & WS Proxy Sample code

Troubleshooting Where to get help


Universal SOAP Client Soap Client

Packaged into PBSoapClient90.pbd & PBSoapClient90.Dll PBSoapClient90.Dll MUST be deployed with PB application

New Classes in PB 9 to support SOAP Messaging SoapConnection class

Used to instantiated the proxy object and populated SOAP options SoapException class

Used to capture runtime errors/exceptions when calling Web Services


SoapConnection Class Functions in SoapConnection class

CreateInstance --Instantiate WS proxy SetOptions -- Set options such as log file, userID, password

CreateInstance CreateInstance(proxyObj, ProxyType)

Create a proxy object using default endpoint CreateInstance(proxyObj, ProxyType, endpoint)

Create a proxy object using specified endpoint SetOptions

SetOptions(optionString) Format of optionString is Name/value pairs. For example:

“SoapLog=~”C:\kt.log~”, userID=~”sa”, Password=~”sybase~”” “SoapLog=‘C:\kt.log’, userID=‘sa’, Password=‘sybase’”


SoapException Class SoapException Class

SoapException inherited from PowerBuilder RuntimeError object Errors that occur in the execution of a method of Web service are

converted to SoapException objects and thrown to the calling script

In PowerScript Use try-catch block to capture the exceptions Unhandled exception will be propagate to PB and cause SystemError

event to be executed



Universal SOAP Client in PB 9 SoapConnection Class SoapException Class

Using SOAP Client & WS ProxyUsing SOAP Client & WS Proxy Sample code

Troubleshooting Where to get help


Using SOAP Client & WS Proxy Procedure

Include PBSoapClient90.pbd to your PB target Create an instance of SoapConnection Set options for the Connection Create an instance of WS proxy using SoapConnection Call the function of the proxy to invoke Web Service


Sample

SoapConnection conn // Define SoapConnectiondemo_ieuroport proxy_obj // Define proxylong rValreal amountconn = create SoapConnection //Instantiated soap connection conn.SetOptions(“SoapLog=‘c:\kt.log’, userID=‘sa’,Password=‘sybase’”) // Set optionsrVal = Conn.CreateInstance(proxy_obj, " demo_ieuroport") // // Create proxy objecttry amount = proxy_obj.toeuro(100, “DEM”) // Invoke service // use the amount ….catch ( SoapException e ) messagebox (“Error”, “Cannot invoke WS”)// error handlingend trydestroy conn



Universal SOAP Client in PB 9 SoapConnection Class SoapException Class

Using SOAP Client & WS Proxy Sample code

TroubleshootingTroubleshooting Where to get help


Troubleshooting Use SetOptions to set log file, which will capture the raw SOAP data

exchange between client and server


Module Map Introduction to PB Web Service Client Create Web Services proxy in PowerBuilder 9 Using Web Services in PowerScript Where to get helpWhere to get help


Where to go for help For Wizard, Generator, Universal Soap Client

PB 9 manual and online help PB 9 Functional Specification

For Standards XML Schema 1.1

http://www.w3.org/XML/Schema WSDL 1.1

WSDL --- http://www.w3.org/TR/2003/WD-wsdl12-20030124/ Binding --- http://www.w3.org/TR/2003/WD-wsdl12-bindings-20030124/

SOAP 1.1 http://www.w3.org/TR/2002/CR-soap12-part0-20021219/


Q & A

John StranoPowerBuilder [email protected]

Documents

PB 9 Web Service Client 66 - 2 ©2003 Sybase, Inc. and its subsidiaries. All rights reserved. n John Strano n PowerBuilder Evangelist n [email protected]