Version 4 of Consuming web services

gkubu - 2012-06-22 19:08:46 This page contains examples of how to use the „Web services for Tcl“ [L1 ] client side package. The package was created and is maintained by Gerald Lester, who also patiently provides support for ignorant users.

The client parses so-called wsdl files [L2 ]. From this file you get all the information you need:

name of the web service
names of the operations it provides
parameters of the operations

You may also get the information from the documentation of the service, or by a tool like soapUI, or by the CreateStubs command of the package (see below).

The wsdl file contains the information in tags like

<wsdl:service name="country">
<wsdl:operation name="GetCountryByCountryCode">
<s:element name="GetCountryByCountryCode">
<s:complexType>
<s:sequence>
<s:element minOccurs="0" maxOccurs="1" name="CountryCode" type="s:string"/>
</s:sequence>
</s:complexType>
</s:element>

Even those not familiar with wsdl can certainly identify the elements in this example (from the wsdl file "http://www.webservicex.net/country.asmx?WSDL ")

the web service name is „country“
the operation name is „GetCountryByCountryCode“
the operation parameter is „CountryCode“ of type „string“ (in Tcl the type doesn't matter, of course)

Example 1: simple synchronous information retrieval

package require Tcl 8.5
package require WS::Client

::WS::Client::GetAndParseWsdl "http://www.webservicex.net/MortgageIndex.asmx?WSDL"

# DoCall: yields result as a nested dict
set monthlyIndex [ ::WS::Client::DoCall MortgageIndex GetCurrentMortgageIndexMonthly {} ]

set key [ dict keys $monthlyIndex ]
flush stdout
puts "Key: $key"

foreach { i v } [ dict get $monthlyIndex $key ] { puts "$i $v" }

should return something like

Key: GetCurrentMortgageIndexMonthlyResult
IndexDate 7/1/2004
OneYearConstantMaturityTreasury 2.1
ThreeYearConstantMaturityTreasury 3.05
FiveYearConstantMaturityTreasury 3.69
ThreeMonthTreasuryBill 1.36
SixMonthTreasuryBill 1.69
ThreeMonthSecondaryMarketCD 1.4625
SixMonthSecondaryMarketCD -
EleventhDistrictCOFI 1.4929
CostOfSavingsIndex 1.6945
OneMonthLIBOR 1.9857
ThreeMonthLIBOR 2.4632
SixMonthLIBOR 1.1617
OneYearLIBOR 1.91
CostOfDepositsIndex 1.57
TwelveMonthTreasuryAverage 1.85

Variants

DoRawCall returns the xml response of the web service

::WS::Client::DoRawCall MortgageIndex GetCurrentMortgageIndexMonthly {}
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">  <soap:Body><GetCurrentMortgageIndexMonthlyResponse xmlns="http://www.webserviceX.NET/">
<GetCurrentMortgageIndexMonthlyResult>
<IndexDate>7/1/2004</IndexDate>
<OneYearConstantMaturityTreasury>2.1</OneYearConstantMaturityTreasury>
<ThreeYearConstantMaturityTreasury>3.05</ThreeYearConstantMaturityTreasury>
<FiveYearConstantMaturityTreasury>3.69</FiveYearConstantMaturityTreasury>
<ThreeMonthTreasuryBill>1.36</ThreeMonthTreasuryBill>
<SixMonthTreasuryBill>1.69</SixMonthTreasuryBill>
<ThreeMonthSecondaryMarketCD>1.4625</ThreeMonthSecondaryMarketCD>
<SixMonthSecondaryMarketCD>-</SixMonthSecondaryMarketCD>
<EleventhDistrictCOFI>1.4929</EleventhDistrictCOFI>
<CostOfSavingsIndex>1.6945</CostOfSavingsIndex>
<OneMonthLIBOR>1.9857</OneMonthLIBOR>
<ThreeMonthLIBOR>2.4632</ThreeMonthLIBOR>
<SixMonthLIBOR>1.1617</SixMonthLIBOR>
<OneYearLIBOR>1.91</OneYearLIBOR>
<CostOfDepositsIndex>1.57</CostOfDepositsIndex>
<TwelveMonthTreasuryAverage>1.85</TwelveMonthTreasuryAverage>
</GetCurrentMortgageIndexMonthlyResult>
</GetCurrentMortgageIndexMonthlyResponse>
</soap:Body>
</soap:Envelope>

If you don't want to look up the name of the web service, you can provide your own. However, if you want to discuss the service, it might be advantageous to use its proper name.

package require WS::Client
::WS::Client::GetAndParseWsdl "http://www.webservicex.net/MortgageIndex.asmx?WSDL" {} mogaIxAlias
set monthlyIndex [ ::WS::Client::DoCall mogaIxAlias GetCurrentMortgageIndexMonthly {} ]
puts [ dict get $monthlyIndex GetCurrentMortgageIndexMonthlyResult TwelveMonthTreasuryAverage ]
1.85

As mentioned above, the CreateStubs command returns operations and parameters

package require WS::Client
::WS::Client::CreateStubs MortgageIndex

        ::MortgageIndex::GetCurrentMortgageIndexMonthly {}
        ::MortgageIndex::GetCurrentMortgageIndexByWeekly {}
        ::MortgageIndex::GetMortgageIndexByMonth {Month Year}
        ::MortgageIndex::GetMortgageIndexByWeek {Day Month Year}

The stubs are actually commands, which can be used instead of DoCall (a stub is a wrapper for DoCall), but they are missing the flexibility of the latter.

::MortgageIndex::GetMortgageIndexByMonth 5 2004