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
`LOCATION=`	`DRIVER`	`INSTANCE`
`CODE=`	`NOT_SUPPORTED`	`WSDL`
`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
Item	Meaning	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.	`CallbackComponentName.Operation`
`DETAIL=`	String giving more details about the error. There is no default value; if not specified, it will not be present in $procerrorcontext.	None

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
Item	Meaning
`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
params
  string pList : IN
endparams

variables
  string additional
  string item
endvariables

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

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

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

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

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

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

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

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

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

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

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xml="http://www.w3.org/XML/1998/namespace">
 <soapenv:Body>
  <soapenv:Fault>
   <faultcode xmlns:fc="http://faultcodes.org/">fc:Server</faultcode>
   <faultstring xml:lang="en-GB">Bad error in server!</faultstring>
   <detail>
    <de1:detail1 xmlns:de1="http://detail1.error/">
     <message>Application-specific error 1</message>
     <e:error xmlns:e="http://empty.error/" />
    </de1:detail1>
    <de2:detail2 xmlns:de2="http://detail2.error/">
     <message>
      <e:error xmlns:e="http://another.error/">
        Application-specific error 2
      </e:error>
     </message>
    </de2:detail2>
   </detail>
  </soapenv:Fault>
 </soapenv:Body>
</soapenv:Envelope>

Calling the getSoapFault entry will produce the following output:

DRV=SOP
LOCATION=SOAPFAULT
CODE={http://faultcodes.org/}Server
MESSAGE=Bad error in server!
No ACTOR item
DETAIL=<?xml version="1.0" encoding="UTF-8"?>
<detail>
 <ns0:detail1 xmlns:ns0="http://detail1.error/">
  <message>Application-specific error 1</message>
  <ns1:error xmlns:ns1="http://empty.error/" />
 </ns0:detail1>
 <ns0:detail2 xmlns:ns0="http://detail2.error/">
  <message>
   <ns1:error xmlns:ns1="http://another.error/">Application-specific error 2</ns1:error>
  </message>
 </ns0:detail2>
</detail>

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.