The R13B03 release.OTP_R13B03

1 files changed, 248 insertions, 0 deletions

diff --git a/lib/odbc/doc/src/getting_started.xml b/lib/odbc/doc/src/getting_started.xml
new file mode 100644
index 0000000000..864c3a7b65
--- /dev/null
+++ b/lib/odbc/doc/src/getting_started.xml
@@ -0,0 +1,248 @@
+<?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>Getting started</title>
+    <prepared>Ingela Anderton Andin</prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date></date>
+    <rev></rev>
+    <file>getting_started.xml</file>
+  </header>
+
+  <section>
+    <title>Setting things up </title>
+    <p>As the Erlang ODBC application is dependent on third party
+      products there are a few administrative things that needs to be
+      done before you can get things up and running.</p>
+    <p></p>
+    <list type="bulleted">
+      <item>The first thing you need to do, is to make sure you
+       have an ODBC driver installed for the database that you
+       want to access. Both the client machine where you plan to
+       run your erlang node and the server machine running the
+       database needs the the ODBC driver. (In some cases the
+       client and the server may be the same machine).</item>
+      <item>Secondly you might need to set environment variables
+       and paths to appropriate values. This may differ a lot
+       between different os's, databases and ODBC drivers. This
+       is a configuration problem related to the third party product
+       and hence we can not give you a standard solution in this guide.</item>
+      <item>The Erlang ODBC application consists of both <c>Erlang</c>
+       and <c>C</c> code. The <c>C</c> code is delivered as a
+       precompiled executable for windows, solaris and linux (SLES10) in the commercial
+       build. In the open source distribution it is built the
+       same way as all other application using configure and make.
+       You may want to provide the the path to your ODBC libraries
+       using --with-odbc=PATH.  </item>
+    </list>
+    <note>
+      <p>The Erlang ODBC application should run on all Unix
+        dialects including Linux, Windows 2000, Windows XP and
+        NT. But currently it is only tested for Solaris, Windows
+        2000, Windows XP and NT.</p>
+    </note>
+  </section>
+
+  <section>
+    <title>Using the Erlang API</title>
+    <p>The following dialog within the Erlang shell illustrates the
+      functionality of the Erlang ODBC interface. The table used in
+      the example does not have any relevance to anything that exist
+      in reality, it is just a simple example. The example was created
+      using <c>sqlserver 7.0 with servicepack 1</c> as database and
+      the ODBC driver for <c>sqlserver</c> with version
+      <c>2000.80.194.00</c>.</p>
+    <code type="none">
+ 1 > odbc:start().
+      ok    </code>
+    <p>Connect to the database </p>
+    <code type="none"><![CDATA[
+ 2 > {ok, Ref} = odbc:connect("DSN=sql-server;UID=aladdin;PWD=sesame", []).
+      {ok,<0.342.0>}    ]]></code>
+    <p>Create a table </p>
+    <code type="none">
+ 3 > odbc:sql_query(Ref, "CREATE TABLE EMPLOYEE (NR integer,
+      FIRSTNAME  char varying(20), LASTNAME  char varying(20), GENDER char(1),
+      PRIMARY KEY(NR))").
+      {updated,undefined}    </code>
+    <p>Insert some data </p>
+    <code type="none">
+ 4 > odbc:sql_query(Ref, "INSERT INTO EMPLOYEE VALUES(1, 'Jane', 'Doe', 'F')").
+      {updated,1}    </code>
+    <p>Check what data types the database assigned for the columns.
+      Hopefully this is not a surprise, some times it can be! These
+      are the data types that you should use if you want to do a
+      parameterized query.</p>
+    <code type="none">
+ 5 > odbc:describe_table(Ref, "EMPLOYEE").
+      {ok, [{"NR", sql_integer},
+            {"FIRSTNAME", {sql_varchar, 20}},
+            {"LASTNAME", {sql_varchar, 20}}
+            {"GENDER", {sql_char, 1}}]}
+    </code>
+    <p>      <marker id="param_query"></marker>
+ Use a parameterized query
+      to insert many rows in one go. </p>
+    <code type="none">
+ 6 > odbc:param_query(Ref,"INSERT INTO EMPLOYEE (NR, FIRSTNAME, "
+\011                  "LASTNAME, GENDER) VALUES(?, ?, ?, ?)",
+\011                   [{sql_integer,[2,3,4,5,6,7,8]},
+\011                    {{sql_varchar, 20},
+                             ["John", "Monica", "Ross", "Rachel",
+                             "Piper", "Prue", "Louise"]},
+\011                   {{sql_varchar, 20},
+                             ["Doe","Geller","Geller", "Green",
+                              "Halliwell", "Halliwell", "Lane"]},
+\011                   {{sql_char, 1}, ["M","F","M","F","F","F","F"]}]).
+      {updated, 7}
+    </code>
+    <p>Fetch all data in the table employee </p>
+    <code type="none">
+ 7> odbc:sql_query(Ref, "SELECT * FROM EMPLOYEE").
+    {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],
+          [{1,"Jane","Doe","F"},
+           {2,"John","Doe","M"},
+           {3,"Monica","Geller","F"},
+           {4,"Ross","Geller","M"},
+           {5,"Rachel","Green","F"},
+           {6,"Piper","Halliwell","F"},
+           {7,"Prue","Halliwell","F"},
+           {8,"Louise","Lane","F"}]]}     </code>
+    <p>Associate a result set containing the whole table
+      <c>EMPLOYEE</c> to the connection. The number of rows in the
+      result set is returned.</p>
+    <code type="none">
+ 8 > odbc:select_count(Ref, "SELECT * FROM EMPLOYEE").
+      {ok,8}     </code>
+    <p>You can always traverse the result set sequential by using next</p>
+    <code type="none">
+ 9 > odbc:next(Ref).
+      {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],[{1,"Jane","Doe","F"}]}
+    </code>
+    <code type="none">
+ 10 > odbc:next(Ref).
+      {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],[{2,"John","Doe","M"}]}
+    </code>
+    <p>If your driver supports scrollable cursors you have a little
+      more freedom, and can do things like this. </p>
+    <code type="none">
+ 11 > odbc:last(Ref).
+      {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],[{8,"Louise","Lane","F"}]}    </code>
+    <code type="none">
+ 12 > odbc:prev(Ref).
+      {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],[{7,"Prue","Halliwell","F"}]}    </code>
+    <code type="none">
+ 13 > odbc:first(Ref).
+      {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],[{1,"Jane","Doe","F"}]}        </code>
+    <code type="none">
+ 14 > odbc:next(Ref).
+      {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],[{2,"John","Doe","M"}]}
+    </code>
+    <p>Fetch the fields <c>FIRSTNAME </c> and <c>NR </c> for all female
+      employees</p>
+    <code type="none">
+ 15 > odbc:sql_query(Ref, "SELECT FIRSTNAME, NR FROM EMPLOYEE WHERE GENDER = 'F'").
+     {selected,["FIRSTNAME","NR"],
+          [{"Jane",1},
+           {"Monica",3},
+           {"Rachel",5},
+           {"Piper",6},
+           {"Prue",7},
+           {"Louise",8}]}     </code>
+    <p>Fetch the fields <c>FIRSTNAME </c> and <c>NR </c> for all female
+      employees and sort them on the field <c>FIRSTNAME </c>. </p>
+    <code type="none">
+ 16 > odbc:sql_query(Ref, "SELECT FIRSTNAME, NR FROM EMPLOYEE WHERE GENDER = 'F'
+      ORDER BY FIRSTNAME").
+    {selected,["FIRSTNAME","NR"],
+          [{"Jane",1},
+           {"Louise",8},
+           {"Monica",3},
+           {"Piper",6},
+           {"Prue",7},
+           {"Rachel",5}]}
+    </code>
+    <p>Associate a result set that contains the fields <c>FIRSTNAME</c> and <c>NR </c> for all female employees to the
+      connection. The number of rows in the result set is
+      returned.</p>
+    <code type="none">
+ 17 > odbc:select_count(Ref, "SELECT FIRSTNAME, NR FROM EMPLOYEE WHERE GENDER = 'F'").
+      {ok,6}    </code>
+    <p>A few more ways of retrieving parts of the result set when the
+      driver supports scrollable cursors. Note that next will work even
+      without support for scrollable cursors. </p>
+    <code type="none">
+ 18 > odbc:select(Ref, {relative, 2}, 3).
+    {selected,["FIRSTNAME","NR"],[{"Monica",3},{"Rachel",5},{"Piper",6}]}
+    </code>
+    <code type="none">
+ 19 > odbc:select(Ref, next, 2).
+      {selected,["FIRSTNAME","NR"],[{"Prue",7},{"Louise",8}]}
+    </code>
+    <code type="none">
+ 20 > odbc:select(Ref, {absolute, 1}, 2).
+      {selected,["FIRSTNAME","NR"],[{"Jane",1},{"Monica",3}]}
+    </code>
+    <code type="none">
+ 21 > odbc:select(Ref, next, 2).
+    {selected,["FIRSTNAME","NR"],[{"Rachel",5},{"Piper",6}]}
+    </code>
+    <code type="none">
+ 22 > odbc:select(Ref, {absolute, 1}, 4). 
+      {selected,["FIRSTNAME","NR"],
+                [{"Jane",1},{"Monica",3},{"Rachel",5},{"Piper",6}]}
+    </code>
+    <p>Select, using a parameterized query. </p>
+    <code type="none">
+ 23 > odbc:param_query(Ref, "SELECT * FROM EMPLOYEE WHERE GENDER=?",
+      [{{sql_char, 1}, ["M"]}]).
+      {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],
+                [{2,"John", "Doe", "M"},{4,"Ross","Geller","M"}]} 
+    </code>
+    <p>Delete the table <c>EMPLOYEE</c>.</p>
+    <code type="none">
+ 24 > odbc:sql_query(Ref, "DROP TABLE EMPLOYEE").
+      {updated,undefined}
+    </code>
+    <p>Shut down the connection. </p>
+    <code type="none">
+ 25 > odbc:disconnect(Ref).
+      ok
+    </code>
+    <p>Shut down the application. </p>
+    <code type="none">
+ 26 > odbc:stop().
+    =INFO REPORT==== 7-Jan-2004::17:00:59 ===
+    application: odbc
+    exited: stopped
+    type: temporary
+
+    ok
+    </code>
+  </section>
+</chapter>
+
+