White Paper Template 2005 - Support - Gupta Technologies

Team Developer & Web ServicesBy Jean-Marc Gemperle - Technical SupportWeb Services introduction and description based on the work ofSuren Behari (Team Developer Web Services Toolkit white paper)April 2006

Abstract.....................................................................4Overview ...................................................................4What is a Web Services?............................................5How are Web Services implemented? ........................5HTTP GET............................................................................. 5HTTP POST .......................................................................... 6SOAP ................................................................................... 6What is a Web Service Description Language file?.....6Anatomy of a WSDL file ....................................................... 6types ................................................................................... 6messages ............................................................................ 7portType.............................................................................. 7bindings............................................................................... 8Operation from the binding element.................................... 8Service ................................................................................ 9Provider, consumer, how they interact? ....................9Gupta HTTPREQUEST interface ................................11HTTPREQUEST Object ........................................................ 11Error Handling ................................................................... 12Synchronous access .......................................................... 13Proxy Server connection.................................................... 13Secure HTTPS using SSL and certificates ........................... 13Consuming web services via HTTPREQUESTER ........13Soap Envelope ................................................................... 14Invoking .NET Web Services .............................................. 14Invoking a JAVA Web Service ............................................ 16Invoking a Team Developer Web Service........................... 18Copyright © 2006 Gupta Technologies, LLC

Creating a Simple Web Service with .NET ................20Team Developer Web Services creation ...................25Consuming Web Services via the MS SOAP toolkit ...29Conclusion ...............................................................34Copyright © 2006 Gupta Technologies, LLC

AbstractIn this paper we will talk specifically about consumption of WebServices using the newly introduced feature in Team Developer 2005.1,the HTTPREQUEST Object found in the XML library and we will alsocover the creation and consumption of Web Services in general usingTeam Developer.OverviewAs businesses embrace the Internet as a means for communicating witheach other, the need for easy to implement, Internet-based informationexchange has grown. Over the past few years many technologies likeDCOM have been used for this, but somehow failed in gainingacceptance. Web services are the next step in the evolution of theWorld Wide Web, allowing programmable elements to be easilydeployed on any Web site so that others can access its distributedbehavior, regardless of the system and architecture used. Because theunderlining technology of Web Services is the ubiquitous HTTP protocoland XML, the accepted standard for data exchange, Web services, isbecoming the programmatic backbone for electronic commerce.Web Services with Team Developer are nothing new. SQLWindows 1.5.0was the first version to support XML in the form of a COM object fromMicrosoft MSXML. This COM Object also contains an HTTPREQUESTinterface, thus containing all the required components for Web Servicesconsumption at a low level. Since then, Team Developer 2.1 solutionswere proposed by Gupta to consume and provide Web Services, usingthe SAL Proxy Generator utility written by Suren Behari. Solutions toconsume Web Services also came from the SQLWindows community;see COM WS solution from Lubos Vnuk athttp://sqlweb.vnuk.org/index.htm##gup/index.htm##articles/comws.htmlAll those solutions are dependent on MSXM or the MS SOAP Toolkit andalso provide extra ease of use in consuming Web Services, thus at ahigher level than the use of the MSXML HTTPREQUEST object. SinceTeam Developer 2005.1 Gupta has included its own XML interface toaccess XML documents via the Document Object Model (DOM) and laterincluded an HTTPREQUEST interface.This paper also will discuss the creation of Team Developer Webservices using the MS SOAP toolkit, .NET simple Web Service creationand the consumption of those services using the HTTPREQUESTER aswell as using the MS SOAP Toolkit client, another way to consume WebServices with Team Developer.Page 4Copyright © 2006 Gupta Technologies, LLC

What is a Web Service?XML Web Services are pieces of program logic that are exposedpublicly, either on an intranet, extranet, or the Internet. They enabledisparate systems to exchange data using Internet standards such asHTTP, XML and SOAP. By implementing the use of standards, XML WebServices become accessible to any client, regardless of their system orarchitecture. This infrastructure supports the exchange of data in aformat that can be used by .NET applications and non-.NETapplications, since the data exchange is done using XML, which is textbased,and can be used (to some degree) by any system. Since XML isself-describing, the data exchanged is immediately useful and easilyinterpreted.Basically, XML Web Services are black boxes of programming logic thatabstract the functionality away from the consuming application. Theconsuming application only needs to know how to invoke the XML WebService, and what to expect in return. Beyond that, the consumingapplication is oblivious to what is happening in the XML Web Service. Asdevelopers, we can build applications that expose methods over theInternet in the form of XML Web Services.An XML Web Service can be exposed for the intended user, whetherthat is the world as a whole, a private client, or for use internally on anintranet, by either telling the client where to find the XML Web Service(the URL), or by registering the XML Web Service in the UniversalDescription, Discovery and Integration (UDDI) database. UDDI is aglobal organization trying to broaden the acceptance and use of XMLWeb Services, essentially a registry for XML Web Services.Potential clients can search the UDDI registry to find XML Web Servicesthat match their business needs.When an XML Web Service is created, a Web Service DescriptionLanguage (WSDL) document is created with it. The WSDL is essentiallya contract that a consumer agrees to, which specifies the exposedmethods of invoking the XML Web Service, the inputs expected, and theoutputs that will be returned. The URL for the WSDL is listed in theUDDI registry, so potential clients can discover it. If we are privatelyinforming a client about the XML Web Service, the URL for the WSDL isall they need to implement the XML Web Service (although a documentexplaining what the XML Web Service is for may be nice). The WSDLcontains all the information needed to invoke the XML Web Service.How are Web Services implemented?The implementation of these methods is done through cross-Internetcalls to the method using HTTP or HTTPS, and accepting the returnvalues as XML. The data exchange can occur using one of threeprotocols:Page 5HTTP GETXML Web Services are invoked using a basic GET requestCopyright © 2006 Gupta Technologies, LLC

