Exploiting SOAP from VO Applications- Creating a Web Service in VO Now=

Abstract

XML and Web Services are hot topics = in the application development arena. Using the Microsoft SOAP toolkit we can mak= e full use of these technologies from our own Visual Objects environment. This ar= ticle will start with some background and theory about what role SOAP and XML pl= ay and how Web services can be a valuable addition for every application developer. The article will demonstrate the contents and functionality available in the Microsoft SOAP toolkit and show how to use the toolkit fr= om VO. I will show the development of Web services written in VO and the usage from other environments like VB or HTML. Don’t underestimate this; it will enable you to use components written in VO via the Internet using onl= y the HTTP protocol! The consumers won’t even have to know about the langu= age the service is written in. We will also approach it from the other angle, = using .NET Web services written in C# or VB and consuming them from our VO applications.

The target audience is of an intermediate= level, i.e. application developers that have been working with VO for a while and= want to become more productive by making full use of what’s available as = part of the OS and MS-Office.

This paper will answer the following ques= tions:

What are Web Serv= ices?
Why should I be interested?
What technologies= are involved?
What is the SOAP toolkit?
Where and how can= I get it?
What role does XML play?
How to build SOAP servers in VO?
How to use VO SOAP Servers via HTTP?
How to build SOAP-clients in VO?
What’s requ= ired for installation and distribution?

Introduction=

