diff options
Diffstat (limited to 'lib/odbc/doc/src/error_handling.xml')
| -rw-r--r-- | lib/odbc/doc/src/error_handling.xml | 174 |
1 files changed, 174 insertions, 0 deletions
diff --git a/lib/odbc/doc/src/error_handling.xml b/lib/odbc/doc/src/error_handling.xml new file mode 100644 index 0000000000..26ad7f9848 --- /dev/null +++ b/lib/odbc/doc/src/error_handling.xml @@ -0,0 +1,174 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2003</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Error handling</title> + <prepared>Ingela Anderton</prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date></date> + <rev></rev> + <file>error_handling.xml</file> + </header> + + <section> + <title>Strategy </title> + <p>On a conceptual level starting a database connection using the + Erlang ODBC API is a basic client server application. The client + process uses the API to start and communicate with the server + process that manages the connection. The strategy of the Erlang + ODBC application is that programming faults in the application + itself will cause the connection process to terminate + abnormally.(When a process terminates abnormally its supervisor + will log relevant error reports.) Calls to API functions during or + after termination of the connection process, will return <c>{error, connection_closed}</c>. Contextual errors on the other + hand will not terminate the connection it will only return + <c>{error, Reason} </c> to the client, where <c>Reason</c> may be + any erlang term.</p> + + <section> + <title>Clients </title> + <p>The connection is associated with the process that created it + and can only be accessed through it. The reason for this is to + preserve the semantics of result sets and transactions when + select_count/[2,3] is called or auto_commit is turned off. + Attempts to use the connection from another process will + fail. This will not effect the connection. On the other hand, if + the client process dies the connection will be terminated.</p> + </section> + + <section> + <title>Timeouts </title> + <p>All request made by the client to the connection are + synchronous. If the timeout is used and expires the client + process will exit with reason timeout. Proably the right thing + to do is let the client die and perhaps be restarted by its + supervisor. But if the client chooses to catch this timeout, + it is a good idea to wait a little while before trying + again. If there are too many consecutive timeouts that are + caught the connection process will conclude that there is + something radically wrong and terminate the connection.</p> + </section> + + <section> + <title>Gaurds </title> + <p>All API-functions are guarded and if you pass an argument of + the wrong type a runtime error will occur. All input parameters + to internal functions are trusted to be correct. It is a good + programming practise to only distrust input from truly external + sources. You are not supposed to catch these errors, it will + only make the code very messy and much more complex, which + introduces more bugs and in the worst case also covers up the + actual faults. Put your effort on testing instead, you should + trust your own input.</p> + </section> + </section> + + <section> + <title>The whole picture </title> + <p>As the Erlang ODBC application relies on third party products + and communicates with a database that probably runs on an other + computer in the network there are plenty of things that might go + wrong. To fully understand the things that might happen it + facilitate to know the design of the Erlang ODBC application, + hence here follows a short description of the current design.</p> + <note> + <p>Please note that design is something, that not + necessarily will, but might change in future releases. While the + semantics of the API will not change as it is independent of the + implementation.</p> + </note> + <image file="odbc_app_arc.gif"> + <icaption>Architecture of the Erlang odbc application</icaption> + </image> + <p>When you do application:start(odbc) the only thing that + happens is that a supervisor process is started. For each call + to the API function connect/2 a process is spawned and added as + a child to the Erlang ODBC supervisor. The supervisors only + tasks are to provide error-log reports, if a child process should + die abnormally, and the possibility to do a code change. Only + the client process has the knowledge to decide if this + connection managing process should be restarted.</p> + <p>The erlang connection process spawned by connect/2, will open a + port to a c-process that handles the communication with the + database through Microsoft's ODBC API. The erlang port will be + kept open for exit signal propagation, if something goes wrong + in the c-process and it exits we want know as mush as possible + about the reason. The main communication with the c-process is + done through sockets. The C-process consists of two threads, + the supervisor thread and the database handler thread. The + supervisor thread checks for shutdown messages on the supervisor + socket and the database handler thread receives requests and sends + answers on the database socket. If the database thread seems to + hang on some database call, the erlang control process will send + a shutdown message on the supervisor socket, in this case the + c-process will exit. If the c-process crashes/exits it will + bring the erlang-process down too and vice versa i.e. the + connection is terminated.</p> + <note> + <p>The function connect/2 will start the odbc application if + that is not already done. In this case a supervisor information + log will be produced stating that the odbc application was started + as a temporary application. It is really the responsibility of the + application that uses the API too make sure it is started in the + desired way.</p> + </note> + + <section> + <title>Error types</title> + <p>The types of errors that may occur can be divide into the + following categories.</p> + <list type="bulleted"> + <item>Configuration problems - Everything from that the + database was not set up right to that the c-program that + should be run through the erlang port was not compiled for + your platform.</item> + <item>Errors discovered by the ODBC driver - If calls to the + ODBC-driver fails due to circumstances that can not be + controlled by the Erlang ODBC application programmer, an + error string will be dug up from the driver. This string + will be the <c>Reason</c> in the <c>{error, Reason} </c> + return value. How good this error message is will of course + be driver dependent. Examples of such circumstances are + trying to insert the same key twice, invalid SQL-queries and + that the database has gone off line.</item> + <item>Connection termination - If a connection is terminated + in an abnormal way, or if you try to use a connection that + you have already terminated in a normal way by calling + disconnect/1, the return value will be<c>{error, connection_closed}</c>. A connection could end abnormally + because of an programming error in the Erlang ODBC + application, but also if the ODBC driver crashes.</item> + <item>Contextual errors - If API functions are used in the + wrong context, the <c>Reason</c> in the error tuple will + be a descriptive atom. For instance if you try to call the + function <c>last/[1,2] </c> without first calling <c>select_count/[2,3] </c> to associate a result set with the + connection. If the ODBC-driver does not support some + functions, or if you disabled some functionality for a + connection and then try to use it.</item> + </list> + </section> + </section> +</chapter> + + |