Generating Web service proxy objects

Creating a Web service proxy object

To create a new Web service proxy, select the Web Service Proxy Wizard icon from the Projects page in the New dialog box. The Web Service Proxy Wizard helps you create the proxy so you can use the Web service in PowerScript. If you select the EasySoap Web service engine, one proxy is created for each port.

In the wizard you specify:

Which Web service engine you want to use
Which WSDL file you want to access
Which service within the WSDL file you want to select
Which port or ports you want to use (EasySoap engine only)
What prefix you want to append to a port name (EasySoap) and include in the proxy name (EasySoap and .NET engines)
Which PowerBuilder library you want to deploy the proxy to

You can also select the Web Service Proxy icon from the Projects page in the New dialog box. The Web Service Proxy icon opens the Project painter for Web services so that you can create a project, specify options, and build the proxy library. The new project lists the Web service (and, for the EasySoap engine, the ports for which proxies will be generated) and specifies the name of the output library that will contain the generated proxy objects.

Whether you create the Web service project through the wizard or in the painter, the final step is to build the proxy objects by clicking the Build icon on the painter bar or selecting Design>Deploy project from the menu bar.

Circular references Generation of a Web service proxy from a WSDL file that contains a circular reference is not supported in PowerBuilder. An example of such a “circular reference” is a structure that includes itself as a child class member.

Using the UDDI browser in the wizard

PowerBuilder provides live access to Universal Description, Discovery, and Integration (UDDI) registries for both PowerScript and JSP targets. The UDDI service is an industry-wide effort to bring a common standard for business-to-business integration. It defines a set of standard interfaces for accessing a database of Web services.

The UDDI browser is incorporated in the Web Service Proxy wizard as well as in the JSP Web Service Proxy wizard. You open UDDI search pages by clicking the Search From UDDI button on the Select WSDL File page of these wizards or on the Web Service page of the properties dialog box for a Web Service Proxy Generator project. The UDDI Search page has search fields and options listed in Table 31-2.

**Table 31-2: UDDI search fields and options**
Search field or option	Description
UDDI profile	Editable drop-down list for the name of a UDDI operator. You can associate a UDDI profile with a query URL. The drop-down list allows you to select predefined profiles for the Microsoft and IBM public UDDI registries.
Query URL	Text box that displays the URL for the Web service registry in which you want to find a Web service. If you selected a predefined profile in the UDDI Profile drop-down list, the URL associated with that profile displays in the text box. You can also enter a query URL and associate the URL with a profile name by clicking the Save Profile button.
Search For	Text box for entering the key word you want to use in a UDDI search.
In	Drop-down list for “Service Names” (default) or “Business Names.”
Exact Match	Check box option. If selected, limits search to the current value in the Search For drop-down list.
Case Sensitive	Check box option. If selected, limits the search to the capitalization used by the current value in the Search For drop-down list.
Sort	Radio button option. Sorts search results in ascending or descending order.
Maximum Rows	Spin button option. Limits the number of search results returned to the number that you enter in this spin button control.

The next wizard page in the UDDI search depends on whether you are searching a key word in business names or service names:

For a business name search The Select Business wizard page returns a list of business names and descriptions that meet your search criteria. After you select a business name and click Next, a list of service names is returned on the Select Service wizard page, along with a service description and WSDL file name for each service listed.
For a service name search The Select Service wizard page returns a list of service names along with a business name, service description, and WSDL file name for each service listed.

After you select a service on the Select Service page of a wizard, the UDDI search is complete and you continue your selections on the remaining pages of the wizard.

The Web Service page of the properties dialog box for a Web Service proxy object displays the WSDL file selection that you made in the Web Service Proxy wizard. It also allows you to modify that search through a UDDI search wizard that contains the same search options and search result lists as the UDDI search pages in the Web Service Proxy wizard.

Generated proxies

The generated proxies display in the System Tree. You can expand the proxy nodes to display the signatures of the methods.

The example shows the System Tree with nodes expanded and displaying the objects imported from the extension file.

Aliases for XML methods

PowerBuilder is not case sensitive, whereas XML, SOAP, C#, and .NET are. To ensure that PowerScript code can call XML methods correctly, each method in the proxy uses an alias. The string that follows alias for contains the name and the signature of the corresponding XML or SOAP method in case-sensitive mode.