over HTTP. Any inputs are passed in the query string. The results arereturned as an XML document.HTTP POSTXML Web Services are invoked using a basic POST request over HTTP.Any input values are passed in the HTTP POST body. The results arereturned as an XML document.SOAPXML Web Services can be invoked using a SOAP message passed overHTTP. Any inputs are passed in the SOAP message body, and the returnvalues are passed in the body of a new SOAP message.For XML Web Services that take in or return simple data types, such asstrings or integers, any input arguments can be passed to the methodas HTTP GET (query string), HTTP POST (form post) values, or in thebody of a SOAP message. For XML Web Services that either take in orreturn complex types, such as DataSets, images, or objects, methodarguments are serialized to XML and sent and received in the body of aSOAP message.What is a Web Service Description Language file?The WSDL describes the inputs, including data type and name, and theoutputs, also including data type and name, for HTTP GET, HTTP POSTand SOAP invocation. As long as the XML Web Service interfaces do notchange, the WSDL will remain the same. This means that the XML WebService provider can make changes to the logic, as long as the inputsand outputs don’t change, and the client will not be affected. Forexample, as a provider of an XML Web Service, we can change whatdatabase we are connecting to, or how the logic performs, provided theexpected inputs and outputs do not change, and the client will neverknow we made the change.Page 6Page 6Anatomy of a WSDL fileBelow are the key XML elements of a WSDL document. It is importantto understand the WSDL document completely before you can constructthe SOAP envelope you intend to send, via the GUPTAHTTPREQUESTER, to the Web Server hosting the Web Services.typesThis is a container for the definition of complex data types for messageexchange. In the sample below, there are no complex data types sothere are no data types defined in this element.Copyright © 2006 Gupta Technologies, LLC

Below is a types element with the definition of a complex type…………messagesThis element describes the contents of the messages being exchangedbetween the client and server. A message has parts that are describedby child elements. The example below defines the AddArraysoperation to have 2 inputs and 3 outputs. The input message providesthe two Arrays to add and the output message returns the result of theaddition of the 2 arrays in Result. The AddArrays also defines Array1and Array2 because the parameters of type anyType is passed byreference.portTypeThis element lists a set of operations, each assigned to a separateoperation child element. For the sample below, the operations areHelloWorld and AddArrays. Each operation child element has two childelements, input and output, describing the input and output for therelated operation. The parameterOrder attribute tells the order in whichthe parameters should be passed.Page 7Copyright © 2006 Gupta Technologies, LLC

indingsEach portType element described above identifies an operation andthere is a corresponding binding element that provides the protocoldetails for the operation. The sample below displays 2 bindings, one foreach operation HelloWorld and AddArrays.......The type attribute type='wsdlns:GuptaWSTestSoapPort' in the bindingelement gives the name of the portType for the corresponding binding.The binding element in this sample has 3 child elements:stk:binding : preferredEncoding Determines the character encodingsoap:binding : Is a child of the binding element that uses the attributesbelow to define the protocol details.style='rpc' attribute: Sets all the operations in this binding to beRemote Procedure Call type operations.transport='http://schemas.xmlsoap.org/soap/http' attribute value: Sets theSOAP messages to be sent over HTTP.Operation from the binding elementPage 8soap:operation ElementIndicates the soapAction. The soapAction HTTP header must be set inthe HTTP headers, for a client to successfully invoke the methodHelloWorld or AddarraysCopyright © 2006 Gupta Technologies, LLC

input and output ElementsBoth of these elements include a soap:body element, indicating thatthe SOAP request and response messages specifying that the operationwill contain only SOAP body (no header). If the operation request orresponse included a SOAP header, then a soap:header element wouldalso appear in the input, output elements.The use attribute specifies the encoding; when a user iscreating/serializing a SOAP message, it can use either encoded or literalformats.The encodingStyle attribute specifies the type of encoding to be usedon the various message parts.The parts attribute indicates the name of the parameter(s) or returnvalues.ServiceWhen invoking an operation, a SOAP client must identify the service,the port in that service, and the input parameter name, order and typeof the operation to be executed. For this identification, the serviceelement contains one or more port child elements. In turn each portchild element contains:The name attribute which uniquely identifies the port in the WSDLdocument.The binding attribute which refers to the binding element seen before.The soap:address element that provides the address of the serverSOAP request handler.How do provider and consumer interact?XML Web Services are based around the concept of a provider and aconsumer. The provider is the application that exposes the XML WebService and the consumer is an application that uses the XML WebService. The user of an application should never see the XML documentreturned from an XML Web Service. Rather, the application consumesthe XML Web Service, and uses the data to provide output to theapplication user.Page 6Page 9Copyright © 2006 Gupta Technologies, LLC

