<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- Error handling</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/odbc-2.10.13.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>Erlang ODBC</strong><br><strong>User's Guide</strong><br><small>Version 2.10.13</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="no" title="Introduction" expanded="false">Introduction<ul>
<li><a href="introduction.html">
Top of chapter
</a></li>
<li title="Purpose"><a href="introduction.html#id57521">Purpose</a></li>
<li title="Prerequisites"><a href="introduction.html#id57527">Prerequisites</a></li>
<li title="About ODBC"><a href="introduction.html#id56991">About ODBC</a></li>
<li title="About the Erlang ODBC application"><a href="introduction.html#id58131">About the Erlang ODBC application</a></li>
</ul>
</li>
<li id="no" title="Getting started" expanded="false">Getting started<ul>
<li><a href="getting_started.html">
Top of chapter
</a></li>
<li title="Setting things up "><a href="getting_started.html#id60105">Setting things up </a></li>
<li title="Using the Erlang API"><a href="getting_started.html#id56674">Using the Erlang API</a></li>
</ul>
</li>
<li id="no" title="Databases" expanded="false">Databases<ul>
<li><a href="databases.html">
Top of chapter
</a></li>
<li title="Databases"><a href="databases.html#id57988">Databases</a></li>
<li title="Database independence "><a href="databases.html#id61089">Database independence </a></li>
<li title="Data types "><a href="databases.html#id61509">Data types </a></li>
<li title="Batch handling"><a href="databases.html#id62159">Batch handling</a></li>
</ul>
</li>
<li id="loadscrollpos" title="Error handling" expanded="true">Error handling<ul>
<li><a href="error_handling.html">
Top of chapter
</a></li>
<li title="Strategy "><a href="error_handling.html#id62301">Strategy </a></li>
<li title="The whole picture "><a href="error_handling.html#id62376">The whole picture </a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>4 Error handling</h1>
<h3><a name="id62301">4.1
Strategy </a></h3>
<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 <span class="code">{error, connection_closed}</span>. Contextual errors on the other
hand will not terminate the connection it will only return
<span class="code">{error, Reason} </span> to the client, where <span class="code">Reason</span> may be
any erlang term.</p>
<h4>Clients </h4>
<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>
<h4>Timeouts </h4>
<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>
<h4>Gaurds </h4>
<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>
<h3><a name="id62376">4.2
The whole picture </a></h3>
<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>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<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>
</p></div>
</div>
<img alt="IMAGE MISSING" src="odbc_app_arc.gif"><br>
<em>Figure
4.1:
Architecture of the Erlang odbc application</em>
<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>
<h4>Error types</h4>
<p>The types of errors that may occur can be divide into the
following categories.</p>
<ul>
<li>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.</li>
<li>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 <span class="code">Reason</span> in the <span class="code">{error, Reason} </span>
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.</li>
<li>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<span class="code">{error, connection_closed}</span>. A connection could end abnormally
because of an programming error in the Erlang ODBC
application, but also if the ODBC driver crashes.</li>
<li>Contextual errors - If API functions are used in the
wrong context, the <span class="code">Reason</span> in the error tuple will
be a descriptive atom. For instance if you try to call the
function <span class="code">last/[1,2] </span> without first calling <span class="code">select_count/[2,3] </span> 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.</li>
</ul>
</div>
<div class="footer">
<hr>
<p>Copyright © 1999-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
