SOAP client examples

These examples use services published on the excellent www.xmethods.com website. They specify a proxy server in the optional arguments to CREATE which may not be necessary at your site and could be dropped.

Simple usage

This is a simple example that is passed two strings and returns a number.

DIM rate, opt$="PROXY=proxy:8080"
OBJECT s = CREATE "SOAP", "http://services.xmethods.net/soap/urn:xmethods-CurrencyExchange.wsdl", opt$
rate = s.getRate("England", "Japan")
OBJECT s = NULL

Using Document Style

There are two styles of SOAP envelope defined by the WSDL: RPC and Document. The former is more conventional in that the WSDL defines the arguments passed and returned in the remote procedure call whereas the latter just passes XML documents in the soap message and leaves the definition of the document to the applications. The contents of the document can be described either by encoding the tags or using a schema in the WSDL. The common message styles today are

• rpc/encoded, best for method calling, does not require WSDL, more verbose messages
• document/literal, best for message passing, requires WSDL but self validating and more compact

KCML can easily map an rpc/encoded SOAP method into a KCML method. However for document/literal services this is only possible if the service exposes simple methods. If the document style was chosen to allow generalized message passing then it may not be possible to map the document onto a KCML structure and the KCML programmer will have to parse the XML directly.

There is a common convention for document/literal, popularized by Microsoft, called wrapped document/literal where the input and output messages are defined in the WSDL schema as complex types named after the method. This has the effect of generating the same message as an rpc style request but backed up by a WSDL schema that allows the format to be validated. The outer tag of the message is the method name which makes dispatching the request on the server much simpler.

KCML SOAP supports this general document style by setting a mode for the SOAP object when it is created using the DOC or LIT options to CREATE. The programmer must create and parse the documents/arguments themselves. The code example below calls the same method as before. This time the argument is specified using XML and the result is received as a string. The programmer must know the format of the argument and the argument name. In this situation KCML is acting solely as a transport.

DOC

The user passed arguments are wrapped automatically in the method name. This should be used with wrapped document/literal styles.

s.method("<arg1>a</arg1><arg2>b</arg2>")

<soap:Envelope>
    <soap:Body>
        <method>
            <arg1>a</arg1><arg2>b</arg2>
        </method>
    </soap:Body>
</soap:Envelope>

LIT

Everything is directly passed as the SOAP body and KCML does not wrap the message with the method name. This allows the programmer to support either the original doc/lit by not passing the method name, or wrapped document literal by passing the name explicitly.

s.method("<method><arg1>a</arg1><arg2>b</arg2></method>")

<soap:Envelope>
    <soap:Body>
        <method><arg1>a</arg1><arg2>b</arg2></method>
    </soap:Body>
</soap:Envelope>

Here is another way to call the above example in the document style

DIM opt$="PROXY=proxy:8080, DOC=Y"
DIM a$400
OBJECT s = CREATE "SOAP","http://live.capescience.com/wsdl/AirportWeather.wsdl",opt$
ERROR DO
    END
END DO
a$ = s.getSummary$("<arg0>EGLL</arg0>")
OBJECT s = NULL
END

The result assigned to a$ is:

<location>London / Heathrow Airport, UnitedKingdom</location>
<wind>from the ESE(110 degrees) at 13 MPH (11 KT) (direction variable)</wind>
<sky></sky>
<temp>77 F (25 C)</temp>
<humidity>44%</humidity>
<pressure>30.03 in. Hg (1017 hPa)</pressure>
<visibility>greater than 7 mile(s)</visibility>

This would require parsing from the programmer before it could be used. NOTE: This is not strictly valid XML since there is no root node.