For example:

function real getquote(string ticker) alias for getQuote(xsd:string symbol)#
return xsd:float StockPrice@urn:xmethods-delayed-quotes@SoapAction

Datatype mappings for EasySoap Web service engine

The Web service proxy generator maps datatypes between XML and PowerBuilder if you use the EasySoap Web engine, and between XML, C#, .NET, and PowerBuilder if you use the .NET Web service engine. All XML data types are based on schemas from the World Wide Web Consortium Web site and.

Table 31-3 shows the datatype mappings between XML and PowerScript. If you use the .NET Web service engine, datatypes are converted to C#, then to .NET datatypes. (Table 31-4 and Table 31-5 show datatype mappings used with the .NET Web service engine.)

**Table 31-3: Datatype mappings between XML and PowerBuilder**
XML Type	PowerScript Type
boolean	boolean
byte (-128 to 127) or short	int
unsignedByte (0 to 255) or unsignedShort	uint
int	long
unsignedInt	ulong
long (-9223372036854775808 to 9223372036854775807), unsignedLong (0 to 9223372036854775807), integer (-9223372036854775808 to 9223372036854775807), nonNegativeInteger (0 to 9223372036854775807), negativeInteger (-1 to -9223372036854775808), nonPositiveInteger (0 to -9223372036854775808), or positiveInteger (1 to 9223372036854775807)	longlong
decimal (-999999999999999999 to 999999999999999999)	decimal
float	real
double	double
gYear, gYearMonth, gMonthDay, gDay, anyURI, QName, NOTATION, string, normalizedSting, token, or datatypes derived from token About normalizedString, token, and derived datatypes A normalized string does not contain carriage return, line feed, or tab characters. A token is similar to similar to a normalizedString, but does not contain leading or trailing spaces or an internal sequence of two or more spaces. Datatypes that derive from token include language, Name, NCName, NMTOKEN, NMTOKENS, ID, IDREF, IDREFS, ENTITY, ENTITIES.	string
date	date
time	time
dateTime	datetime
base64, base64Binary, or hexBinary	blob

Datatype mappings for .NET Web service engine

When you use the .NET Web Service engine, PowerBuilder converts the XML from WSDL files to C# code and compiles it in a .NET assembly. Table 31-4 displays datatype mappings for these conversions.

**Table 31-4: Datatype mappings for the .NET Web service engine**
XML type	C# type	.NET type
int	int	System.Int32
unsignedInt	uint	System.UInt32
boolean	bool	System.Boolean
unsignedByte	Byte	System.Byte
short	short	System.Int16
unsignedShort	ushort	System.UInt16
long	long	System.Int64
unsignedLong	ulong	System.UInt64
Decimal	Decimal	System.Decimal
Float	Float	System.Float
Double	Double	System.Double
Datetime, Date, and Time	System.DateTime	System.DateTime
hexBinary and hex64Binary	Byte [ ]	System.Byte [ ]
nonNegativeInteger, negativeInteger, nonPositiveInteger, positiveInteger, gYear, gMonth, gMonthDay, gDay, duration, anyURI, QName, NOTATION, normalizedString, token, language, NMTOKEN, NMTOKENS, Name, NCName,ID, IDREF, IDREFS, ENTITY, ENTITIES, and String	String	System.String
AnyType	Object	System.Object

Table 31-5 displays the datatype mapping between C# datatypes and PowerBuilder.

**Table 31-5: Datatype mappings between C# and PowerBuilder**
C# type	PowerScript type
byte	byte
sbyte	int
short	int
int	long
long	longlong
ushort	uint
uint	ulong
ulong	longlong
float	real
double	double
object	any
char	uint
string	string
decimal	decimal
bool	boolean
System.DateTime	datetime

Arrays of arrays

Unlike XML, PowerBuilder can support only unbounded one-dimensional arrays. If an array in a WSDL file is bounded and one-dimensional, PowerBuilder automatically converts it to an unbounded array. If an array in a WSDL file is multidimensional, the return type is invalid and cannot be used.

In function prototypes, PowerBuilder displays an array type as a PowerBuilder any type. You must declare an array of the appropriate type to hold the return value.