Soap Exceptions

Back To Appendix Home

Back to ECGridOS Wiki

---

Catching Errors in ECGridOS™

As in all good programming, trapping error situations is key to a great user experience. ECGridOS makes extensive use of SOAP Exceptions to help the developer along when problems occur.

There are two types of SOAP errors that can by thrown by ECGridOS. The first is by the Framework itself, primarily syntactic, and the second is by the ECGridOS system, syntactic and semantic.

Framework Exceptions

The most common Framework Exception is for missing parameters, as with web services all parameters are required. Additionally, an exception generated due to internal server errors will likely throw a Framework Exception.

ECGridOS Exceptions

When ECGridOS throws an exception, it creates a specifically formatted node that is included in the SOAP Exception.

<details>
  <ErrorCode>8</ErrorCode>
  <ErrorString>Invalid data length.</ErrorString>
  <ErrorItem>Description</ErrorItem>
  <ErrorMessage>Too Integer (max=35)</ErrorMessage>
</details>

By parsing out the details node, you can determine programmatically what happened and make corrective actions. The various ECGridOS Error Codes are listed at the bottom of this section.

The system will detect and report the attempt to create duplicate IDs, redundant Interconnect Requests, unauthorized access and a host of data errors.

The following code snippet shows how to catch and parse SOAP Exceptions. Please note this a Example Only please follow all industry standard coding procedures and patterns in your production code.

C#

using System;
using System.Web.Services.Protocols;
using System.Xml;
using ECGridService = ECGrid_API.net.ecgridos;

namespace ECGrid_API
{
    /// <summary>
    /// ECGridSOAPErrorInfo - Class to Capture ECGridOS Soap Exception Variables
    /// </summary>
    public class ECGridSOAPErrorInfo
    {
        public string ErrorCode;
        public string ErrorString;
        public string ErrorItem;
        public string ErrorMessage;
    } // END CLASS

