summaryrefslogtreecommitdiff
path: root/lib/odbc/doc/src/getting_started.xml
blob: 864c3a7b658fae4d940536178357a21eecab9828 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
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>