Interfacing with other systems seems to be common nowadays; however historically there have always been a lot of diff= erent ways to go about doing it. It only seems to work well if both parties agre= e to sit down and talk to each other or if one of the parties documents its interface very well, and the other end adapts to that. Even more important, when it works, no one is allowed to change anything. Attempts have been ma= de, CORBA and COM seem to be reasonably well-accepted standards, but they are = very platform or vendor specific. SOAP, Simple Object Access Protocol, is one o= f the few standards that is very widely accepted and thus available everywhere a= nd for everyone. A SOAP message is just an XML document that can be transport= ed via HTTP. So it passes easily through firewalls and can transport just abo= ut anything. The current SOAP specification is version 1.1 and the World Wide= Web Consortium (W3C) is finishing up version 1.2 (http://www.w3.org/2000/xp/Group/).

Using SOAP as a way to communicate with o= thers and implementing a SOAP interface for your components so others can use it, enables enormous functionality for you. You will be able to communicate wi= th a maximum number of components on almost every platform.

There are plenty of resources, websites a= nd books about SOAP, so I won’t go into SOAP in this paper but I do encourage you to look it up and read on the subject as it will be around f= or a while and it is already playing an important role in our industry. The too= lkit itself also contains a lot of reference material about SOAP. I’m sur= e it will continue and expand seriously in the near future. Listening to MS architects and designers like Pat Helland and Don Box convinced me that SO= AP will play a very important part in products Microsoft is building right no= w, and ones we will use in the future.

Web Services=

So, what are we actually talking about wh= en we talk about Web Services? We are talking about the complete package, finding services (discovery), describing services (WSDL, schema and documentation)= , the format and encoding (SOAP/XML) and finally the transport (HTTP). Usi= ng the SOAP toolkit we are able to turn VO Classes into a Web Service and I w= ill show you how to do just that. Since we are Windows based, the first layer = we create around our class is a COM layer. This way we will also be able to address issues like load balancing, object pooling and transactions, if and when we desire. This is where products like VOCOM, VOCOM+ and the COM SDK should come in handy. For this presentation however we will use only out o= f the box VO automation.

Consuming WebServices

In a Windows environment we do have a cho= ice. We can implement SOAP-messages ourselves, or we can use the Microsoft SOAP Toolkit. We will have a short look at using raw-soap from VO, consuming a = Web Service and after that focus on using the Toolkit because it saves us a fair amoun= t of work and typing. The Microsoft SOAP Toolkit is a small, free download from= MSDN currently at version 3.0 but version 2.0 should be sufficient for most VO solutions. You can install both versions side by side and use either one. Important enhancements for 3.0 are the ability to handle file-attachments = and so-called typemappers that allow you to define your own parameter types and pass objects as parameters.

You can find the downloads at http://msdn.microsoft.com/soap along wi= th a lot of articles about the usage of SOAP and the toolkit. There’s als= o a separate download for samples available. After installation you will end u= p with some registered components, a link to the documentation and some utilities= .

Note: If you have a more or less bare = bone Windows installation and are only using VO, chances are that you have not installed the VB-runtime and you will need that to run some of the wizards. This is again available from MSDN, just do a search for VB runtime.=

You will probably encounter situations wh= ere you just have to deal with SOAP from a client’s perspective. A Web Servi= ce is available somewhere and you just want to access that from your VO applicat= ion. In our case for example we just needed to access patient information in an application in use in a hospital. In this case they ran a Web Service that returned patient details like name and location. All we had to do is call = the service, pass an account name, password and patient-id and we got the requ= ired information. By doing this using raw SOAP and XML we didn’t need to install the toolkit COM components at the clients so this made deployment easier. Actually since some of the workstations were Windows ’95 thi= s was our only option since the toolkit doesn’t install on Windows ’= 95 (which is no longer supported by Microsoft). You will need to make sure ho= wever that an appropriate XML-parser (in this case MSXML2) is installed. We haven’t actually tried it, but VO’s cHttp class should also be= an appropriate alternative.

This is how our sample looks in plain VO:=

FUNCTION Sta= rt()

LOCAL oXHttp= AS OBJECT

LOCAL strXML= AS STRING

LOCAL StrUrl= , cMsg AS STRING

LOCAL nummer= AS STRING

LOCAL userid= AS STRING

LOCAL wachtw= oord AS STRING

LOCAL nFile = AS PTR

<= /o:p>

nummer :=3D '0000004' // Assign a patient-id=

userid :=3D 'z501xxx' // Assign an account-id

wachtwoord := =3D 'z501xxx' // Assign password

<= /o:p>

// The URL f= or the webservice

StrUrl :=3D = http://patamc14.xxx.nl/SOAPServer/rpcrouter

<= /o:p>

// We do nee= d a way to make http-requests

oXhttp :=3D OLEAUTOOBJECT{"MSXML2.XMLHTTP"}

<= /o:p>

// Creating = a SOAP message

IF oXhttp:fI= nit

// We= have a valid automation object

strXM= L :=3D "<?xml version=3D'1.0'?>"

strXM= L :=3D strXML +

= "<SOAP-ENV:Envelope

= xmlns:SOAP-ENV=3D'http://schemas.xmlsoap.org/soap/envelope/'

= xmlns:xsi=3D'http://www.w3.org/1999/XMLSchema-instance’

= xmlns:xsd=3D'http://www.w3.org/1999/XMLSchema'>"=

<= /o:p>

strXM= L :=3D strXML + "<SOAP-ENV:Body>"

// zoekMetNummer is the name of the method we want to call<= /h4>

// PatientService the service or class

strXM= L :=3D strXML +

= "<ns1:zoekMetNummer xmlns:ns1=3D'urn:PatientService' SOAP-

= ENV:encodingStyle=3D'http://schemas.xmlsoap.org/soap/encoding/'>"<= o:p>

<= /o:p>

// The parameters

strXML :=3D strXML + "<nummer xsi:type=3D'xsd:string'>"= ; + nummer + "</nummer>"

strXML :=3D strXML + "<gebruiker xsi:type=3D'xsd:string'>" + userid +

"</gebruiker>"

strXML :=3D strXML + "<wachtwoord xsi:type=3D'xsd:string'>" + wachtwoord +

"</wachtwoord>"

strXML :=3D strXML + "</ns1:zoekMetNummer>"

strXM= L :=3D strXML + "</SOAP-ENV:Envelope>"

<= /o:p>

// Se= nd the request

oXhttp:Open("POST", StrUrl, FALSE)

oXhttp:setRequestHeader("Content-type", "text/xml")

oXhttp:Send(strXML)

<= /o:p>

? oXHttp:responseText

// Lo= g the response to a file

? nFi= le :=3D FCreate("c:\SoapTest\SoapXML.xml",FC_NORMAL)

? FWrite(nFile,oXHttp:responseText)

? FClose(nFile)

ELSE

?&nbs= p; 'No object...-fInit=3DFalse'

ENDIF =

You can probably imagine how a more compl= ex implementation would look like - not really a nice way of doing things if actually all you want to do is something like this in pseudo code:

oService :=3D Createobject(“PatientService”)
? oService:ZoekMetNummer(“123”,”EdR”,”PWD= 221;)

This is wh= ere the toolkit can earn its keep for the first time. This is how the code looks w= hen using the toolkit:

LOCAL soapcl= ient AS OBJECT

<= /o:p>

soapclient := =3D OleAutoObject{ "MSSOAP.SoapClient" }

IF !soapclient:fInit

? 'Th= is should not happen <g>'

ELSE <= o:p>

soapclient:mssoapinit("http://patamc14.xxx.nl/SOAPServer/rpcrouter&qu= ot;,;

= "", "", "" )

?soapclient:zoekMetNummer('000004','z501xxx','z501xxx')<= /h4>

ENDIF =

_wait()=

Looks a lot more appealing for every day = usage doesn’t it? As you can probably guess by looking at the code, the to= olkit installs and registers a SoapClient COM object. This object serves as a pr= oxy for the real object on the server-side. Do keep in mind though that this a= lways is a late bound method; you cannot generate a class that represents the pr= oxy like you do using automation. The only class you could generate is the SoapClient class, not the patientserver. The Soap client is just translati= ng to SOAP/XML and sending the messages.

3D"figu=

Fig. 1: schematic representation of Client dataflow from the SOAP toolkit helpfile

It is that easy to start consuming Web Se= rvice from VO applications.

The first parameter the call to mssoapinit requires is the name of the WSDL-file that describes the service, it’= ;s methods and parameters. Note that if there is no WSDL you need to construc= t the SOAP messages yourself and this simple way of writing client code doesn= 217;t work. In the case of a .NET Web Service, there is no separate WSDL-file bu= t the service does know how to return one when we use the following URL:

soapclient:m= ssoapinit ("http://localhost/Devcon/WS1/Service1.asmx?wsdl", "",

"", "" )

That’s basically the only change we= need to make when we want to use an out of the box .NET Web Service from VO (or other Windows clients for that matter).

The first thing we need to do is convert = our VO business logic to a COM-component. This is really simple; all we need to d= o is create a class that inherits from Autoserver (in the OLE Server library). = You can start by using the OLE InprocServer Sample on the OLE Server tab page = in the New Application Gallery.

I always select the class, right click, s= elect properties and generate a new GUID. Next, go to the app-properties and typ= e in a proper ProgId and select the Type library checkbox. See the screenshots below.

Now I always go to through the trouble of writing just one test-method and test the server. The generated code conta= ins a messagebox call that obviously makes no sense for us so we can remove that= . It also declares a protect and access/assign pair. This is also of no use sin= ce we need to make stateless components.

The next step we need to take is to creat= e a website for testing purposes. I will demonstrate this using W2K, I’m= sure it could be done using other environments but I found IIS on W2K best, and given a choice IIS 6.0 is even better. First make a new folder; for the sa= mples I’ve used c:\SOAP3DocSamples. After that, start the Internet Services Manager (Control Panel, Administrative Tools) and use it to create a new Virtual Directory with the same name pointing to the folder you’ve j= ust made. For access permission you need at least Read, Run Scripts and Execute CGI/ASP. We can now change the filepath of our DLL in VO to that same loca= tion so the DLL, regfile and typelibrary are generated there when we compile and build the DLL.

We now are ready to start using the SOAP Toolkit. To be able to use the DLL from SOAP we need to write a WSDL (Web Service Description Language) and WSML (Web Service Meta Language) file. T= he WSDL describes the classes, methods and parameters in detail in XML; the W= SML (also XML) maps the Service and methods described in the WSDL to the proper COM-object using the ProgId. One of the most useful parts of the Toolkit is that it provides a wizard that does this for us. Below are screenshots for= that process based on the previous sample. You will find a link to the WSDL-generator wizard in Programs, Microsoft SOAP Toolkit Version 3 after a default installation of the kit. After selecting Next on the welcome scree= n we are presented with a screen where the configuration file can be opened. Th= is .wgen file (also xml) is always generated by the wizard and contains all t= he input-values so by loading this we get all the input values of the previous time we ran the wizard for this DLL. This is not of much use now because w= e are running it for the first time, so just press Next for now but remember it = for later. You will appreciate it!

The next step is where we name the servic= e and load the type library.

It is all quite straight forward from her= e: after pressing Next the wizard will open and read the type library and pre= sent the classes and method we’ve written. In theory, a VO automation DLL= can only expose one Class, but we present a workaround for that in the COMSDK. Now select the methods you want to h= ave exposed in the Web Service by checking them.

In the fifth step we fill in location det= ails and choose a method to access our Service: ISAPI offers the best performan= ce and reliability, but ASP can be more flexible and offers some more debuggi= ng freedom. For now we will use the default.

The sixth step is just more tweaking and = configuring; for testing leave it default, but in real life make an effort to personali= ze the namespace to avoid any chance of name collisions. The last step is to provide the location for the generated files and the encoding to be used.<= o:p>

Here’s sample of the generated WSDL= :

<?xml version=3D'1.0' encoding=3D'UTF-8' ?>

<definiti= ons

name=3D'SOAPInproc1'

targetNamespace=3D'http://tempuri.org/SOAPInproc1/wsdl/'=

xmlns:wsdlns=3D'http://tempuri.org/SOAPInproc1/wsdl/'

xmlns:typens=3D'http://tempuri.org/SOAPInproc1/type/'

xmlns:soap=3D'http://schemas.xmlsoap.org/wsdl/soap/'

xmlns= :xsd=3D'http://www.w3.org/2001/XMLSchema'

xmlns:stk=3D'http://schemas.microsoft.com/soap-toolkit/wsdl-extension'

xmlns:dime=3D'http://schemas.xmlsoap.org/ws/2002/04/dime/wsdl/'=

xmlns:ref=3D'http://schemas.xmlsoap.org/ws/2002/04/reference/'<= /span>

xmlns= :content=3D'http://schemas.xmlsoap.org/ws/2002/04/content-type/'

xmlns:wsdl=3D'http://schemas.xmlsoap.org/wsdl/'

xmlns=3D'http://schemas.xmlsoap.org/wsdl/'>

<= /o:p>

<types>

<schema

targetNamespace=3D'http://tempuri.org/SOAPInproc1/type/'=

xmlns=3D'http://www.w3.org/2001/XMLSche= ma'

xmlns:SOAP-ENC=3D'http://schemas.xmlsoap.org/soap/encoding/'

xmlns:wsdl=3D'http://schemas.xmlsoap.org/wsdl/'

elementFormDefault=3D'qualified'><= /h4>

<= /o:p>

= <import namespace=3D'http://schemas.xmlsoap.org/soap/encoding/'/>

= <import namespace=3D'http://schemas.xmlsoap.org/wsdl/'/><= /span>

= <import namespace=3D'http://schemas.xmlsoap.org/ws/2002/04/reference/'/= >

= <import namespace=3D'http://schemas.xmlsoap.org/ws/2002/04/content-type= /'/>

<= /o:p>

= </schema>

</types>

<= /o:p>

<m= essage name=3D'SimpleAutoServer.SayHello'>

</message>

<= /o:p>

<m= essage name=3D'SimpleAutoServer.SayHelloResponse'>

= <part name=3D'Result' type=3D'xsd:anyType'/>

</message>

<= /o:p>

<p= ortType name=3D'SimpleAutoServerSoapPort'>

<= /o:p>

= <operation name=3D'SayHello' parameterOrder=3D'c'>=

= <input message=3D'wsdlns:SimpleAutoServer.SayHello'/>

= <output message=3D'wsdlns:SimpleAutoServer.SayHelloResponse'/><= /o:p>

= </operation>

<= /o:p>

</portType>

<= /o:p>

<b= inding name=3D'SimpleAutoServerSoapBinding'

= type=3D'wsdlns:SimpleAutoServerSoapPort' >

<= /o:p>

= <stk:binding preferredEncoding=3D'UTF-8'/>

= <soap:binding style=3D'rpc'

= transport=3D'http://schemas.xmlsoap.org/soap/http'/><= /h4>

<= /o:p>

= <operation name=3D'SayHello'>

= <soap:operation

= soapAction=3D'http://tempuri.org/SOAPInproc1/

= action/SimpleAutoServer.SayHello'/>

= <input>

= <soap:body

= use=3D'encoded'

= namespace=3D'http://tempuri.org/SOAPInproc1/message/'

= encodingStyle=3D'http://schemas.xmlsoap.org/soap/encoding/'/>

= </input>

= <output>

= <soap:body

= use=3D'encoded'

= namespace=3D'http://tempuri.org/SOAPInproc1/message/'

= encodingStyle=3D'http://schemas.xmlsoap.org/soap/encoding/'

= parts=3D'Result'/>

= </output>

= </operation>

<= /o:p>

</binding>

<= /o:p>

<s= ervice name=3D'SOAPInproc1' >

= <port name=3D'SimpleAutoServerSoapPort'

= binding=3D'wsdlns:SimpleAutoServerSoapBinding' >

= <soap:address

= location=3D'http://Localhost/Soap3DocSamples/SOAPInproc1.WSDL'/>

= </port>

</service>

<= /o:p>

</definit= ions>

As you can see by taking a look at the WS= DL (the SayHelloResponse part), types are important so it can pay off to actually provide some more type information. Strong typing will lead to a more spec= ific type library and generate more detailed WSDL. This will of course result in tighter code and better error handling. But for now, let’s test the generated setup by writing a client in VO again.

FUNCTION Sta= rt()
LOCAL soapclient AS OBJECT
soapclient :=3D OleAutoObject{ "MSSOAP.SoapClient30" }
soapclient:mssoapinit

= ("http://LOCALHOST/Soap3DocSamples/SOAPInprocServer1.wsdl", "", "", "" )
? "Test : ",soapclient:SayHello()
_wait()
soapclient :=3D NULL_OBJECT
RETURN NIL

When this works we can change the code fo= r the server to strong typed code:

CLASS SimpleAutoServer INHERIT AutoServer
DECLARE METHOD SayHello

METHOD SayHe= llo(c AS STRING ) AS STRING STRICT CLASS SimpleAutoServer
RETURN "HELLO from Server 1: "+c

Now we can generate the DLL again. Next w= e have to generate a new WSDL; after all that was why we made the string typed DLL i= n the first place. You will have to do this every time you change anything conce= rning the ‘interface’ of the server. This includes changing a parame= ter, adding a method, etc. It is a good thing we have the wgen-file that saves = us some typing.

Here are some of the differences in the generated wsdl:

….

<m= essage name=3D'SimpleAutoServer.SayHello'>

= <part name=3D'c' type=3D'xsd:string'/>

</message>

<= /o:p>

<m= essage name=3D'SimpleAutoServer.SayHelloResponse'>

= <part name=3D'Result' type=3D'xsd:string'/>

</message>

…=

You probably understand that you will get= a lot clearer error handling based on these definitions. You can test this by us= ing the following VO-code:

FUNCTION Sta= rt()

LOCAL soapclient AS OBJECT

LOCAL= cVar AS STRING

<= /o:p>

soapc= lient :=3D OleAutoObject{ "MSSOAP.SoapClient30" }

soapclient:mssoapinit

= ("http://LOCALHOST/Soap3DocSamples/SOAPInprocServer1.wsdl", "", "", "" )

? &qu= ot;Test : ",soapclient:SayHello() // Runtime error here!

cVar = :=3D ‘Testing’

? &qu= ot;Test : ",soapclient:SayHello(cVar)

_wait= ()

soapc= lient :=3D NULL_OBJECT

RETUR= N NIL

Ed Richard

Software Objectives

Building XML Web Services for the Microsoft .NET platform
(ISBN 0-7356-1406-7; Microsoft Press)
SOAP Toolkit 3.0 documentation

http://www.w3c.org

Exploiting SOAP from VO Applications- Creating a Web Service in VO Now=

Abstract

Introduction=

Web Services=

Consuming WebServices

FUNCTION Sta= rt()

LOCAL oXHttp= AS OBJECT

LOCAL strXML= AS STRING

LOCAL StrUrl= , cMsg AS STRING

LOCAL nummer= AS STRING

LOCAL userid= AS STRING

LOCAL wachtw= oord AS STRING

LOCAL nFile = AS PTR

<= /o:p>

nummer :=3D '0000004' // Assign a patient-id=

userid :=3D 'z501xxx' // Assign an account-id

wachtwoord := =3D 'z501xxx' // Assign password

<= /o:p>

// The URL f= or the webservice

StrUrl :=3D = http://patamc14.xxx.nl/SOAPServer/rpcrouter

<= /o:p>

// We do nee= d a way to make http-requests

oXhttp :=3D OLEAUTOOBJECT{"MSXML2.XMLHTTP"}

<= /o:p>

// Creating = a SOAP message

IF oXhttp:fI= nit

// We= have a valid automation object

strXM= L :=3D "<?xml version=3D'1.0'?>"

strXM= L :=3D strXML +

= "<SOAP-ENV:Envelope

= xmlns:SOAP-ENV=3D'http://schemas.xmlsoap.org/soap/envelope/'

= xmlns:xsi=3D'http://www.w3.org/1999/XMLSchema-instance’

= xmlns:xsd=3D'http://www.w3.org/1999/XMLSchema'>"=

<= /o:p>

strXM= L :=3D strXML + "<SOAP-ENV:Body>"

// zoekMetNummer is the name of the method we want to call<= /h4>

// PatientService the service or class

strXM= L :=3D strXML +

= "<ns1:zoekMetNummer xmlns:ns1=3D'urn:PatientService' SOAP-

= ENV:encodingStyle=3D'http://schemas.xmlsoap.org/soap/encoding/'>"<= o:p>

<= /o:p>

// The parameters

strXML :=3D strXML + "<nummer xsi:type=3D'xsd:string'>"= ; + nummer + "</nummer>"

strXML :=3D strXML + "<gebruiker xsi:type=3D'xsd:string'>" + userid +

"</gebruiker>"

strXML :=3D strXML + "<wachtwoord xsi:type=3D'xsd:string'>" + wachtwoord +

"</wachtwoord>"

strXML :=3D strXML + "</ns1:zoekMetNummer>"

strXM= L :=3D strXML + "</SOAP-ENV:Envelope>"

<= /o:p>

// Se= nd the request

oXhttp:Open("POST", StrUrl, FALSE)

oXhttp:setRequestHeader("Content-type", "text/xml")

oXhttp:Send(strXML)

<= /o:p>

? oXHttp:responseText

// Lo= g the response to a file

? nFi= le :=3D FCreate("c:\SoapTest\SoapXML.xml",FC_NORMAL)

? FWrite(nFile,oXHttp:responseText)

? FClose(nFile)

ELSE

?&nbs= p; 'No object...-fInit=3DFalse'

ENDIF =

oService :=3D Createobject(“PatientService”) ? oService:ZoekMetNummer(“123”,”EdR”,”PWD= 221;)

LOCAL soapcl= ient AS OBJECT

<= /o:p>

soapclient := =3D OleAutoObject{ "MSSOAP.SoapClient" }

IF !soapclient:fInit

? 'Th= is should not happen <g>'

ELSE <= o:p>

soapclient:mssoapinit("http://patamc14.xxx.nl/SOAPServer/rpcrouter&qu= ot;,;

= "", "", "" )

?soapclient:zoekMetNummer('000004','z501xxx','z501xxx')<= /h4>

ENDIF =

_wait()=

soapclient:m= ssoapinit ("http://localhost/Devcon/WS1/Service1.asmx?wsdl", "",

"", "" )

<?xml version=3D'1.0' encoding=3D'UTF-8' ?>

<definiti= ons

oService :=3D Createobject(“PatientService”)
? oService:ZoekMetNummer(“123”,”EdR”,”PWD= 221;)