The figure below shows the communication between the consumer andthe provider.A consumer application connects to an XML Web Service provider. Thesteps that occur are as follows:Page 10• The consumer finds an available XML Web Service either inthe UDDI registry or directly from the provider (notshown).• The consumer makes a request to the provider for theWSDL document.• The provider returns the XML-based WSDL document.• The provider makes a request to the XML Web Service inthe WSDL document, passing in any required argumentsas defined in the WSDL.Copyright © 2006 Gupta Technologies, LLC

• The provider processes the request, performing anyfunctions necessary to complete the request, and returnsthe result to the consumer as either an XML document or aSOAP message.Gupta HTTPREQUEST interfaceWith Team Developer 2005.1, XML document handling was introducedin the form of a new Class Library XMLIB.APL, a Team DeveloperDocument Object Model (DOM) library based on the Xerces-C XMLparser http://xml.apache.org seehttp://www.guptaworldwide.com/DevCenter/WhitePapersDisplay.aspx?ProdID=2 Team Developer and XML.This now allows a Team Developer programmer to access their XMLdocument without having to use third party libraries like the COM basedlibrary from Microsoft (MSXML). Because both MSXML and the GUPTAlibraries are based on the DOM standard, they are similar in terms ofobject and member features and behavior.With version 2005.1 PTF1, a new OBJECT HTTPRequest was introducedin the XML library. While this object is part of XMLIB.APL library, thesame as the equivalent MS XMLHttpRequest object, those objects arenot limited to being used with XML; they can request or send any typeof document and also allow you to SET HTTP HEADERS.In this section we will focus on using this OBJECT to SEND a SOAPREQUEST in order to consume Web Services.HTTPREQUEST ObjectWith an HTTP request, an application can make any request to, and geta response from, a web server. This allows the SOAP envelope to besent to a server and the response to be returned. To use this feature,just include XMLLIB.APL in your Team Developer application andinstantiate a HTTPREQUEST object.Typical HTTP access/response calls to send and receive XMLBelow is the ascending order of calls a typical application would needto consume a Web Service.• Boolean open(nMethod, sURL, sUser, sPassword)Initializes the HTTPREQUEST request object and specifies themethod, URL, and authentication information for the request.nMethod: HTTP method used to open the connection, such asHTTP_GET, HTTP_POST, HTTP_PUTsURL: Requested URL. Must be an absolute URL, ie:http://localhost/TestWebServicesWithGupta/Service1.asmx?wsdlsUser, sPassword: Name of the user and password forauthentication.Example:Call oRequest.open( HTTP_GET, sEndPoint,'','' )Page 11• Boolean setHTTPHeader(sHeader, sValue)Copyright © 2006 Gupta Technologies, LLC

Specify the name of an HTTP header.sHeader: Header name to setsValue: Value of the headerExample:Set sHTTPHeader = "Content-Type: "Set sHTTPValue = "text/xml; charset=utf-8"Call oRequest.setHTTPHeader( sHTTPHeader, sHTTPValue )• Boolean sendXML(oXMLDocumentToSend)Sends an HTTP request to the server and receives a response.oXMLDocumentToSend: A XMLDocument objectExample:If NOT oRequest.sendXML( oSOAPEnvolope )Call oRequest.getLastError( nError, mlSOAPMsg )• Boolean getResponseXML(oXMLDocumentReceived)Retrieves the HTTP response into a XMLDocumentoXMLDocumentReceived: A XMLDocument objectExample:If NOT oRequest.getResponseXML( oSOAPResponse )Call oRequest.getLastError( nError, mlSOAPMsg )Sending and receiving text instead of XML• Boolean sendText(sContent)• Boolean getResponseText(sResponse)To retrieve HTTP Headers• Boolean getAllResponseHeaders(sHeadersReceived)Retrieves the values of all the HTTP headers.sHeadersReceived: The received headers values• Boolean getResponseHeader(sHeader, sValueReceived)Get the value of an HTTP header from the response body.sHeader: Header name to getsValueReceived: The received header valueError HandlingAll methods seen above return a Boolean, TRUE if the call succeeds andFALSE if the call fails. The method below allows you to retrieve the errornumber and message.• Boolean getLastError(nErrorTypeReceived, sErrorReceived)nErrorTypeReceived: Error NumbersErrorReceived: Error DescriptionNote that currently the HTTPREQUEST object does not supportasynchronous access, thus the method open() and setHTTPHeader() willalways return TRUE. Only the Send() method might return FALSE.Therefore, it makes sense to check the error using getLastError()Page 12Copyright © 2006 Gupta Technologies, LLC

