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:


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.


Return value

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

RemoveBypassList

SetBypassProxyOnLocal

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


Return value

Long.

Valid values are:

Value

Description

0

Successful

100

Invalid proxy name

101

Failed to create proxy


Examples

  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")
    
  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 proxy
    
    string 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

SetOptions

SetProxyServerOptions

DynamicCast (Obsolete)

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


Return value

Powerobject.

An object of the datatype specified by the targettype variable.

Examples

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.


Return value

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

SetBasicAuthentication

SetOptions

UseIntegratedWindowsAuthentication

RemoveBypassList (Obsolete)

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.


Return value

Long.

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

See also

AddToBypassList

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 "appeon.com", or a machine name.

userID

A string for an https connection.

password

A string for an https connection.


Return value

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 services, you can call the UseIntegratedWindowsAuthentication method for Integrated Windows Authentication.

See also

RemoveAuthentication

SetOptions

UseIntegratedWindowsAuthentication

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.


Return value

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

AddToBypassList

SetUseDefaultProxySetting

SetClientCertificateFile (Obsolete)

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 ("").


Return value

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

SetBasicAuthentication

SetOptions

UseIntegratedWindowsAuthentication

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:

SoapLog

(EasySoap Web service engine only) The file path for SoapLog. To disable the log, enter "".

UserID

A string value for an https connection.

Password

A string value for an https connection.

Domain

(.NET Web service engine only) A string value for the Web domain to which the user belongs. This could be a domain name, such as "appeon.com", or a machine name.

UseWindowsAuthentication

(.NET Web service engine only) A "yes" or "no" value to determine whether to use "Integrated Windows Authentication". The value you enter can be a boolean or a string. If this option is set to "yes", you do not need to set the UserID, Password, or Domain options.

AuthenticationMode

(.NET Web service engine only) A string value for the authentication mode to use. This can be "basic" or "digest". These AuthenticationMode values are described on the Microsoft MSDN Web site at http://msdn.microsoft.com/en-us/library/aa833874(VS.80).aspx.

CertificateFile

(.NET Web service engine only) A string value for the certificate file or files that you want to send from the Web service client to the server. The string value could include local files with a full path and URLs to remote certificate files. You must use a semicolon as a separator for multiple files.

Timeout

A number for the maximum wait time in seconds.

The default timeout value is 0, meaning that no limit to the connection time is set.

ConnectionCache

(EasySoap Web service engine only) 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.


Return value

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

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:


See also

CreateInstance

SetProxyServerOptions

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


Return value

Long.

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

Examples

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

SetOptions

SetProxyServerOptions

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.


Return value

Long.

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

Examples

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

CreateInstance

SetOptions

SetProxyServer

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 ("").


Return value

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

SetOptions

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.)


Return value

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

SetOptions

SetUseDefaultProxySetting (Obsolete)

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.


Return value

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

AddToBypassList

RemoveBypassList

SetOptions

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.


Return value

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

SetOptions

SetSoapLogFile

UseIntegratedWindowsAuthentication (Obsolete)

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.


Return value

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

RemoveAuthentication

SetBasicAuthentication

SetOptions