Web service proxy is obsolete
Creating Web service proxy for connecting to SOAP server will no longer be eligible for technical support. Developers who build Web service client that connects to SOAP server can choose to either continue using the feature without support, or use HTTPClient to call SOAP Web service. For more information, refer to this article: Call SOAP Web Service Using HTTPClient Object.
Web services allow you to use preexisting components (available on the Internet or on a local network) instead of writing new business logic to perform common tasks invoked by the applications that you develop. Web services originated when the Simple Object Access Protocol (SOAP) was introduced. SOAP leverages Extensible Markup Language (XML) and usually employs Hypertext Transfer Protocol (HTTP) as the transport. Invoking Web services through SOAP requires serialization and deserialization of datatypes, and the building and parsing of SOAP messages.
Part of the value of Web services comes from the Web Services Description Language (WSDL), which enables a service to be self-describing. WSDL defines an XML grammar for describing Web services as collections of communication endpoints capable of exchanging messages. WSDL service definitions provide documentation for distributed systems and serve as a recipe for automating the details involved in applications communication.
With SOAP and WSDL, using third-party components is easier because interfaces between applications become standardized across disparate platforms.
PowerBuilder supports the following Web services standards:
-
SOAP 1.1 or later
-
WSDL 1.1 or later
-
HTTP or HTTPS
-
XSD (XML Schema Document) 1.0
A PowerBuilder application can act as a client consuming a Web service that is accessed through the Internet. Using SOAP and WSDL, a collection of functions published remotely as a single entity can become part of your PowerBuilder application. A Web service accepts and responds to requests sent by applications or other Web services.
Invoking Web services through SOAP requires serialization and deserialization of data types, and the building and parsing of XML-based SOAP messages. Using objects from an extension file or dynamic library that installs with PowerBuilder, the Web services client proxy performs these tasks for you -- thereby eliminating the need to have extensive knowledge of the SOAP specification and schema, the XML Schema specification, or the WSDL specification and schema.
PowerBuilder lets you choose between the .NET Web service engine and the EasySoap Web service engine to construct SOAP requests and parse the SOAP messages returned from a Web service.
Generating a .NET assembly
The .NET Web service engine supports the latest Web service standards. To use this engine, you must have the wsdl.exe Web service tool on the development machine. This tool is required to parse WSDL files and generate C# code for a .NET assembly. The wsdl.exe file installs with the .NET SDK. It is not required on deployment machines, although deployment machines must have the .NET Framework to consume a Web service that depends on the .NET Web service engine.
If you select the .NET Web service engine in the Web Service Proxy wizard, the wizard generates a .NET assembly (DLL) in addition to a proxy object. To use the Web service at runtime, you must deploy the wizard-generated DLL along with your application.
You can also select the .NET Web service engine in the Project painter for a new Web service proxy. If you select the .NET Web service engine on the Web Service tab of the Properties dialog box for the Web Service Proxy Generator, PowerBuilder attempts to generate an assembly DLL after you click Apply or OK. You cannot use the Properties dialog box to change the Web service engine for a proxy that you already generated with the Web Service Proxy wizard.
Naming the DLL
You can name the DLL generated by the Web Service Proxy wizard or by the Project painter in the Proxy Assembly Name text box. You do not need to include the DLL extension. The name of the wizard-generated assembly is Web_service.DLL, where Web_service is the name you provide in the Proxy Assembly Name field. If you do not provide a name, the assembly takes the name of the Web service to be consumed by the DLL. The assembly is generated in the current target directory.
Deploying the DLL
You must deploy the DLL created for your Web service project to the directory where you deploy the client executable. You must also copy the Sybase.PowerBuilder.WebService.Runtime.dll and the Sybase.PowerBuilder.WebService.RuntimeRemoteLoader.dll system assemblies to this directory.
Extension objects
Although you use the same SOAP connection and exception-handling objects for the .NET Web service engine as for the EasySoap Web service engine, the objects that reference the .NET Web service engine require a different extension file or library.
The methods available on the SoapConnection object depend on which extension file or library you are using and on which Web service engine you are using. The methods for a .NET Web service engine allows you to include security information in the SOAP client header.
For more information, see Importing objects from an extension file.
Temporary directory access requirement
The .NET Web service engine requires client applications to access the system defined temporary directory on the client computer. The client must have read/write permission for the temporary directory or a "Cannot invoke the web service" error occurs. The temporary directory is set by the TEMP user environment variable.
If you decide not to use the .NET SOAP engine, PowerBuilder uses the EasySoap Web service engine. Earlier releases of PowerBuilder supported the EasySoap Web service engine only. Unlike the .NET Web service engine, the EasySoap engine does not support the XML-type array datatype or header sections in SOAP message envelopes. The EasySoap Web service engine is retained for backward compatibility and for use with targets deployed to UNIX machines.
You set the Web service engine that you want to use on the first page of the Web Service Proxy Wizard or on the Web Service tab of the Property sheet for a Web service project. The Use .NET Engine check box is selected by default for new Web service projects. You must clear the check box if you are developing a Web service application that you intend to deploy to UNIX machines.
When you add a Web service at design time and your development machine is behind a firewall, you must assign proxy server settings to connect to the Internet.
The following table displays the design-time proxy server settings that you can enter on the Firewall Settings page of the PowerBuilder System Options dialog box. To enter runtime proxy server settings, you must use the SoapConnection SetProxyServer or the SetProxyServerOptions methods.
For information about the SetProxyServer or the SetProxyServerOptions methods, see the section called “SetProxyServer” in PowerBuilder Extension Reference and the section called “SetProxyServerOptions” in PowerBuilder Extension Reference.
|
Firewall setting |
Description |
|---|---|
|
Proxy host |
Name of the proxy server that you use to access Web pages |
|
Port |
The port used for connecting to the proxy server |
|
User name |
User name for accessing the proxy server |
|
Password |
Password for the user accessing the proxy server |
PowerBuilder uses the values you enter for the proxy server settings only if you also select the Use Above Values as System Defaults check box on the Firewall Setting page. The type of engine you select for consuming a Web service can also affect the settings that PowerBuilder uses to connect to the Internet at design time.
.NET Web service engine
If the development machine is located behind a firewall but you do not select the Use Above Values as System Defaults check box, PowerBuilder attempts to connect to the Internet using settings entered in the Internet Options dialog box of the Internet Explorer browser. The selections you make on the Firewall Setting page have no effect if the development machine is not located behind a firewall.
EasySoap Web service engine
If you do not select the Use Above Values as System Defaults check box, PowerBuilder assumes that the development machine is not behind a firewall and makes no attempt to use settings from the Internet Options dialog box of the Internet Explorer browser. If you select the Use Above Values as System Defaults check box, but the development machine is not located behind a firewall, the Web service invocation can fail.