Synchronous accessThe HTTPREQUEST object currently only supports synchronous access;if a request is sent to a Web Server, the HTTPREQUEST object waitsuntil a response is returned from the server, thus blocking theapplication flow. Setting a timeout allows you to decide arbitrarily whena request should time out and return control to the application.• Boolean setTimeout(nMilSeconds)nMilSeconds: The time to wait until HTTPREQUEST returns thecontrol to the applicationProxy Server connectionThe HTTPREQUEST object has no specific methods to connect via aProxy Server. The setup of the proxy server is independent to theHTTPREQUEST and has to be configured externally. Since theHTTPREQUEST object uses MS WINHTTP internally, the proxycfg.execonfiguration tool has to be used. Unfortunately this currently does notwork. A defect:#86908XMLIB HTTPREQUEST OBJECT can't be used when the connectionrequires a proxy server and when proxycfg.exe settings as been setproperlyaddresses the issue.Secure HTTPS using SSL and certificatesCurrently the HTTREQUEST has no option to connect using secureHTTPS.Consuming web services via HTTPREQUESTERTeam Developer 2005.1 PTF 1 includes a sample that consumes a WebService via the HTTPREQUEST object (see CurrencyExchange.apt). Inthis section we will see further examples that involve different WebServices; .NET, JAVA and Team Developer using the MS SOAP toolkitserver and explain the process involved to successfully invoke a WebService via the HTTPREQUESTER.Invoking a Web Service is as simple as calling the requester method inthis sequence: open(), setHTTPHeader(), sendXML(),getResponseXML(). It is simple because the only thing that matters tothe Web Service you intend to invoke is to receive a valid SOAPenvelope. If you have it, it is just a matter of sending it. The onlydifficulty lies in sending a properly serialized XML SOAP envelope to theserver along with the right SOAPAction header, so that we get aresponse back. The response will have to be parsed using the GUPTADOM XML object from the XMLIB.APL and converting it to the properdata type in the Team Developer application. This low level approach ininvoking a Web Service has the advantage of giving you full control ofPage 13Copyright © 2006 Gupta Technologies, LLC

what you send and receive. All you need to do is map the data typesreceived to the types used in your application.Soap EnvelopeIt all starts with getting a valid WSDL (Web Service DescriptionLanguage) document. As we already explained in a previous sectionthe WSDL file tells us about the location of a Web Service, theoperations (methods) that it supports and the description of theparameters and results for each operation. Think of it as a XML TypeLibrary. Because we have not covered the creation process of a WebService yet, we will use Web Services from the internet and get theirWSDL contents..NET Web Servicehttp://www.webservicex.net/uklocation.asmx?wsdlJava Web Serviceshttp://webservices.imacination.com/distance/Distance.jws?wsdlThe URLs below are .NET Web Services and Team Developer WebServices using the MS Soap Server that were built for this paper.There is no guarantee the server is online when running the sampleapplication.http://proxima.xs4all.nl:8008/TestWebServicesWithGupta/Service1.asmx?wsdlhttp://proxima.xs4all.nl:8008/GuptaWS/GuptaWebServiceTest.WSDLInvoking .NET Web ServicesIn .NET, web services have an .asmx file extension. When theASP.NET runtime receives a request for a file with an .asmxextension, the runtime dispatches the call to the web servicehandler. Using this handler, ASP.NET is able to dynamically create aHTML page describing the service's capabilities and methods. Thegenerated HTML page also provides the user with a way in which totest the web methods within the service. Another advantage ofASP.NET is in publishing Web Service Definition Language (WSDL)contracts.To test simply open the following URL in your Web Browserhttp://www.webservicex.net/uklocation.asmxYour browser should display this :GetUKLocationByCounty is the Web Services that we will be invokingusing the GUPTA HTTPREQUESTER object. Let’s look further at thisservice by clicking on GetUKLocationByCountyPage 14Copyright © 2006 Gupta Technologies, LLC

On this page you can directly invoke the Web Service, but mostimportantly this comment about SOAP : “The following is a sampleSOAP request and response. The placeholders shown need to bereplaced with actual values.” This means we have the needed sampleenvelope given by .NET, so to invoke this Web Service it is a simplematter to copy and paste the envelope in a Team Developer String,feed in the placeholders with data from a data field and invoke theHTTPREQUESTER method as explained previously. Also the envelopeclearly shows what the name of the operation is:GetUKLocationByCounty, the parameter(s): County, and result variable:GetUKLocationByCountyResultBelow is a Team Developer application that would invoke and processthe response of the Web Service seen above:HTTPRequest: oRequestXMLDocument: oSOAPEnvolopeXMLDocument: oSOAPResponseXMLNode: oNodeXMLNamedNodeMap: oNamedNodeMapString: sURLString: sHTTPHeaderString: sHTTPValueString: sSOAPEnvolopeNumber: nErrorNumber: nErrorTypePage 15Call SalWaitCursor(TRUE)Set sEndPoint="http://www.webservicex.net/uklocation.asmx?wsdl"Set sSOAPEnvolope = ''||df1||''If NOT oSOAPEnvolope.loadFromString( sSOAPEnvolope )Page 16Copyright © 2006 Gupta Technologies, LLC

