SoapConnection

Description

The SoapConnection class is used to create a proxy object for a specific Web service and set options for the connection.

Methods

SoapConnection has the following methods:

AddToBypassList

SetOptions

CreateInstance

SetProxyServer

DynamicCast

SetProxyServerOptions

RemoveAuthentication

SetSoapLogFile

RemoveBypassList

SetTimeout

SetBasicAuthentication

SetUseDefaultProxySetting

SetBypassProxyOnLocal

UseConnectionCache

SetClientCertificateFile

UseIntegratedWindowsAuthentication

The GenerateProxy method is currently not implemented.




AddToBypassList

Description

Adds URIs to a list of locations that can be accessed without connecting to a proxy server. This method is available for .NET Web services only.

Syntax

conn.AddToBypassList (string value) 

Argument

Description

conn

The name of the SoapConnection object that establishes the connection

value

A regular expression that defines URIs that can be accessed without connecting to a proxy server.

Returns

Long. Valid values are 0 for success, and 50 for failure.

Usage

You can use asterisks for wild cards in expressions for domain or host names and addresses. You can add multiple URIs to the bypass list in a single call by including semicolon separators to the value string expression.

See also




CreateInstance

Description

Creates a proxy instance with a default URL for a SOAP server, which comes from a user-supplied WSDL file. The client application must create a proxy instance before it can access a Web service.

Syntax

conn.CreateInstance (ref powerobject proxy_obj, string proxy_name, {string portname}) throws SoapException

Argument

Description

conn

The name of the SoapConnection object that establishes the connection

proxy_obj

The referenced name of your proxy object

proxy_name

The name of the proxy, based on the port name from a URL in the WSDL file stored in the proxy

portname

(Optional) The port name from a URL not stored in the proxy

Returns

Long. Valid values are:

Value

Description

0

Successful

100

Invalid proxy name

101

Failed to create proxy

Examples

Example 1

In this example, the client application creates a proxy instance to access the Web services at http://my.server/soap/myport. The proxy name "syb_myport" is generated by the Web Service Proxy wizard when you select "syb_" as a prefix for a service port (endpoint) called "myport".

syb_myport myproxy
long ret

ret = Conn.CreateInstance(myproxy, "syb_myport", "http://my.server/soap/myport")

Example 2

The following script creates a connection to a Web service on a SOAP server. It sets the connection properties using an endpoint defined in the CreateInstance method. (If the endpoint is not defined in the CreateInstance method, a default URL stored in the proxy is used). The script uses the SetOptions method to specify a log file. It displays a return value in an application message box:

SoapConnection conn // Define SoapConnection
syb_currencyexchangeport proxy_obj // Declare proxy
long rVal, lLog
real amount

//Define endpoint. You can omit it, if you want to use
//the default endpoint inside proxystring str_endpoint

str_endpoint = "http://services.xmethods.net:80/soap"
conn = create SoapConnection  //Instantiated connection

lLog = conn.SetOptions("SoapLog=~"C:\mySoapLog.log~"")

// Set trace file to record soap interchange data, 
// if string is "", disables the feature

rVal = Conn.CreateInstance(proxy_obj, &
   "syb_currencyexchangeport", str_endpoint)

// Create proxy object
try

   amount = proxy_obj.getrate("us","japan") 
   // Invoke service
   messagebox("Current Exchange Rate", "One US Dollar"&
   + " is equal to " + string(amount) + " Japanese Yen")
catch ( SoapException e )
   messagebox ("Error", "Cannot invoke Web service")   
    // error handling   
end try
destroy conn

Usage

After you instantiate a proxy, you are ready to call the SOAP methods you want from the associated Web service port.

See also




DynamicCast

Description

Dynamically casts a variable from one datatype (nonvisual object or structure) to another datatype, and copies runtime data form the source datatype to the target datatype. However, you must make sure the data in source datatype can be conveted to the target datatype before you call this method.

This method is available for .NET Web services only.

Syntax

conn.DynamicCast (powerobject src, string targettype)

Argument

Description

conn

The name of the SoapConnection object that establishes the connection

src

The PowerScript datatype that you want to convert

targettype

A string specifying the datatype to which you want to convert the object

Returns

Powerobject. An object of the datatype specified by the targettype variable.

Examples

Example 1

The following code converts a returned message from the msgA datatype to the msgB datatype.

Try
 msgA = myReport.GetMessage() 
 MessageB msgB 
 msgB = lsc_connection.dynamiccast(msgA, "MessageB")

Catch (SoapException e)
...
End Try

Usage

Some Web services return runtime data of a subclass even though the definition of the Web service method uses a base class. You can call the DynamicCast method to cast the proxy object for the subclass to the proxy object for the base class.After you convert the object to the datatype you want, you can access every field in that object.




RemoveAuthentication

Description

Removes authentication for a Web service connection.

Syntax

conn.RemoveAuthentication ()

Argument

Description

conn