    /// <summary>
    /// Main Method for Running the Program
    /// </summary>
    /// <param name="args"></param>
    class ECGrid_Main
    {
        static void Main(string[] args)
        {
            try
            {
                using (ECGridService.ECGridOSAPIv3 ECGrid = new ECGridService.ECGridOSAPIv3())
                {
                    string SessionID = "00000000-0000-0000-0000-000000000000";
                    try
                    {
                        var NetworkList = ECGrid.NetworkList(SessionID, "");
                    }
                    catch (SoapException SoapEx)
                    {
                        var ECGridOS_Soap_Ex = CatchException(SoapEx);
                        Console.WriteLine("ECGridOS ErrorCode: " + ECGridOS_Soap_Ex.ErrorCode);
                        Console.WriteLine("ECGridOS ErrorItem: " + ECGridOS_Soap_Ex.ErrorItem);
                        Console.WriteLine("ECGridOS ErrorMessage: " + ECGridOS_Soap_Ex.ErrorMessage);
                        Console.WriteLine("ECGridOS ErrorString: " + ECGridOS_Soap_Ex.ErrorString);
                        Console.WriteLine("Soap Exception Error StackTrace: " + SoapEx.StackTrace);
                    }
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine("Unhandled Exception: " + ex.ToString());
            }

            Console.WriteLine("Press any Key to quit...");
            Console.ReadKey();

        } // END MAIN

        /// <summary>
        /// CatchException - Method to Catch ECGridOS and Native Soap Exceptions
        /// Parses XML to get Error Detail Information
        /// </summary>
        /// <param name="ex">SoapException</param>
        /// <returns>ECGridSOAPErrorInfo Class Object</returns>
        public static ECGridSOAPErrorInfo CatchException(SoapException ex)
        {
            ECGridSOAPErrorInfo functionReturnValue = new ECGridSOAPErrorInfo();

            XmlDocument doc = new XmlDocument();
	    XmlNode Node = default(XmlNode);
	    doc.LoadXml(ex.Detail.OuterXml);
	    Node = doc.DocumentElement.SelectSingleNode("ErrorInfo");

            if (Node == null) {

		// This picks up Framework generated SOAP Exceptions
		var _with1 = functionReturnValue;
		_with1.ErrorCode = "-1";
                _with1.ErrorString = ex.ToString();
		_with1.ErrorItem = "";
		 _with1.ErrorMessage = "";

	    } else {

		// This picks up ECGridOS generated SOAP Exceptions
		var _with2 = functionReturnValue;
		_with2.ErrorCode = Node.SelectSingleNode("ErrorCode").InnerText;
                _with2.ErrorString = Node.SelectSingleNode("ErrorString").InnerText;
		_with2.ErrorItem = Node.SelectSingleNode("ErrorItem").InnerText;
		_with2.ErrorMessage = Node.SelectSingleNode("ErrorMessage").InnerText;

	    }
	    return functionReturnValue;

        } // END METHOD
    } // END CLASS

} // END NAMESPACE

---

VB

Imports System.Xml

Class ErrorInfo
    Public ErrorCode As Short
    Public ErrorString As String
    Public ErrorItem As String
    Public ErrorMessage As String
End Class

Private Sub SomeFunction()
    Dim errInfo As ErrorInfo
    Try
        Dim parcels() As net.ecgridos.ParcelIDInfo = _
         ecgridos.ParcelInBoxArchiveEx(SessionID, _
                                       NetworkID, _
                                       MailboxID, _
                                       BeginDate, _
                                       EndDate, _
                                       ECGridID1, _
                                       ECGridID2, _
                                       Status)
        [...]
    Catch ex As SoapException
        errInfo = CatchException(ex)
        [...]
    End Try
    [...]
End Sub

Private Function CatchException(ByVal ex As SoapException) As ErrorInfo
    Dim doc As New XmlDocument
    Dim Node As XmlNode
    CatchException = New ErrorInfo
    doc.LoadXml(ex.Detail.OuterXml)
    Node = doc.DocumentElement.SelectSingleNode("ErrorInfo")
    If Node Is Nothing Then
        'This picks up Framework generated SOAP Exceptions
        With CatchException
            .ErrorCode = -1
            .ErrorString = ex.Message
            .ErrorItem = ""
            .ErrorMessage = ""
        End With
    Else
        'This picks up ECGridOS generated SOAP Exceptions
        With CatchException
            .ErrorCode = CInt(Node.SelectSingleNode("ErrorCode").InnerText)
            .ErrorString = Node.SelectSingleNode("ErrorString").InnerText
            .ErrorItem = Node.SelectSingleNode("ErrorItem").InnerText
            .ErrorMessage = Node.SelectSingleNode("ErrorMessage").InnerText
        End With
    End If
End Function

---

PHP

<?php

try{

    $SessionID = "00000000-0000-0000-0000-000000000000";

    //Create the client object
    $soapClient = new SoapClient('https://ecgridos.net/v3.2/prod/ecgridos.asmx?WSDL');

    //Use the functions of the client, the params of the function are in the associative array
    $params = array('SessionID' => $SessionID, 'Name' => '');
    $response = $soapClient->NetworkList($params);

    var_dump($response);
}
catch(SoapFault $fault)
{
    $ECGridOS_Soap_Ex = CatchException($fault);
    echo "ECGridOS Soap Exception ErrorCode: ".$ECGridOS_Soap_Ex->ErrorCode."<br/>";
    echo "ECGridOS Soap Exception ErrorItem: ".$ECGridOS_Soap_Ex->ErrorItem."<br/>";
    echo "ECGridOS Soap Exception ErrorMessage: ".$ECGridOS_Soap_Ex->ErrorMessage."<br/>";
    echo "ECGridOS Soap Exception ErrorString: ".$ECGridOS_Soap_Ex->ErrorString."<br/><br/>";
    echo "Soap Exception Error: ".$fault->faultstring."<br/><br/>";

    var_dump($fault);
}
catch(Exception $e)
{
    echo 'Caught exception: ',  $e->getMessage(), "\n";
}

class ECGridSOAPErrorInfo
{
    public $ErrorCode;
    public $ErrorString;
    public $ErrorItem;
    public $ErrorMessage;
} // END CLASS

function CatchException($ex)
{
    $functionReturnValue = new ECGridSOAPErrorInfo();
    $node = $ex->detail->ErrorInfo;

    if ($node == null) {

        // This picks up Framework generated SOAP Exceptions
        $functionReturnValue->ErrorCode = "-1";
        $functionReturnValue->ErrorString = $ex.ToString();
        $functionReturnValue->ErrorItem = "";
        $functionReturnValue->ErrorMessage = "";

    } else {

        // This picks up ECGridOS generated SOAP Exceptions
        $functionReturnValue->ErrorCode = $node->ErrorCode;
        $functionReturnValue->ErrorString = $node->ErrorString;
        $functionReturnValue->ErrorItem = $node->ErrorItem;
        $functionReturnValue->ErrorMessage = $node->ErrorMessage;
    }

    return $functionReturnValue;

} // END FUNCTION

?>

---

ECGridOS Error Codes

ErrorCode	Description
1	Session timeout
2	Access denied
3	Not found
4	Invalid ID
5	Duplicate ID
6	ID exists on network
7	Invalid data type
8	Invalid data length
9	Data error
10	SQL Error

---

Back To Appendix Home