If NOT oSOAPEnvolope.setOutputEncoding( UTF8 )If NOT oRequest.open( HTTP_GET, sEndPoint,'','' )Set sHTTPHeader = "Content-Type: "Set sHTTPValue = "text/xml; charset=utf-8"If NOT oRequest.setHTTPHeader( sHTTPHeader, sHTTPValue )Set sHTTPHeader = "SOAPAction"Set sHTTPValue = "http://www.webserviceX.NET/GetUKLocationByCounty"If NOT oRequest.setHTTPHeader( sHTTPHeader, sHTTPValue )If NOT oRequest.sendXML( oSOAPEnvolope )If NOT oRequest.getResponseXML( oSOAPResponse )Call oSOAPResponse.setFeature( XMLDOC_FORMAT_PRETTY_PRINT, TRUE )Set mlSOAPMsg = oSOAPResponse.writeToString()Call oSOAPResponse.getElementsByTagName( oNamedNodeMap,"GetUKLocationByCountyResult" )Call oNamedNodeMap.first( oNode )Set ml1= oNode.getTextContent( )Call oSOAPEnvolope.release( )Call oSOAPResponse.release( )Call SalWaitCursor(FALSE)This Team Developer code speaks for itself; it is not complicated. Forthe invocation to be successful you must provide the right SOAPAction:in the HTTP header; the namespace of the GetUKLocationByCounty andthe operation name. You might also consult the WSDL document of theservice.The sample above opened thehttp://www.webservicex.net/uklocation.asmx?wsdl URL. You could alsoaccess the Web Service using this URLhttp://www.webservicex.net/uklocation.asmxSo invoking .NET services using the HTTPREQUEST is simplified because.NET provides us clear information about the Web Service we want toinvoke. It is easier than constructing our SOAP envelope by analyzingthe WSDL file: Enter this in your Web Browser…http://www.webservicex.net/uklocation.asmx?wsdlIn the WSDL file you would see the operation name supported by thisservice and would have to extract the information to build the rightSOAP envelope using the description of the WSDL document weexplained earlier on.This Web Service is simple as it passes only a string and returns astring. If the Web Service passes or returns a complex data type, theasmx handler would not generate a testing page for the service.However the SOAP envelope would still be given.To see this, open http://www.webservicex.net/GenericNAICS.asmxand click GetNAICSGroupByID.Invoking a JAVA Web ServiceHere is a service in which you will have to construct the SOAP envelopefrom the WSDL file.Open http://webservices.imacination.com/distance/Distance.jws?wsdl in yourbrowser and search for all getDistance nodes in the XML file. This iswhat you should find:WSDL OperationsPage 17Copyright © 2006 Gupta Technologies, LLC

This shows us that the operation getDistance takes 2 input parameters,fromZip and toZip, defined in the message getDistanceRequest andreturns a result on getDistanceResponse defined in the messagegetDistanceResponse.This further tells us about the getDistance operation; the SOAPAction isempty “”, the input name is defined in getDistanceRequest (amessage), the namespace for this operation is“http://DefaultNamespace“ and the output name isgetDistanceResponse (in a message).WSDL MessagesThis tells us about the output parameter type and name;getDistanceReturn is of type double.This informs us about the input parameters types and names; fromZipand toZip are of type string.SOAP EnvelopeThis is our SOAP envelope from the information above, only what is inbetween the soap:Body tag is specific to the getDistance service.SetsEndPoint="http://webservices.imacination.com/distance/Distance.jws?wsdl"Set sSOAPEnvolope ='' || df1 || '' || df2 || 'SOAPActionHere we set the HTTP header of SOAPAction to be what we found in theWSDL.Set sHTTPHeader = "SOAPAction"Set sHTTPValue =""If NOT oRequest.setHTTPHeader( sHTTPHeader, sHTTPValue )Page 18Copyright © 2006 Gupta Technologies, LLC

Invocation of the getDistance operation and result extractionHere we send the request to the server and get the response in aXMLDocument object that we parse for ns1:getDistanceReturn.If NOT oRequest.sendXML( oSOAPEnvolope )If NOT oRequest.getResponseXML( oSOAPResponse )Call oSOAPResponse.setFeature( XMLDOC_FORMAT_PRETTY_PRINT, TRUE )Set mlSOAPMsg = oSOAPResponse.writeToString()If oSOAPResponse.getElementsByTagName( oNodeList,"ns1:getDistanceReturn" )If oNodeList.first( oNode )Set df3 = oNode.getTextContent( )Call oSOAPEnvolope.release( )Call oSOAPResponse.release( )Invoking a Team Developer Web Service'Using the MS SOAP toolkit, you can build Web Services out of any COMobject as long as the COM object uses the IDISPATCH interface (whichis the case in a Team Developer COM server) and as long as you useonly COM data types. Strings and numbers are allowed. The nextsection will explain the creation of such Web Services further, but forthe moment we will focus on the consumption of such Web Servicesusing the HTTPREQUEST. If you decide to consume such services,chances are you will develop the Web Service yourself. If that is thecase, you can test this Web Service using Visual Basic and use the traceutility provided in the MS SOAP toolkit, thus revealing the envelope sentto the server.Again, there is no guarantee that the web server below will be onlinewhen trying to test the sample provided. Making a Web Service from aTeam Developer COM application is simple and we will cover that lateron.Open this URL in your browser:http://proxima.xs4all.nl:8008/GuptaWS/GuptaWebServiceTest.WSDLand search for AddArrays nodeWSDL OperationsWe know the SOAPAction:http://tempuri.org/GuptaWebServiceTest/action/GuptaWSTest.AddArraysThe name space:Copyright © 2006 Gupta Technologies, LLCPage 19

