The R13B03 release.OTP_R13B03

1 files changed, 275 insertions, 0 deletions

diff --git a/lib/odbc/doc/src/databases.xml b/lib/odbc/doc/src/databases.xml
new file mode 100644
index 0000000000..c06327e11d
--- /dev/null
+++ b/lib/odbc/doc/src/databases.xml
@@ -0,0 +1,275 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2002</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>Databases</title>
+    <prepared>Ingela Anderton</prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date></date>
+    <rev></rev>
+    <file>databases.xml</file>
+  </header>
+
+  <section>
+    <title>Databases</title>
+    <p>If you need to access a relational database such as
+      <c>sqlserver</c>, <c>mysql</c>, <c>postgres</c>, <c>oracle</c>,
+      <c>cybase</c> etc. from your erlang application using the Erlang
+      ODBC interface is a good way to go about it.</p>
+    <p></p>
+    <p>The Erlang ODBC application should work for any relational
+      database that has an ODBC driver. But currently it is only
+      regularly tested for <c>sqlserver</c> and <c>postgres</c>.</p>
+  </section>
+
+  <section>
+    <title>Database independence </title>
+    <p>The Erlang ODBC interface is in principal database
+      independent, e.i. an erlang program using the interface could be
+      run without changes towards different databases. But as SQL is
+      used it is alas possible to write database dependent
+      programs. Even though SQL is an ANSI-standard meant to be
+      database independent, different databases have proprietary
+      extensions to SQL defining their own data types. If you keep to
+      the ANSI data types you will minimize the problem. But
+      unfortunately there is no guarantee that all databases actually
+      treats the ANSI data types equivalently. For instance an
+      installation of <c>Oracle Enterprise release 8.0.5.0.0 for unix</c> will accept that you create a table column with the
+      ANSI data type <c>integer</c>, but when retrieving values from
+      this column the driver reports that it is of type
+      <c>SQL_DECIMAL(0, 38)</c> and not <c>SQL_INTEGER</c> as you may have
+      expected. </p>
+    <p>Another obstacle is that some drivers do not support scrollable
+      cursors which has the effect that the only way to traverse the
+      result set is sequentially, with next, from the first row to the
+      last, and once you pass a row you can not go back. This means
+      that some functions in the interface will not work together with
+      certain drivers. A similar problem is that not all drivers
+      support "row count" for select queries, hence resulting in that
+      the function <c>select_count/[3,4]</c> will return <c>{ok, undefined}</c> instead of <c>{ok, NrRows}</c> where
+      <c>NrRows</c> is the number of rows in the result set.</p>
+  </section>
+
+  <section>
+    <title>Data types </title>
+    <p>The following is a list of the ANSI data types. For details
+      turn to the ANSI standard documentation. Usage of other data types
+      is of course possible, but you should be aware that this makes your
+      application dependent on the database you are using at the moment.</p>
+    <list type="bulleted">
+      <item>CHARACTER (size), CHAR (size)</item>
+      <item>NUMERIC (precision, scale), DECIMAL (precision, scale), DEC
+       (precision, scale ) precision - total number of digits, scale
+       - total number of decimal places</item>
+      <item>INTEGER, INT, SMALLINT</item>
+      <item>FLOAT (precision)</item>
+      <item>REAL</item>
+      <item>DOUBLE PRECISION</item>
+      <item>CHARACTER VARYING(size), CHAR VARYING(size)</item>
+    </list>
+    <p>When inputting data using sql_query/[2,3] the values will
+      always be in string format as they are part of an SQL-query.
+      Example:</p>
+    <code type="none">
+      odbc:sql_query(Ref, "INSERT INTO TEST VALUES(1, 2, 3)").
+    </code>
+    <note>
+      <p>Note that when the value of the data to input is a string, it
+        has to be quoted with <c>'</c>. Example: </p>
+      <code type="none">
+\011odbc:sql_query(Ref, "INSERT INTO EMPLOYEE VALUES(1, 'Jane', 'Doe', 'F')").
+      </code>
+    </note>
+    <p>You may also input data using <seealso marker="odbc#param_query">param_query/[3,4]</seealso> and then
+      the input data will have the Erlang type corresponding to the
+      ODBC type of the column.<seealso marker="#type">See ODBC to Erlang mapping</seealso></p>
+    <p>      <marker id="type"></marker>
+ When selecting data from a table, all data
+      types are returned from the database to the ODBC driver as an
+      ODBC data type. The tables below shows the mapping between those
+      data types and what is returned by the Erlang API.</p>
+    <table>
+      <row>
+        <cell align="left" valign="middle">ODBC Data Type </cell>
+        <cell align="left" valign="middle">Erlang Data Type </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_CHAR(size)</cell>
+        <cell align="left" valign="middle">String </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_NUMERIC(p,s)         <br></br>
+when (p >= 0 and p &lt;= 9 and s == 0) </cell>
+        <cell align="left" valign="middle">Integer </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_NUMERIC(p,s)         <br></br>
+when (p >= 10 and p &lt;= 15 and s == 0) or (s &lt;= 15 and s > 0)</cell>
+        <cell align="left" valign="middle">Float </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_NUMERIC(p,s)        <br></br>
+when p >= 16 </cell>
+        <cell align="left" valign="middle">String </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_DECIMAL(p,s)        <br></br>
+when (p >= 0 and p &lt;= 9 and s == 0) </cell>
+        <cell align="left" valign="middle">Integer </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_DECIMAL(p,s)         <br></br>
+when (p >= 10 and p &lt;= 15 and s == 0) or (s &lt;= 15 and s > 0)</cell>
+        <cell align="left" valign="middle">Float </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_DECIMAL(p,s)        <br></br>
+when p >= 16 </cell>
+        <cell align="left" valign="middle">String </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_INTEGER </cell>
+        <cell align="left" valign="middle">Integer </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_SMALLINT </cell>
+        <cell align="left" valign="middle">Integer </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_FLOAT </cell>
+        <cell align="left" valign="middle">Float </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_REAL </cell>
+        <cell align="left" valign="middle">Float </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_DOUBLE</cell>
+        <cell align="left" valign="middle">Float</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_VARCHAR(size) </cell>
+        <cell align="left" valign="middle">String </cell>
+      </row>
+      <tcaption>Mapping of ODBC data types to the Erlang data types returned to the Erlang application.</tcaption>
+    </table>
+    <table>
+      <row>
+        <cell align="left" valign="middle">ODBC Data Type </cell>
+        <cell align="left" valign="middle">Erlang Data Type </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_TYPE_DATE </cell>
+        <cell align="left" valign="middle">String </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_TYPE_TIME </cell>
+        <cell align="left" valign="middle">String </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_TYPE_TIMESTAMP </cell>
+        <cell align="left" valign="middle">String </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_LONGVARCHAR </cell>
+        <cell align="left" valign="middle">String</cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_BINARY</cell>
+        <cell align="left" valign="middle">String </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_VARBINARY</cell>
+        <cell align="left" valign="middle">String </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_LONGVARBINARY</cell>
+        <cell align="left" valign="middle">String </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_TINYINT </cell>
+        <cell align="left" valign="middle">Integer </cell>
+      </row>
+      <row>
+        <cell align="left" valign="middle">SQL_BIT</cell>
+        <cell align="left" valign="middle">Boolean </cell>
+      </row>
+      <tcaption>Mapping of extended ODBC data types to the Erlang data types returned to the Erlang application.</tcaption>
+    </table>
+    <note>
+      <p>To find out which data types will be returned for the
+        columns in a table use the function <seealso marker="odbc#describe_table">describe_table/[2,3]</seealso></p>
+    </note>
+  </section>
+
+  <section>
+    <title>Batch handling</title>
+    <p>Grouping of SQL queries can be desirable in order to reduce
+      network traffic. Another benefit can be that the data source
+      sometimes can optimize execution of a batch of SQL queries.</p>
+    <p>Explicit batches an procedures described below will result
+      in multiple results being returned from sql_query/[2,3].
+      while with parameterized queries only one result will be returned
+      from param_query/[2,3].</p>
+
+    <section>
+      <title>Explicit batches</title>
+      <p>The most basic form of a batch is created by semicolons
+        separated SQL queries, for example:</p>
+      <code type="none">
+"SELECT * FROM FOO; SELECT * FROM BAR" or
+"INSERT INTO FOO VALUES(1,'bar'); SELECT * FROM FOO"
+      </code>
+    </section>
+
+    <section>
+      <title>Procedures </title>
+      <p>Different databases may also support creating of procedures
+        that contains more than one SQL query. For example, the
+        following SQLServer-specific statement creates a procedure that
+        returns a result set containing information about employees
+        that work at the department and and a result set listing the
+        customers of that department. </p>
+      <code type="none">
+ CREATE PROCEDURE DepartmentInfo (@DepartmentID INT) AS
+\011SELECT * FROM Employee WHERE department = @DepartmentID
+\011SELECT * FROM Customers WHERE department = @DepartmentID
+      </code>
+    </section>
+
+    <section>
+      <title>Parameterized queries</title>
+      <p>To effectively perform a batch of similar queries, you can use
+        parameterized queries. This means that you in your SQL query
+        string will mark the places that usually would contain values
+        with question marks and then provide lists of values for each
+        parameter. For instance you can use this to insert multiple
+        rows into the <c>EMPLOYEE</c> table while executing only a
+        single SQL statement, for example code see <seealso marker="getting_started#param_query">"Using the Erlang API"</seealso> section in the "Getting Started" chapter.</p>
+    </section>
+  </section>
+</chapter>
+
+