aboutsummaryrefslogtreecommitdiffstats
path: root/lib/odbc/doc/src/getting_started.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/odbc/doc/src/getting_started.xml')
-rw-r--r--lib/odbc/doc/src/getting_started.xml248
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>
+
+