You are on page 1of 42

PB 9 Web Service Client

John Strano PowerBuilder Evangelist StranoJ@Sybase.com

66 - 2

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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

66 - 3

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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.

66 - 4

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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.

66 - 5

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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

66 - 6

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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.

66 - 7

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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

66 - 8

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Module Map

Introduction to PB Web Service Client


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

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

66 - 9

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Introduction to Web Service Client

How Web Services work


Client Side
5. Create WS proxy from WSDL 6. Use proxy to invoke Web Services
PowerScript 6 Web service Proxy Invoke Data

Server Side
1. Create Server Side components 3 2. Wrap to WS 3. Generate WSDL 4. Publish NVO or Other components

WSDL Files 5

2
Web service Stub

66 - 10

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

PB Web Service Client Internals

Web Service Wizard

PB 9 Web Service Wizard WSDL file Proxy Generator PB Proxy PowerScript Universal Soap Client Proxy Instance Exception Processor Info Generator Data Store

Collect information such as the location of WSDL, service, ports, etc. Create WS proxy based on the information above Instantiate WS proxy, communicate to WS server Capture exception/error

Proxy Generator

Universal SOAP Client

Error Handling

66 - 11

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
66 - 12

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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

66 - 13

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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; dont support HTTP Get/Post Dont support UDDI Not support for all XML data types

66 - 14

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Module Map

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

Using 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

66 - 15

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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 Select the Web Service Proxy Wizard icon from Project page of the New dialog box 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.
2003 Sybase, Inc. and its subsidiaries. All rights reserved.

To Start The Wizard

Information collected includes:


66 - 16

Using Web Service Proxy Wizard

Demo

66 - 17

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Primitive Data Types Supported

XML Primitive Data Types Supported and PB Types Mapping XML Type boolean byte unsignedByte short unsignedShort int unsignedInt long unsignedLong integer decimal float PB Type boolean int (-128~127) uint (0~255) int uint long ulong longlong longlong (*) longlong decimal real XML Type double string date time datetime duration base64Binary hexBinary base64 PB Type double string date time datetime double blob blob blob

* 1~ 264-1

66 - 18

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Composed Data Types Supported

XML Composed Data Types Supported and Mapping XML Type 1. enumeration PB Type Its base type

Examples

Enumeration

<simpleType name="CurrencySymbol"> <restriction base="string"> <enumeration value=USA" /> <enumeration value="BEF" /> <enumeration value="DEM" /> <enumeration value="ESP" /> </restriction> </simpleType>
66 - 19

String

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Composed Data Types Supported (cont)

XML Composed Data Types Supported and Mapping XML Type 2. complex type (structure)) structure PB Type

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

66 - 20

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Composed Data Types Supported (cont)

XML Composed Data Types Supported and Mapping XML Type 3. 1-dim unbounded array PB Type array

Examples

1-dimension array

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

int []

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Data Types Not Supported

PB 9 doesnt support:

Any other primitive data types except for those included in previous pages Multi-dimension array

66 - 22

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Schemes Supported

PB 9 supports following schemas:


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

PB9 doesnt support:


Private schemas Messages use different schema from the complex data type definition

66 - 23

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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

66 - 24

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Module Map

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


Using Web Service Proxy Wizard to collect information Using 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

66 - 25

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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
Close project

Proxy Generator Mini-Toolbar

3 Generate proxy Save the Project 1 Change properties 2 Display & change service/ports

66 - 26

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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?
2003 Sybase, Inc. and its subsidiaries. All rights reserved.

66 - 27

Change Properties (cont)

Change properties -- Web Service

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

66 - 28

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Change Service/Ports

Display & change service/ports

66 - 29

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Generate Proxy

Generate proxy

66 - 30

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Module Map

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

Universal SOAP Client in PB 9


SoapConnection Class SoapException Class Sample code

Using SOAP Client & WS Proxy

Troubleshooting

Where to get help

66 - 31

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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 Used to capture runtime errors/exceptions when calling Web Services

SoapException class

66 - 32

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

SoapConnection Class

Functions in SoapConnection class


CreateInstance --Instantiate WS proxy SetOptions -- Set options such as log file, userID, password CreateInstance(proxyObj, ProxyType)

CreateInstance

Create a proxy object using default endpoint Create a proxy object using specified endpoint

CreateInstance(proxyObj, ProxyType, 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

66 - 33

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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

66 - 34

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Module Map

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

Universal SOAP Client in PB 9


SoapConnection Class SoapException Class Sample code

Using SOAP Client & WS Proxy

Troubleshooting

Where to get help

66 - 35

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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

66 - 36

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
66 - 37
2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Module Map

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

Universal SOAP Client in PB 9


SoapConnection Class SoapException Class Sample code

Using SOAP Client & WS Proxy

Troubleshooting

Where to get help

66 - 38

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Troubleshooting

Use SetOptions to set log file, which will capture the raw SOAP data exchange between client and server

66 - 39

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Module Map

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

66 - 40

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

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 --- http://www.w3.org/TR/2003/WD-wsdl12-20030124/ Binding --- http://www.w3.org/TR/2003/WD-wsdl12-bindings-20030124/ http://www.w3.org/TR/2002/CR-soap12-part0-20021219/

WSDL 1.1

SOAP 1.1

66 - 41

2003 Sybase, Inc. and its subsidiaries. All rights reserved.

Q&A
John Strano PowerBuilder Evangelist StranoJ@Sybase.com

66 - 42

2003 Sybase, Inc. and its subsidiaries. All rights reserved.