http://tempuri.org/GuptaWebServiceTest/message/The method in parts: takes 2 input parameters Array1 and Array2 andreturns 3 output parameters: Result, Array1 and Array2The method AddArrays passes 2 parameters and defines an inputAddArrays and an output AddArraysResponse message.WSDL MessagesThe input types for the 2 parameters are of type anyType (VARIANT)The output types for the 3 parameters are of type anyType (VARIANT)Trying to build the SOAP envelope from the above information seemsrelatively easy as in our Java example, but because we are using arraysof specific types it is not.Set sSOAPEnvolope = '' ||df1||''||df2||''||df3||''||df4||''||df5||''||df6||'’'This demonstrates that building a SOAP envelope is obviouslyproportional to the complexity of the Web Service that you want toinvoke, in this case an array. The MS SOAP COM server makes it morePage 20Copyright © 2006 Gupta Technologies, LLC

complex because the types passed and received need to be mappedfrom XML types to COM data types.The screen shot below shows the accompanying sample demonstratingwhat we discussed in this section. The C# Web Service samples and theTeam Developer one require that you have .NET and the MS SOAPtoolkit to build the Web Services locally. Still, you can test other WebServices and also attempt to use the URL hosting my sample WebServices. The sample is located in “\SAMPLES\SAMPLE APP ConsumingWebService via Gupta HTTPRequester”.Creating a Simple Web Service with .NETThis section provides help to anyone that wants to build simple WebServices using .NET and C#, also showing .NET creating the requiredsetup (virtual directory) on the Web Server to allow access to WebServices. The examples we will build are used to demonstrate theconsumption of Web Services via the GUPTA HTTPREQUEST object, butalso using the MS SOAP client using a wrapper on the WSDLReader MSSOAP toolkit object. We will cover that later on.The creation of web services using .NET is very simple. We are using.NET2003 to demonstrate this. Before creating the Web Service, ensurethat IIS Web Server is running on your machine, and that the ComputerManagement (from the control panel) shows IIS service started.Page 21Copyright © 2006 Gupta Technologies, LLC

Execute Microsoft Visual Studio .NET 2003 and create a new project asshown below. Adjust the URL of your Web Server to your environmentWe will be creating a new method so simply click on switch to codeview.Page 6Remove the sample comments….Page 22Copyright © 2006 Gupta Technologies, LLC

And paste this in its place:public struct ReturnInformation {public string ReturnMessage;public double pi;};public struct PComplex {public string ReturnMessage;public double pi;};[WebMethod]public string HelloWorld(string MyMessage){return MyMessage + "Hello World";}[WebMethod]public ReturnInformation TestReturnComplex(stringMessageToPass){ReturnInformation R;R.ReturnMessage=MessageToPass + "C# WebService say:PI is in ReturnCode Element, it is in the next nodelistitem... ";R.pi= 3.14159265;return R;}[WebMethod]public ReturnInformation TestPassComplex(PComplexPassComplex){ReturnInformation R;R.ReturnMessage=PassComplex.ReturnMessage;R.pi=PassComplex.pi;return R;}The code above creates 3 methods: HelloWorld, which passes andreturns a string, TestReturnComplex that passes a string and returns astructure and finally TestPassComplex that passes and returns astructure.Build the solutionCopyright © 2006 Gupta Technologies, LLC

Building the solution should succeed as shown below. If that is thecase, open Computer management from the control panel and youshould see a new virtual directory, TestWebServicesWithGupta, created.Page 23Copyright © 2006 Gupta Technologies, LLC

To test your new Web Service, click View In Browser in the solutionexplorer on the Service1.asmx file.As shown previously you can test your Web Service directly and .NETwill also display the SOAP envelope.Page 24Copyright © 2006 Gupta Technologies, LLC

To see the WSDL file, just append ?wsdl in your URLhttp://localhost/TestWebServicesWithGupta/Service1.asmx?wsdlTeam Developer Web Services creationTo build a Web Service from a Team Developer COM Server application,you will need to download and install the MS SOAP Toolkit version 3from this URL :http://www.microsoft.com/downloads/details.aspx?familyid=c943c0dd-ceec-4088-9753-86f052ec8450&displaylang=enThe MS SOAP Toolkit exposes COM server applications to clients usingthe SOAP protocol, basically making the COM server a Web Service.There are certain limitations to be aware of. Here are some guidelines:• The COM objects must implement the IDispatch interface,which is the case with a Team Developer COM application.• The methods exposed can only use Automation compatibledatatypes; use VARIANT as much as possible for yourparameters. Strings are allowed as they are converted toBSTR. Numbers are also allowed, but remember that TeamDeveloper defines them as doubles per default (VT_R8).• In and out (receive) parameters must be VARIANTS.The screen shot below shows a Team Developer COM application with aCoClass named GuptaWSTest and an interface IGuptaWSTest whichdefines 2 methods HelloWorld() and AddArrays(). The methods useSAFEARRAYS. Notice the use of the SAL Trace function and especiallythe use of SalComCleanupMode() on SAM_AppStartup.Page 25Copyright © 2006 Gupta Technologies, LLC

The use of SalComCleanupMode() is important because with this featureyou tell the GUPTA Runtime not to enter its cleanup, SAM_AppExit,each and every time a Service is executed. It can be a MTS service or,as in this case, a Web Service.Below SalComCleanupMode(FALSE) was set (its default) and theinvocation of the a Web Service Operation made the runtime exit eachand every time the operation was called. SettingSalComCleanupMode(TRUE) would never execute SAM_AppExit. Itwould only execute when the actual Web Server is shutdown.Page 6Page 26Copyright © 2006 Gupta Technologies, LLC

