Two things have my interest these days: the arrival of PB 10.5 and TechWave 2006! (Yes, that's right, I'm already planning ahead.) So, I thought I'd take this opportunity to roll a little application using MS MapPoint to illustrate what's new in PowerBuilder 10.5 Web services as well as help me plot my way from Chicago to Las Vegas for this year's conference! (see Figure 1).

Sybase's introduction of the .NET Web services engine allows PB programmers to access Web services that have more complex data types than their EasySoap predecessor. This means we can use a rich array of services that were previously unavailable. (Note, for backward compatibility, you can still use EasySoap if you like, but the new recommended method is the .NET engine.) This article will show you how.

To use the .NET Web services engine you'll need a few things:

• An MS MapPoint developer account - you can sign-up at https://mappoint-css.partners.extranet.microsoft.com/MwsSignup/Eval2.aspx
• .NET 2.0 Framework SDK and Redistributable downloadable here: http://msdn.microsoft.com/netframework/downloads/updates/default.aspx
• TCP Trace downloadable here: www.pocketsoap.com/tcptrace/
• PowerBuilder 10.5
• A little time to learn!

[Alternatively, you can import the PBNI extension objects from the pbwsclient105.pbx into an existing PBL. See the "Other Enhancements" article in this same issue. - Editor]

The easiest way to actually create a .NET Web services client is to use a wizard. To access it, go to File -> New -> Project and choose the Web Service Proxy Wizard. Notice, you'll need to check "Use .NET Engine" (see Figure 3).

Click on next and you'll prompted for a WDSL file name. Either select one from your local hard drive or point your browser to the URL location. In this case, we'll use the staging (developers) location for our Web services definition - http://service.mappoint.net/standard-30/mappoint.wsdl. Next, you'll be prompted for the service you wish to use. In this case, we only need access to the CommonServiceSoap, so select that and click next. The wizard will then ask you for a prefix for the proxy name. I suggest using p_. This will easily help you identify data types belonging to the proxy. Next, PowerBuilder will prompt you for the PBL where you want to store the generated project and proxy, so choose a location. Finally, click on finish and, voilá, PowerBuilder has created your Web service proxy. However, before you can use it you'll have to deploy it. To do that, choose Design -> Deploy Project and wait a few seconds while PowerBuilder compiles the types for you (see Figure 4).

With that out of the way, we can go about coding our MS MapPoint Web service functionality. As stated previously, we are simply going to get the latitude and longitude coordinates for Chicago and Las Vegas. The code is simple (see Listing 1). The primary focus will be on debugging and a new method introduced to the SoapConnection object.

The new method is called SetBasicAuthentication. What this allows us to do is provide our .NET credentials to a Web service. This is not possible in the EasySoap implementation. Again, this opens up a vast array of Web services that use this type of authentication. (On a related note, another nice thing Sybase did was add several methods for setting properties on the SoapConnection object, a change from the old tab-delimited mechanism.)

What about debugging? You may be used to using the SetOptions method and property SoapLog for your debugging pleasure. This is gone with the .NET Web services engine. We will have to rely on a third-party debugging mechanism, namely TCP Trace. [Or any TCP tracing utility, such as Trace Utility from the Microsoft SOAP Toolkit, or YATT, which is also from PocketSOAP. - Editor]

TCP Trace is a great tool for learning about IP protocols. Basically you can set it up to capture all IP traffic on a particular port. The way it works is, you direct your client to send all traffic to a port that TCP Trace is listening on. TCP Trace logs that traffic (for your viewing pleasure) and then forwards it on to the real host. It's kind of like a sniffer.

There are three steps to configuring it. First, tell TCP Trace which port to listen for messages on, then where to send them after it has logged them. The third part of the equation is to tell PowerBuilder to send SOAP messages to TCP Trace. To do that, you'll need to modify your PB105.exe.config file. It's usually located in C:\Program Files\Sybase\PowerBuilder 10.5.

You will need to add this line given that you have TCP trace set up as shown in Figure 5.

<appSettings>
<add key="EndpointURL" value ="http://localhost:25000/Find-30/FindService.asmx">
</add>
</appSettings>

[The other option is to simply specify the local endpoint as the third optional parameter on the CreateInstance call for the SoapConnection object. That overrides the endpoint from the WSDL file. - Editor]

Doing so will instruct PowerBuilder to re-direct all your outbound SOAP traffic to port 25000, which TCP Trace has been configured to listen on. Then, as stated, the messages will be logged and then forwarded to the real host, which in our case is findv3.staging.mappoint.net. Cool huh? (Many thanks to Jim O'Neil of Sybase for showing me how to use it.)

[Be careful not to include the "http://" prefix on the destination source in TCP Trace. Doing so confuses the utility and will result in the connection attempt hanging. Many thanks of my own to Jim O'Neil for helping me through that issue. - Editor]

That's it.

Interested in learning more? There are hundreds of operations you can explore with the MS MapPoint Web service but more important is the fact that Sybase has added the .NET services engine. This opens up a world of programming fun. There are many books out there that give real-world examples from Amazon to MS MapPoint to Google to you-name-it Web services that you can now incorporate into your own applications. I encourage you to start exploring.

BTW, this application does have some usefulness to it, that is, if you're into geocaching. In particular, look for a special hidden cache I'll have down at TechWave this year. You can keep tabs on it at www.geocaching.com/

Happy coding!