Using SOAP Toolkit 2.0 to provide existing code as a WEB service

Web uses SOAP Toolkit 2.0 to provide existing code as a Web service
Building a distributed application using. NET
Steve Kirk and Priya Dhawan
Microsoft Developer Network

Summary: This article describes the data transformations that were made when using Microsoft SOAP Toolkit version 2.0 to provide existing Microsoft Visual Basic 6.0 code as a Web service.

Directory
Brief introduction
Data types provided by existing code
ADO 2x Command Object
ADO 2x Recordset Object
Stream Object
XMLDOM objects
Summarize

Brief introduction
Microsoft®soap Toolkit version 2.0 simplifies the task of providing and using existing code as a WEB service, as described in the SOAP Toolkit 2.0 document in the SDK section of the MSDN Library. Some of the main functions performed on the server side are conversions between data of different data types passed by existing code and XML messages (used between WEB service clients and servers). Conversions of simple data types can be handled automatically, and more complex data types require developers to provide conversion code.

The data transformation issues discussed in this article are not the only issues that need to be considered when evaluating whether existing code is appropriate for WEB service delivery. Other factors that should be considered include object and state models, the size of the data returned, how to indicate success, how to return an error message, the security model (including access control, authentication, and encryption), the execution model (synchronous or asynchronous), how to distribute the code, and the transaction model (COM + transaction or declarative transaction), and so on. These issues will be discussed in an upcoming architecture topic (English) article.

Data types provided by existing code
To describe the conversion of all data types passed by existing code is a fairly large project, so this article describes some of the most commonly used data types. An alternative to converting through SOAP Toolkit code is to extend existing code using an XML interface. This article discusses the conversion methods for the following data types:

ADO 2x Command Object
Ado2x Recordset Object
Stream Object
XMLDOM objects
ADO 2x Command Object
Existing code that accesses the database directly often provides Command objects for Microsoft ActiveX® Data Objects (ADO). Although you cannot pass a Command object between application tiers running in different processes, you can pass the object within the same process. For Single-line data entities, it is more efficient to return data through the Command object's output parameters than to return data through an ADO recordset. Therefore, the ADO Command object is useful for returning single-line entity data.

Reading data
The existing code in the following example returns an ADO Command object that contains data as an output parameter. Before the customer that is passed to the Web service, the code in the Custom Type Mapper uses the Soapserializer object to convert the Command object:

With Soapserializer
' Convert CommandType
. Startelement "CommandType"
. writestring Cmd.commandtype
. endelement
' Convert CommandText
. Startelement "CommandText"
Cmdtext = Cmd.commandtext
Cmdtext = Left (Cmd.commandtext, Len (Cmdtext)-8)
Cmdtext = Right (Cmdtext, Len (Cmdtext)-7)
. writestring Cmdtext
. endelement
' Convert Parameters Collection
. startelement "Parameters"
For i = 0 to Ocmd.parameters.count-1
. Startelement Right (Ocmd.parameters (i). Name, _
Len (Ocmd.parameters (i)). Name)-1)
. startelement "Direction"
. WriteString ocmd.parameters (i). Direction
. endelement
. startelement "Type"
. WriteString ocmd.parameters (i). Type
. endelement
. startelement "Size"
. WriteString ocmd.parameters (i). Size
. endelement
. startelement "Value"
. WriteString ocmd.parameters (i). Value
. endelement
. endelement
Next
. endelement
End With
Write Data
Passing data as a parameter of a Command object is a very effective method of data transfer. It can also be extended and provides some type-checking functionality.

In the following example, the XML data that the customer submits to the Web service is converted to the parameters of the ADO Command object, which is passed to the existing code:

Dim CMD as Adodb.command
Dim Param as ADODB. Parameter
' Pnode is the MSXML2 that contains the XML submitted by the customer. IXMLDOMNode
' Instantiate an ADO Command object
Set CMD = New Adodb.command
With CMD
' Applied CommandType and CommandText
. CommandType = _
CInt (Pnode.selectsinglenode ("CommandType"). nodeTypedValue)
. CommandText = Pnode.selectsinglenode ("CommandText"). nodeTypedValue
' Populate Parameters Collection
Set nodeparent = Pnode.selectsinglenode ("Parameters")
For i = 0 to Nodeparent.childnodes.length-1
Set Nodeparameter = nodeparent.childnodes (i)
Set Param = New ADODB. Parameter
With Param
. Name = "@" + nodeparameter.nodename
. Direction = _
Nodeparameter.selectsinglenode ("Direction"). nodeTypedValue
. Type = Nodeparameter.selectsinglenode ("Type"). nodeTypedValue
. Size = Nodeparameter.selectsinglenode ("size"). nodeTypedValue
. Value = Factory.getmapper (Enxsdstring, _
Nothing). Read (Nodeparameter.selectsinglenode ("Value"), _
Bstrencoding, Encodingmode, lflags)
End With
. Parameters.Append Oparam
Next
End With

ADO 2x Recordset Object
An ADO 2x disconnected recordset is typically used to pass data between tiers of multi-tier applications. The data can be single, multiline, or layered rows.

Reading data
In this example, the existing code returns an ADO Recordset object that contains hierarchical row data that is converted to XML and then returned to the customer:

Dim Doc as MSXML2. DOMDocument
Set Doc = New MSXML2. DOMDocument
' Write recordset data to XMLDOM
Rs. Save odoc, adPersistXML
' Pass XML to SOAP Toolkit serializer
Soapserializer.writexml Doc.xml

Write Data
In the following example, the ADO Recordset object is populated with XML that represents the hierarchical row data, and the object is passed to the existing code:

Dim rs as ADODB. Recordset
Dim Doc as MSXML2. DOMDocument
Set rs = New ADODB. Recordset
Set Doc = New MSXML2. DOMDocument
' Loading XML into the XMLDOMDocument
Doc.loadxml Pnode.xml
' Populate the Recordset with XML from XMLDOMDocument
Rs. Open Doc
Stream Object
Streams provide an efficient way to pass data between the local layers of an application. It is the primary way to read XML from Microsoft SQL server™2000.

Reading data
In the following example, the existing code returns an XML stream that represents a hierarchical row of data, which is converted and then returned to the customer:

Dim instream as ADODB. Stream
' Pvar contains Stream objects returned by existing code
Set instream = Pvar
' Pass the XML data from the spread to the SOAP serializer
Soapserializer.writestring Instream.readtext
XMLDOM objects
The Xmldom object is a good way to pass data between the local layers of a multi-tier application. It provides interface scalability, type checking, and schema validation capabilities.

Reading data
In the following example, the existing code returns a XMLDOMDocument object that is converted and then returned to the customer:

' Pvar contains XMLDOMDocument
Psoapserializer.writexml Pvar.xml

Write Data
In the following example, the Xmldom object is populated with XML that represents the hierarchical row data (submitted by the customer), and then the object is passed to the existing code:

Set odoc = New MSXML2. DOMDocument
' Load the IXMLDOMNode XML into the DOMDocument object
' Pnode contains IXMLDOMNode objects
Odoc.loadxml pnode.childnodes (0). xml
Summarize
This article and the accompanying examples introduce information about data transformations. With Data transformation, you can use SOAP Toolkit 2.0 to provide existing code as a WEB service. This article describes some of the commonly used interface objects.

The performance of these solutions varies and is affected by the size of the data being passed. In later articles in this series, we will compare these implementations.

When evaluating the suitability of existing code as a WEB service, interfaces are but one of many factors that should be considered. Other factors to consider include security (including authorization, authentication and encryption), transaction model, state model, ways to return errors and results, and whether the code is synchronized or asynchronous, and so on.