Once the MS SOAP Toolkit is installed and you are done with a workingTeam Developer COM server application, you are ready to make it aWeb Service. The directory \TD WEB SERVICES\Web ServicesSERVER\Gupta TD WebService MS SAOP SERVER\ contains the exampleGuptaWebServiceTest.apt used in this paper. Load it in Team Developerand make it a COM DLL. Double check that the DLL is registered oncethe application is built. Create a Virtual directory on your Web Serverpointing to where the COM DLL is located (I simply created a directoryunder \Inetpub\wwwroot\GuptaWS).Execute WSDL Generator from the MS SOAP toolkit and click next to thefirst page of the wizard. This should show you the screen below. Give aname to the service, GuptaWebServiceTest in this case, and give thepath to the DLL of your COM server DLL built in the previous steps.Click next and select the method you would like to expose as a WebService.Page 27Copyright © 2006 Gupta Technologies, LLC

Click next and enter the listener URL (basically the virtual directory youhave created previously) and use the ISAPI listener. In my case I usehttp://localhost:8008/GuptaWS/. Use the port your Web Server isconfigured on; if it’s the default port 80 then enterhttp://localhost/GuptaWS/Click next and change the URIs to your server domain name. In oursample we leave it at its default tempuri.org.Click next and give the path where the WSDL and WSML file should bestored. As mentioned in the wizard, the files need to be Web accessible,so just enter the path of your virtual directory as shown below.Page 28Copyright © 2006 Gupta Technologies, LLC

The virtual directory and its path where the WSDL and WSML file shouldbe located.Page 29IMPORTANT: Lastly, set up the Internet Server API (ISAPI) handler forthat virtual directory by calling this MS SOAP cmd file:\Program Files\MSSOAP\Binaries soapvdir.cmd UPDATE GuptaWSThis is it! You have now created a Team Developer Web Service. If youused the accompanying sample of a Team Developer COM server(GuptaWebServiceTest.apt), you can now test the Web Service with theapplication “TD HTTPREQUEST WEB SERVICES CONSUMPTION.apt”found in the “\SAMPLES\SAMPLE APP Consuming WebService via GuptaHTTPRequester” directory.Consuming Web Services via the MS SOAP toolkitThe MS SOAP toolkit has a server component, as we have seen in aprevious section, but it also has client components that consume WebServices. So using the MS SOAP toolkit makes it possible to consumeWeb Services.A solution to consume Web Services for Team Developer using the MSSOAP toolkit was already proposed by Suren Behari with the ProxyCopyright © 2006 Gupta Technologies, LLC

Generator. Here again is another COM Proxy class generator. It uses aC++ DLL that returns analyzed information from a WSDL file. Theinformation (order, in/out flag, types and method names) are retunedto a Team Developer application that generates, via the CDK, the COMProxy class to the service(s) of the selected WSDL document. All thesource files are included. I have tested a few Web Services with goodsuccess like the US NAICS structure Web Service (see example). But, incase of a problem, the source is included as I did the mapping of thedata types the best I could, but I could not test it all.The generator converts the Web Service type to VARIANT in case ofDATE and COMPLEX type and maps NUMBER to their proper VT TYPES,feeding it to the SOAP toolkit client that invokes the service. Complexdata types are defined as VARIANT since they might containSAFEARRAY or valid XMLDomNodeList IDISPATCH objects, thus it ispossible to invoke Web Services having complex data types.WSAnalyserToolWSAnalyserTool is a Team Developer CDK application to be installed as atool in the Team Developer IDE. It can also function as a normalapplication. With it you can generate a COM Proxy Class for a givenWSDL document.How does it work?It functions pretty much the same way as the ActiveX explorer; the onlydifference is that all methods are generated (you can’t select whichones you do not want to generate). Also the generator can use eitherMSOFFICE SOAP or the MS SOAP toolkit. The advantage of usingMSOFFICE SOAP toolkit is that you do not have to deploy the MS SOAPcomponents if the deployed machine already contains MSOFFICE 2003.Still, for the generator to function, the MS SOAP toolkit must beinstalled.If the generator finds an existing method name in the COM Proxy Classname, it will give a warning and ignore the method. Each generatedCOM Proxy Class in an outline has an Init() method that actuallyconnects to the Web Service to be invoked. In the Init() method youcan also pass a username and password if the service requires a basicauthentication. If multiple Services are generated in a given COM ProxyClass, the tool verifies that the endpoint and the address of the serviceis identical to the one already existing in the Init() method.The figure below shows the tool installed in Team Developer havinggenerated some COM Proxy class from some WSDL documentsPage 30Copyright © 2006 Gupta Technologies, LLC