The name of the SoapConnection object that establishes the connection.

Returns

Long. Valid values are 0 for success, and 50 for failure.

Usage

This method clears Basic, Digest, and Integrated Windows Authentication information. You can set authentication with the UseIntegratedWindowsAuthentication (.NET Web service clients only), SetBasicAuthentication, or SetOptions methods.

See also




RemoveBypassList

Description

Removes the list of URIs to access without connecting to a proxy server. This method is available for .NET Web services only.

Syntax

conn.RemoveBypassList ()

Argument

Description

conn

The name of the SoapConnection object that establishes the connection.

Returns

Long. Valid values are 0 for success, and 50 for failure.

See also




SetBasicAuthentication

Description

Determines whether the SoapConnection object uses basic authentication for a Web service connection.

Syntax

conn.SetBasicAuthentication (string domain, string userID, string password)

Argument

Description

conn

The name of the SoapConnection object that establishes the connection.

domain

A string for the Web domain to which the user belongs. This could be a domain name, such as “sybase.com”, or a machine name.

userID

A string for an https connection.

password

A string for an https connection.

Returns

Long. Valid values are 0 for success, and 50 for failure.

Usage

You can call the SetBasicAuthentication method instead of including client identification information in the options argument of the SetOptions method.

If you are using .NET Web serveices, you can call the UseIntegratedWindowsAuthentication method for Integrated Windows Authentication.

See also




SetBypassProxyOnLocal

Description

Indicates whether to bypass the proxy server when connecting to Web services running on local servers. This method is available for .NET Web services only.

Syntax

conn.SetBypassProxyOnLocal (boolean bypass)

Argument

Description

conn

The name of the SoapConnection object that establishes the connection.

bypass

A boolean value that, when true, allows a connection to a local resource without using a proxy server. All internet requests are made through the proxy server when this value is false.

Returns

Long. Valid values are 0 for success, and 50 for failure.

Usage

Local requests use the localhost or loopback domains, or a local IP address. Addresses without a period in the URI are also identified as being local.

See also




SetClientCertificateFile

Description

Sets the certificate file or files to use to connect to a Web service. This method is available for .NET Web services only.

Syntax

conn.SetClientCertificateFile (string filename)

Argument

Description

conn

The name of the SoapConnection object that establishes the connection.

filename

A string containing the name of the certificate file or files you want to use to connect to a Web service. You must use a semicolon as a separator for multiple files. The value can include local files with a full path and URLs to remote certificate files. To discontinue use of certificates, enter an empty string (“”).

Returns

Long. Valid values are 0 for success, and 50 for failure.

Usage

You can call the SetClientCertificateFile method instead of including certificate information in the options argument of the SetOptions method.

See also




SetOptions

Description

Sets connection options for SoapConnection class.

Syntax

conn.SetOptions (string options)

Argument

Description

conn

The name of the SoapConnection object that establishes the connection.

options

Options you want to set for your connection. The string values for the option names are not case sensitive. These can be:

Returns

Long. Valid values are 0 for success, and 50 for failure. If multiple options are specified and the return value is 50, options specified before the failure are still valid.

Examples

Example 1

In this example, the application enables the logging function and attempts to connect to an endpoint for which no user ID, password, or timeout has been set.

lOpt=Conn.SetOptions("SoapLog=~"airportweather.log~"")

To avoid using escape characters before a second pair of quotation marks, use single quotation marks instead, or you can start an exterior string with single quotation marks and use double quotation marks around an interior string:

lOpt=Conn.SetOptions('SoapLog="airportweather.log"')

Usage

User ID and password values can be set in an endpoint used by the SoapConnection class or by including these values as arguments to the SetOptions method.

Priority is given to values set in an endpoint (port) that is passed as an argument to the CreateInstance method of the SoapConnection class. However, a default endpoint is used when an endpoint is not set in the CreateInstance method. In this case, priority is given to user ID and password values defined in the SetOptions method.

If the endpoint used by the SoapConnection class does not have user ID and password values, and you do not set a user ID or password with the SetOptions method, the SoapConnection class connects to a SOAP server without giving a user ID or password.

If a user ID is defined in either the endpoint or the SetOptions method but is not a password, the password value is taken to be an empty string.

When you set a timeout other than the default, an exception is thrown after the Web service connection times out. Even if you do not set a timeout value from the client, the Web server can cause the request to time out on the server side.

If you include ConnectionCache as an argument in a SetOptions call, you must not use quotation marks to enclose the value that you set for this option.

Although SetOptions takes a single string argument for all available options, you can set each of the options with more specific methods. You can use the following methods to replace SetOptions:

For .NET Web services

For EasySoap Web services

See also




SetProxyServer

Description

Sets the address, port, user name, and password for the proxy server. This method has two syntaxes.

Syntax

conn.SetProxyServer (string address, string userID, string password)
conn.SetProxyServer (string hostname, long port, string userID, string password)

Argument

Description

conn

