docs.intersystems.com
Home  /  Application Development: Additional Options  /  Creating Web Services and Web Clients  /  Using Datasets in SOAP Messages


Creating Web Services and Web Clients
Using Datasets in SOAP Messages
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


This chapter discusses %XML.DataSet, which is an XML-enabled dataset that you can use in SOAP messages when both the web service and client are based on InterSystems IRIS or when one side uses .NET. Other SOAP vendors do not support datasets.
This chapter provides the details on the following:
About Datasets
A dataset is an XML-format result set defined by Microsoft (and used for .NET) and also supported in InterSystems IRIS. If both the web service and client are based on InterSystems IRIS or when one side uses .NET, you can use datasets as input to or output from a web method. Other SOAP technologies do not understand this format.
When you work with web services or clients in InterSystems IRIS, you use %XML.DataSet (or a custom subclass) to represent a dataset. For details on using %XML.DataSet, see the class reference.
Note:
The %XML.DataSet class supports only a single table. That is, the query it uses can return only a single table.
The sample web service SOAP.Demo (in the SAMPLES namespace) demonstrates datasets in InterSystems IRIS. Specifically, the following web methods use datasets:
To output results of a query so that a Java-based web client can work with it, use a %ListOfObjects subclass; SOAP.Demo shows an example.
Defining a Typed Dataset
Any dataset uses a query that specifies the data to retrieve. If the query is known at compile time, the dataset is typed; otherwise it is untyped. Typed datasets are convenient in many cases; for example, in .NET, a typed dataset allows code completion in Microsoft Visual Studio.
To define a typed dataset, create a subclass of %XML.DataSet and specify the QUERYNAME and CLASSNAME parameters. Together, these parameters refer to a specific SQL query. When it generates the schema for the dataset, %XML.DataSet considers the class and property metadata such as any LogicalToXSD() methods in custom data types.
Note:
If you use %XML.DataSet as the return value for a method, the XML type for that value is DataSet. On the other hand, if you use a subclass of %XML.DataSet as the return value, the XML type for the value is the name of that subclass. This behavior is the same as that of other XML-enabled classes, and it affects the XML types that are described in the WSDL. See the chapter Controlling the Projection to XML Types in Projecting Objects to XML
Controlling the Dataset Format
By default, a dataset is written in Microsoft DiffGram format and is preceded by its XML schema. The following shows an example:
<SOAP-ENV:Body>
  <Get0Response xmlns="http://www.myapp.org">
    <Get0Result>
    <s:schema id="DefaultDataSet" xmlns="" 
    attributeFormDefault="qualified" 
    elementFormDefault="qualified"
    xmlns:s="http://www.w3.org/2001/XMLSchema" 
    xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
      <s:element name="DefaultDataSet" msdata:IsDataSet="true">
        <s:complexType>
          <s:choice maxOccurs="unbounded">
            <s:element name="GetPeople">
              <s:complexType>
                <s:sequence>
                  <s:element name="Name" type="s:string" minOccurs="0" />
                  <s:element name="DOB" type="s:date" minOccurs="0" />
                </s:sequence>
              </s:complexType>
            </s:element>
          </s:choice>
        </s:complexType>
      </s:element>
    </s:schema>

    <diffgr:diffgram 
    xmlns:msdata="urn:schemas-microsoft-com:xml-msdata" 
    xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1">
      <DefaultDataSet xmlns="">
        <GetPeople diffgr:id="GetPeople1" msdata:rowOrder="0">
          <Name>Quine,Howard Z.</Name>
          <DOB>1965-11-29</DOB>
        </GetPeople>
...
      </DefaultDataSet>
    </diffgr:diffgram>
   </Get0Result>
 </Get0Response>  
</SOAP-ENV:Body>
The %XML.DataSet class provides the following options for controlling this format:
%XML.DataSet also provides the CaseSensitive property, which corresponds to the Microsoft dataset property of the same name. The default is false, for compatibility reasons.
Viewing the Dataset and Schema as XML
A dataset that extends %XML.DataSet has utility methods that you can use to generate XML. All of these methods write to the current device:
For information on generating XML schemas from XML-enabled objects, see Using XML Tools.
Effect on the WSDL
If an InterSystems IRIS web service uses %XML.DataSet as input or output to a web method, that affects the WSDL so that clients other than InterSystems IRIS and .NET have difficulty consuming the WSDL.
For a typed dataset, the WSDL includes the following elements (within the <types> section):
<s:element name="GetDataSetByNameResponse">
   <s:complexType>
      <s:sequence>
        <s:element name="GetDataSetByNameResult" type="s0:ByNameDataSet" /> 
      </s:sequence>
   </s:complexType>
</s:element>
<s:complexType name="ByNameDataSet">
   <s:sequence>
     <s:any namespace="http://tempuri.org/ByNameDataSet" /> 
   </s:sequence>
</s:complexType>
For an untyped dataset, the WSDL includes the following:
<s:element name="GetByNameResponse">
   <s:complexType>
      <s:sequence>
         <s:element name="GetByNameResult" type="s0:DataSet" /> 
      </s:sequence>
   </s:complexType>
</s:element>
<s:complexType name="DataSet">
   <s:sequence>
      <s:element ref="s:schema" /> 
   <s:any /> 
   </s:sequence>
</s:complexType>
In the latter case, if you attempt to generate a web client within a tool other than InterSystems IRIS or .NET, an error occurs because there is not enough information for that tool. For Metro, it is possible to load additional schema information before attempting to consume the WSDL. To do so, you can use a command-line tool called wsimport. This technique can provide enough information to generate the client.
In all cases, however, considerable work is necessary to write code so that the client can either interpret or generate messages in the appropriate form.