From 66c6cede2b5039ca05ad57d3da3b76a5b8e9da47 Mon Sep 17 00:00:00 2001
From: Bernard Duggan <bernie@m5.net>
Date: Wed, 25 Jul 2012 17:36:40 +1000
Subject: Add extended_errors option to ODBC

This patch adds the extended_errors option to odbc:connect/2. When
enabled, this option alters the return code of ODBC operations that
produce errors to include the ODBC error code as well as the native
error code, in addition to the ODBC reason field which is returned by
default. The extended error information can be used to produce more
sophisticated error handling than is possible with the standard ODBC
Reason alone.
---
 lib/odbc/doc/src/odbc.xml | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

(limited to 'lib/odbc/doc')

diff --git a/lib/odbc/doc/src/odbc.xml b/lib/odbc/doc/src/odbc.xml
index 8a58dc2848..0e3386b11f 100644
--- a/lib/odbc/doc/src/odbc.xml
+++ b/lib/odbc/doc/src/odbc.xml
@@ -74,8 +74,12 @@
     <code type="none">
  milliseconds() = integer() >= 0     </code>
     <code type="none">
- common_reason() = connection_closed | term() - some kind of
-                 explanation of what went wrong    </code>
+ common_reason() = connection_closed | extended_error() | term() - some kind of
+ explanation of what went wrong    </code>
+    <code type="none">
+ extended_error() = {string(), integer(), Reason} - extended error type with ODBC
+ and native database error codes, as well as the base reason that would have been
+ returned had extended_errors not been enabled. </code>
     <code type="none">
  string() = list of ASCII characters    </code>
     <code type="none">
@@ -143,7 +147,7 @@
         <d>All options has default values. </d>
         <v>option() = {auto_commit, on | off} | {timeout, milliseconds()}
 	| {binary_strings, on | off} | {tuple_row, on | off} | {scrollable_cursors, on | off} |
-	{trace_driver, on | off} </v>
+	{trace_driver, on | off} | {extended_errors, on | off} </v>
         <v>Ref = connection_reference() - should be used to access the connection. </v>
         <v>Reason = port_program_executable_not_found | common_reason()</v>
       </type>
@@ -196,6 +200,19 @@
           <p>For more information about the <c>ConnectStr</c> see
             description of the function SQLDriverConnect in [1].</p>
         </note>
+
+		  <p>The <c>extended_errors</c> option enables extended ODBC error
+			  information when an operation fails. Rather than returning <c>{error, Reason}</c>,
+			  the failing function will reutrn <c>{error, {ODBCErrorCode, NativeErrorCode, Reason}}</c>.
+			  Note that this information is probably of little use when writing database-independent code,
+			  but can be of assistance in providing more sophisticated error handling when dealing with
+			  a known underlying database.
+			 <list type="bulleted">
+				  <item><c>ODBCErrorCode</c> is the ODBC error string returned by the ODBC driver.</item>
+				  <item><c>NativeErrorCode</c> is the numberic error code returned by the underlying database. The possible values
+					  and their meanings are dependent on the database being used.</item>
+				  <item><c>Reason</c> is as per the <c>Reason</c> field when extended errors are not enabled.</item>
+		  </list></p>
       </desc>
     </func>
     <func>
@@ -203,7 +220,7 @@
       <fsummary>Closes a connection to a database. </fsummary>
       <type>
         <v>Ref = connection_reference()</v>
-        <v>Reason = process_not_owner_of_odbc_connection</v>
+        <v>Reason = process_not_owner_of_odbc_connection | extended_error()</v>
       </type>
       <desc>
         <p>Closes a connection to a database. This will also
-- 
cgit v1.2.3