The name of the SoapConnection object that establishes the connection

address

A string containing the host name address and port of the proxy server, and optionally, an endpoint— in the format:

http://hostname:port/path

hostname

A string containing the host name

port

A long for the proxy server port

userID

A string containing the user ID for the proxy server

password

A string containing the proxy server password

Returns

Long. Valid values are 0 for success, and 50 for failure.

Examples

Example 1

This example uses the four-argument syntax of SetProxyServer:

long ll_return
ll_return = Conn.SetProxyServer &
 (“http://myProxyServer”,8080, “My Name”, “My Pass”)

Usage

This method does the same thing as the SetProxyServerOptions method, but it has a different syntax.

Use this method or the SetProxyServerOptions method if the proxy server requires authentication. The user ID and password that you supply with the SetOptions or other authentication methods apply to the URL of the Web service, not the proxy server.

See also




SetProxyServerOptions

Description

Sets the proxy address, user name, and password for the proxy server.

Syntax

conn.SetProxyServerOptions (string optionstring)

Argument

Description

conn

The name of the SoapConnection object that establishes the connection.

optionstring

A string containing comma-separated name/value pairs. The format is:

"address='proxy_endpoint '{, userID='name ', password='password '} "

The address is required and can have a format such as:

http://hostname:port/path

Specify values for userID and password if the proxy server requires them.

Returns

Long. Valid values are 0 for success, and 50 for failure.

Examples

Example 1

This example specifies a user name and password, as well as the proxy endpoint:

long ll_return
string ls_string
ls_string = "address='http://Srvr:8080/endpnt',"
ls_string += "userID='MyName', password='mypass'"
ll_return = Conn.SetProxyServerOptions (ls_string)

Usage

Use this method or the SetProxyServer method if the proxy server requires authentication. The user ID and password that you supply with the SetOptions or other authentication methods apply to the URL of the Web service, not the proxy server.

See also




SetSoapLogFile

Description

Sets the name of a file for logging raw SOAP messages. This method is available for EasySoap Web services only.

Syntax

conn.SetSoapLogFile (string filename)

Argument

Description

conn

The name of the SoapConnection object that establishes the connection.

filename

A string containing the full file name for the SOAP log file. To disable logging, enter an empty string (“”).

Returns

Long. Valid values are 0 for success, and 50 for failure.

Usage

You can call the SetSOAPLogFile method instead of including a log file name in the options argument of the SetOptions method.

See also




SetTimeout

Description

Sets the timeout value for a SOAP connection.

Syntax

conn.SetTimeout (long seconds)

Argument

Description

conn

The name of the SoapConnection object that establishes the connection.

seconds

The timeout value in seconds. If this option is set to 0, no timeout will be set on the client side. (The Web service might still have a timeout value on the server side.)

Returns

Long. Valid values are 0 for success, and 50 for failure.

Usage

You can call the SetTimeout method instead of including a timeout value in the options argument of the SetOptions method.

See also




SetUseDefaultProxySetting

Description

Indicates whether to use Internet Explorer proxy settings for a SOAP connection. This method is available for .NET Web services only.

Syntax

conn.SetUseDefaultProxySetting (boolean useDefault)

Argument

Description

conn

The name of the SoapConnection object that establishes the connection.

useDefault

A boolean value that, when true, uses the Internet Explorer proxy settings to connect to a Web service. When this value is false (default), the proxy server settings can be assigned by the SetProxyOption, SetBypassOnLocal, AddToBypassList, and RemoveBypassList methods.

Returns

Long. Valid values are 0 for success, and 50 for failure.

Usage

If you do not set a proxy server, PowerBuilder uses the Internet Explorer proxy settings.

See also




UseConnectionCache

Description

Determines whether a connection cache is used for the Web service connection. This method is available for EasySoap Web services only.

Syntax

conn.UseConnectionCache (boolean cache)

Argument

Description

conn

The name of the SoapConnection object that establishes the connection.

cache

A boolean that determines whether the http connection of the proxy instance is kept alive after a call to the proxy. The default value is false. For Web services on EAServer, you must not change the default.

Returns

Long. Valid values are 0 for success, and 50 for failure.

Usage

You can call the UseConnectionCache method instead of setting a connection cache in the options argument of the SetOptions method.

See also




UseIntegratedWindowsAuthentication

Description

Determines whether the SoapConnection object uses Integrated Windows Authentication to connect to a Web service. This method is available for .NET Web services only.

Syntax

conn.UseIntegratedWindowsAuthentication (boolean useIWA)

Argument

Description

conn

The name of the SoapConnection object that establishes the connection.

useIWA

A boolean that determines whether to use Integrated Windows Authentication. If this option is set to “yes,” you do not need to set the UserID, Password, or Domain options.

Returns

Long. Valid values are 0 for success, and 50 for failure.

Usage

You can call the UseIntegratedWindowsAuthentication method to set connection authentication instead of the options argument of the SetOptions method.

See also