XML

The Payload for a SOAP Response

Just as our sample SOAP request message contained child elements for all the in and in/out parameters of the method, the SOAP response will contain child elements for each out and in/out parameter. Let's say you have the following Visual Basic function:

  Public Function UpdatePO(byref OrderID as Integer, _
      byval CustomerNumber as Integer, _
      byval Item as Integer, _
      byval Quantity as Integer) as Integer

In this case, the server would set the orderID variable to some value and return the value to the client. Because the orderID parameter is byref, it is an in/out parameter. UpdatePO is now a function, and it will return a value (a Boolean value, in this case). The return value of the function can be considered an out only parameter.

For this UpdatePO function, the request payload containing all the in and in/out parameters might look like this:

  <SOAP-ENV:Envelope
      xmlns:xsi="http://www.w3.org/1999/XMLSchema/instance"
      xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope"
      xsi:schemaLocation=
        "http://www.northwindtraders.com/schemas/NPOSchema.xsd">
     <SOAP-ENV:Body xsi:type="NorthwindBody">
        <UpdatePO>
        <orderID>0</orderID>
        <customerNumber>999</customerNumber>
        <item>89</item>
        <quantity>3000</quantity>
        </UpdatePO>
     </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>

The response package including the payload that contains all the out and in/out parameters would look like this:

  HTTP/1.1 200 OK
  Content-Type: text/xml
  Content-Length: nnnn
  <SOAP-ENV:Envelope
     xmlns:xsi="http://www.w3.org/1999/XMLSchema/instance"
     xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope"
     xsi:schemaLocation=
        "http://www.northwindtraders.com/schemas/NPOSchema.xsd">
     <SOAP-ENV:Body xsi:type="NorthwindBody">
        <UpdatePO>
           <orderID>09877</orderID>
           <return>0</return>
        </UpdatePO>
     </SOAP-ENV:Body>
  </SOAP-ENV:Envelope>

Notice that the SOAP response message doesn't have the SOAPAction header field. This header field is required only in the SOAP request message. During request processing, a SOAP package will be passed to a SOAP application on the server that handles SOAP requests. This SOAP application will in turn pass on the request to the appropriate method.

Sometimes a request cannot be processed properly and errors might occur. Errors can be handled in several ways, depending on where the error occurs. If an error occurs during the transport of the package to the method, the error is usually handled by returning status codes other than 200. An example of this situation is when there is a problem getting the package through a firewall or the specified host does not exist or is down.

Once the information has been passed to the method, it is possible that the application handling the request will experience an error. In this case, you can return a custom HTTP code, use one of the predefined HTTP codes, use an element, such as the return element in the preceding example, or return a SOAP package that contains a Fault element to pass back the error information. Let's look at how to use the Fault element to report errors.