Information Returned for Web Services Call-Out Errors

If an error occurs when calling out to a web service, Uniface generates error -150 and provides details in $procerrorcontext. One type of error could be a SOAP Fault received from the remote web service provider. Most of the information about the fault is provided as a Uniface list under the ADDITIONAL ID.

Location of the Error

The LOCATION item under the ADDITIONAL identifier gives the stage of SOAP call-out in which the error was detected. It can contain one of the following values:

Values of LOCATION
Value Meaning
DRIVER Error occurred while initializing or calling the SOAP connector; for example, during call validation; local error.
INSTANCE Error occurred while gathering information about the component and operation; for example, during signature lookup or WSDL parsing; local error.
REQUEST Error occurred while preparing the SOAP envelope; for example, while creating serialisers and deserialisers and the SOAP envelope itself. After the invocation and callbacks, this location also handles the response handling, provided the response is not a SOAP fault; local error.
CALLBACK_PRE Error occurred while processing the list of SOAP_CALLOUT_PRE operations; callback operation error
INVOCATION Error occurred while sending or receiving the SOAP envelope over the network; local error.
CALLBACK_POST Error occurred while processing the list of SOAP_CALLOUT_POST operations; callback operation error
SOAPFAULT SOAP fault returned by the web service; remote error.

For each LOCATION, the error is further described using the items CODE, MESSAGE, ACTOR, and DETAIL

Information Returned for Local Errors

Local errors can occur when preparing a call-out request or processing the response. They can include errors that occurr when executing callback operations. Any value of LOCATION, except SOAPFAULT, indicates a local error. (If LOCATION=SOAPFAULT, a remote error occurred.)

SOAP Error Items
Item Meaning
CODE=ErrorCode Short form the error description; mandatory.
MESSAGE=ErrorString Long form of the error description; mandatory.
ACTOR= If LOCATION is CALLBACK_PRE or CALLBACK_POST, the component name and operation of the callback operation, or a string giving actor information, as defined by the developer.
DETAIL= A string giving further application or processing details about the error, if available.

For example, the following table shows some examples of information that could be returned for local errors detected when calling the SOAP connector or the component signature:

Examples of Information About Local Errors
  Error When Calling SOAP Connector Error When Calling Component
Item Value Value
MESSAGE= Soap component engine call not supported WSDL reader error
DETAIL= SOAPCE::soapNewInst Statefull Web service component is not supported Importing WSDL from location http://...

Information Returned for Callback Operation Errors

Callback operation errors are local errors that may occur when executing a callback operation. If LOCATION=CALLBACK_PRE or CALLBACK_POST, the information returned in $procerrorcontext depends on what the Uniface developer did when implementing the SOAP callback operations for web services (SOAP_CALLOUT_PRE and SOAP_CALLOUT_POST).

When implementing a callback operation, you can return -1 to indicate an error and fill the envelope string parameter with an error message. The envelope parameter may be empty, or contain a simple string, or an associative list. The associative list may contain any of the following key values that are defined in $procerrorcontext:

SOAP Error Information for SOAP Callback Operations



Default, if not specified

CODE=ErrorCode Error code, or Client if not specified Client
MESSAGE=ErrorString Error message.

Complete returned envelope string, if none of these items are found and the envelope does contain a returned string.

Error was detected in callout callback operation
ACTOR= String giving actor information, as defined by the developer.

If not specified, the component name and operation of the callback operation are provided.

DETAIL= String giving more details about the error.

There is no default value; if not specified, it will not be present in $procerrorcontext.


Information Returned for Remote Errors

If LOCATION=SOAPFAULT, the error is a SOAP fault received from the web service provider.

In this case, the ADDITIONAL information correspond to the child elements of the SOAP Fault element, as defined by the SOAP protocol. (For detailed descriptions of the SOAP Fault elements, consult the Simple Object Access Protocol (SOAP) 1.1.)

SOAP Fault Information


CODE=ErrorCode Contents of the <faultcode> element, with namespace prefixes expanded.
MESSAGE=ErrorString Literal contents of the <faultstring> element; mandatory.
ACTOR= Literal contents of the <faultactor> element, if available
DETAIL= Well-formed XML string representing the <detail> element in the SOAP fault.

Parsing SOAP Errors in $procerrorcontext

The sample ProcScript entry getSoapFault parses the associative list returned by $procerrorcontext. This list can contain several levels of nested lists.

Tip: You can copy this entry into your own code to parse the information provided in $procerrorcontext.

entry getSoapFault
  string pList : IN

  string additional
  string item

getitem/id item, pList, "ADDITIONAL"
if ($status = 0)
  putmess "No ADDITIONAL item"

pList = item
getitem/id item, pList, "DRV"
if ($status = 0)
  putmess "No DRV item"
  putmess "DRV=%%item%%%%%^"

getitem/id item, pList, "LOCATION"
if ($status = 0)
  putmess "No LOCATION item"
  putmess "LOCATION=%%item%%%%%^"

getitem/id item, pList, "CODE"
if ($status = 0)
  putmess "No CODE item"
  putmess "CODE=%%item%%%%%^"

getitem/id item, pList, "MESSAGE"
if ($status = 0)
  putmess "No MESSAGE item"
  putmess "MESSAGE=%%item%%%%%^"

getitem/id item, pList, "ACTOR"
if ($status = 0)
  putmess "No ACTOR item"
  putmess "ACTOR=%%item%%%%%^"

getitem/id item, pList, "DETAIL"
if ($status = 0)
  putmess "No DETAIL item"
  putmess "DETAIL=%%item%%%%%^"

Call the getSoapFault entry after an error occurs when activating a web service. For example:

if ($procerror = -150)
    vErrorlist = $procerrorcontext
    call getSoapFault(vErrorlist)

For example, if a SOAP request for a web service returns the following SOAP Fault:

<soapenv:Envelope xmlns:soapenv=""
   <faultcode xmlns:fc="">fc:Server</faultcode>
   <faultstring xml:lang="en-GB">Bad error in server!</faultstring>
    <de1:detail1 xmlns:de1="http://detail1.error/">
     <message>Application-specific error 1</message>
     <e:error xmlns:e="http://empty.error/" />
    <de2:detail2 xmlns:de2="http://detail2.error/">
      <e:error xmlns:e="http://another.error/">
        Application-specific error 2

Calling the getSoapFault entry will produce the following output:

MESSAGE=Bad error in server!
No ACTOR item
DETAIL=<?xml version="1.0" encoding="UTF-8"?>
 <ns0:detail1 xmlns:ns0="http://detail1.error/">
  <message>Application-specific error 1</message>
  <ns1:error xmlns:ns1="http://empty.error/" />
 <ns0:detail2 xmlns:ns0="http://detail2.error/">
   <ns1:error xmlns:ns1="http://another.error/">Application-specific error 2</ns1:error>

Note:  The namespace prefixes and the whitespace formatting have changed and the complete detail element of the SOAP fault is placed in the detail list item as complete and well-formed xml.

Related Topics