How to use it?Unzip the sample and Install soapsdk.exe fromhttp://www.microsoft.com/downloads/details.aspx?familyid=c943c0dd-ceec-4088-9753-86f052ec8450&displaylang=enThe SOAP SDK is only required for the generator. If using a MS OFFICESOAP TOOLKIT generated COM Proxy class, the deployed machinehaving MS OFFICE installed does not need the MS SOAP toolkit.The sample directory “\SAMPLES\WSDLAnalyser” contains:\src: the C++ source of a DLL that interfaces to TD.WSAnalyserTool.apt : The Team Developer 2005.1 application; thisshould work fine with older versions of Team Developer.Microsoft Office Soap Type Library v3.0.apl : a minimal ActiveXinterface for MS office SOAP.Microsoft Soap Type Library v3.0.apl : Same as above using the MSSOAP toolkit.msxml.apl : MS XML ActiveX interface used by the examples but notused by the generator.TD WS CONSUMPTION with proxygen interface.apt : The same samplesthat we covered in Consuming web services via HTTPREQUESTERsection.WSDLAnalyser.dll : An MS SOAP toolkit WSDLREADER interface toGUPTA Team Developer.Once you build the WSAnalyserTool.apt, ensure you can successfullygenerate a COM proxy using one of the WSDL sources given in theendpoint combo. Try:http://webservices.imacination.com/distance/Distance.jws?wsdlUncheck “in the current outline” check box and click generate. Checkthat the APL interface has been created.Page 31Copyright © 2006 Gupta Technologies, LLC

Test TD WS CONSUMPTION with proxygen interface.apt.The sample below uses the same web services as the HTTPREQUESTERsample and the proxy is in the GuptaProxyTest.apl. To test theaccompanying C# and Team Developer Web Services you will have tobuild the Web Services samples or you can try to use the remote URLindicated in the sample.Below is an example of a generated COM Proxy class for the US NAICS service:Function: GetNAICSByIDDescription:ReturnsBoolean:ParametersLong String: NAICSCodeReceive Boolean: GetNAICSByIDResultFunctionalVar: NAICSDataClass: VariantStatic VariablesLocal variablesBoolean: tmpretActionsCall __ObjectPushString(NAICSCode)Call __ObjectPushVariantByRef(NAICSData)Set tmpret = __ObjectInvoke("GetNAICSByID", INVOKE_FUNCTION)Call __ObjectPopNumber(-1,GetNAICSByIDResult)Call __ObjectPopVariant(1,NAICSData)Call __ObjectFlushArgs()Return tmpretAnd its invocation:Call oGenericNAICS.Create( )Call oGenericNAICS.Init( '', '', '' )Set bGetNAICSByIDResult=FALSECall oGenericNAICS.GetNAICSByID( dfCode, bGetNAICSByIDResult, vNAICSData )If vNAICSData.GetObject( oDOMNodeList )If oDOMNodeList.IsDispatchValid( )Call oDOMNodeList.PropGetitem( 0,oDOMNode )Call oDOMNode.PropGetparentNode( oDOMNode )Call oDOMNode.PropGetxml( ml1 )Page 32Copyright © 2006 Gupta Technologies, LLC

Below is an example of a generated COM Proxy class for a local Team Developerservice using arrays:COM Proxy Class: GuptaWebServiceTestFunction: AddArraysDescription:ReturnsBoolean:ParametersFunctionalVar: Array1Class: VariantFunctionalVar: Array2Class: VariantFunctionalVar: ResultClass: VariantStatic VariablesLocal variablesBoolean: tmpretActionsCall __ObjectPushVariantByRef(Array1)Call __ObjectPushVariantByRef(Array2)Set tmpret = __ObjectInvoke("AddArrays", INVOKE_FUNCTION)Call __ObjectPopVariant(0,Array1)Call __ObjectPopVariant(1,Array2)Call __ObjectPopVariant(-1,Result)Call __ObjectFlushArgs()Return tmpretBelow is the initialization of the COM Proxy class and the invocation of theAddArray method.Call oGuptaWebServiceTest.Create( )Call oGuptaWebServiceTest.Init('','','' )Call oGuptaWebServiceTest.AddArrays( vA, vB, vResult )Call vResult.GetSafeArray( sfR )! ! Extract the returned array and display results....Call sfR.GetNumber( df7, 0 )Call sfR.GetNumber( df8, 1 )Call sfR.GetNumber( df9, 2 )Call SalWaitCursor(FALSE)To install WSAnalyserTool as a Team Developer tool, copy WSAnalyserTool.exe,WSDLAnalyser.dll, Microsoft Office Soap Type Library v3.0.apl, Microsoft SoapType Library v3.0.apl to your Gupta Team Developer root directory. Install it as auser tool in Team Developer as shown below. The -MTX parameter is required forTeam Developer 3.10 and above.Page 33Copyright © 2006 Gupta Technologies, LLC

ConclusionConsuming Web Services at a low level using the HTTPREQUEST objectcan be simple or quite complex depending on the type of Web Service tobe used and its complexity. A few solutions attempt to make the invocationof Web Services simpler in Team Developer, like COM WS from LubosVnuk, but it currently only supports MSXML (although a port to Gupta XMLshould be relatively easy).The use of the HTTPREQUEST object to consume Web Services shouldbe compatible with any future version of Team Developer, since it involvesXMLLIB.APL library. This might not be the case when using the MS SOAPToolkit to consume Web Services and certainly not to create Web Servicessince the MS SOAP toolkit is deprecated in favor of .NET.Because Web Services are such an important technology, there is nodoubt that future versions of Team Developer will seamlessly allow thecreation and consumption of Web Services.Page 34Copyright © 2006 Gupta Technologies LLC. Gupta, the Gupta logo, andall Gupta products are licensed or registered trademarks of GuptaTechnologies, LLC., All other products are trademarks or registeredtrademarks of their respective owners. All rights reserved.Copyright © 2006 Gupta Technologies, LLC