diff options
Diffstat (limited to 'lib/odbc/doc/src/getting_started.xml')
| -rw-r--r-- | lib/odbc/doc/src/getting_started.xml | 248 |
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> + + |