Using Generated Web Services

Using Attachments with Generated Web Services

Streaming attachments can be defined in metadata as data sources (input attachments) and data targets (output attachments). Two types of streaming attachments are available:

XML stream

specifies an attachment that is in-lined in the payload of the SOAP request or SOAP response. You can also specify a schema for this data. The schema is included in the generated WSDL.

Note: You can specify single streaming output the same way you do with the XMLA Web service by selecting Stream as the result capability. However, using data targets provides more flexibility because you can provide the name of the attachment as well as provide a schema that matches your expected data. [cautionend]

generic stream

specifies an out-of-band binary attachment that is included with the SOAP request or SOAP response in one of the following ways:

If the attachment data is small, it can be included directly in the payload and encoded as Base64 binary data.
If the attachment data is not small, then it is included out-of-band from the payload as a MIME multi-part related attachment where it is referenced from the payload via MTOM XOP/Include or SOAP with Attachments references (swaRef).

The following code is an example of a schema definition for a generated Web service that expects one generic (binary) stream as an output response:

<element name="stpAllParm1Response">
   <complexType>
      <sequence>
         <element name="stpAllParm1Result">
            <complexType>
               <sequence>
                  <element maxOccurs="1" minOccurs="0" name="Streams">
                     <complexType>
                        <sequence>
                           <element maxOccurs="1" minOccurs="0" name="myAttachment">
                              <complexType>
                                 <sequence>
                                    <element name="Value" type="base64Binary"/>
                                 </sequence>
                                 <attribute name="contentType" type="string"/>
                              </complexType>
                           </element>
                        </sequence>
                     </complexType>
                  </element>
               </sequence>
             </complexType>
         </element>
      </sequence>
   </complexType>
</element>

In this generated schema, myAttachment is the name of the element that represents the output attachment. This name is defined by the user in metadata. This element is a container for the actual value of that attachment. The content type of the attachment can be returned as an attribute to further clarify the content of the data within the attachment.

Package type output is also supported. This type of output produces one or more attachments and packages them together as a single entity. To enable this type of output, select Package as the result capability for the stored process.

Attachment definitions in metadata provide a means to establish a contract between all parties involved in a Web service request. The Web Service Maker Web service generates a WSDL and schema based on metadata definitions that provide a contract between the client and generated Web service. The generated Web service enforces that all required attachments are sent in the request. The SAS code that executes on the SAS server must be written in accordance to the metadata definitions that it is representing; otherwise, problems might occur (for example, not reading the correct stream, and so on) resulting in SAS errors. If a SAS error occurs, the generated Web service returns a SOAP fault to the client.

Top of Page