← Back to branch summary

~statik/ubuntu/maverick/erlang/erlang-merge-testing

« back to all changes in this revision

Viewing changes to lib/odbc/doc/src/getting_started.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2009-05-01 10:14:38 UTC
  • mfrom: (3.1.4 sid)
  • Revision ID: james.westby@ubuntu.com-20090501101438-6qlr6rsdxgyzrg2z
Tags: 1:13.b-dfsg-2
* Cleaned up patches: removed unneeded patch which helped to support
  different SCTP library versions, made sure that changes for m68k
  architecture applied only when building on this architecture.
* Removed duplicated information from binary packages descriptions.
* Don't require libsctp-dev build-dependency on solaris-i386 architecture
  which allows to build Erlang on Nexenta (thanks to Tim Spriggs for
  the suggestion).

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/odbc/doc/src/getting_started.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>2002</year><year>2009</year>
 
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
 
9
    </copyright>
 
10
    <legalnotice>
 
11
      The contents of this file are subject to the Erlang Public License,
 
12
      Version 1.1, (the "License"); you may not use this file except in
 
13
      compliance with the License. You should have received a copy of the
 
14
      Erlang Public License along with this software. If not, it can be
 
15
      retrieved online at http://www.erlang.org/.
 
16
    
 
17
      Software distributed under the License is distributed on an "AS IS"
 
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
19
      the License for the specific language governing rights and limitations
 
20
      under the License.
 
21
    
 
22
    </legalnotice>
 
23
 
 
24
    <title>Getting started</title>
 
25
    <prepared>Ingela Anderton Andin</prepared>
 
26
    <responsible></responsible>
 
27
    <docno></docno>
 
28
    <approved></approved>
 
29
    <checked></checked>
 
30
    <date></date>
 
31
    <rev></rev>
 
32
    <file></file>
 
33
  </header>
 
34
 
 
35
  <section>
 
36
    <title>Setting things up </title>
 
37
    <p>As the Erlang ODBC application is dependent on third party
 
38
      products there are a few administrative things that needs to be
 
39
      done before you can get things up and running.</p>
 
40
    <p></p>
 
41
    <list type="bulleted">
 
42
      <item>The first thing you need to do, is to make sure you
 
43
       have an ODBC driver installed for the database that you
 
44
       want to access. Both the client machine where you plan to
 
45
       run your erlang node and the server machine running the
 
46
       database needs the the ODBC driver. (In some cases the
 
47
       client and the server may be the same machine).</item>
 
48
      <item>Secondly you might need to set environment variables
 
49
       and paths to appropriate values. This may differ a lot
 
50
       between different os's, databases and ODBC drivers. This
 
51
       is a configuration problem related to the third party product
 
52
       and hence we can not give you a standard solution in this guide.</item>
 
53
      <item>The Erlang ODBC application consists of both <c>Erlang</c>
 
54
       and <c>C</c> code. The <c>C</c> code is delivered as a
 
55
       precompiled executable for windows, solaris and linux (SLES10) in the commercial
 
56
       build. In the open source distribution it is built the
 
57
       same way as all other application using configure and make.
 
58
       You may want to provide the the path to your ODBC libraries
 
59
       using --with-odbc=PATH.  </item>
 
60
    </list>
 
61
    <note>
 
62
      <p>The Erlang ODBC application should run on all Unix
 
63
        dialects including Linux, Windows 2000, Windows XP and
 
64
        NT. But currently it is only tested for Solaris, Windows
 
65
        2000, Windows XP and NT.</p>
 
66
    </note>
 
67
  </section>
 
68
 
 
69
  <section>
 
70
    <title>Using the Erlang API</title>
 
71
    <p>The following dialog within the Erlang shell illustrates the
 
72
      functionality of the Erlang ODBC interface. The table used in
 
73
      the example does not have any relevance to anything that exist
 
74
      in reality, it is just a simple example. The example was created
 
75
      using <c>sqlserver 7.0 with servicepack 1</c> as database and
 
76
      the ODBC driver for <c>sqlserver</c> with version
 
77
      <c>2000.80.194.00</c>.</p>
 
78
    <code type="none">
 
79
 1 > odbc:start().
 
80
      ok    </code>
 
81
    <p>Connect to the database </p>
 
82
    <code type="none"><![CDATA[
 
83
 2 > {ok, Ref} = odbc:connect("DSN=sql-server;UID=aladin;PWD=sesame", []).
 
84
      {ok,<0.342.0>}    ]]></code>
 
85
    <p>Create a table </p>
 
86
    <code type="none">
 
87
 3 > odbc:sql_query(Ref, "CREATE TABLE EMPLOYEE (NR integer,
 
88
      FIRSTNAME  char varying(20), LASTNAME  char varying(20), GENDER char(1),
 
89
      PRIMARY KEY(NR))").
 
90
      {updated,undefined}    </code>
 
91
    <p>Insert some data </p>
 
92
    <code type="none">
 
93
 4 > odbc:sql_query(Ref, "INSERT INTO EMPLOYEE VALUES(1, 'Jane', 'Doe', 'F')").
 
94
      {updated,1}    </code>
 
95
    <p>Check what data types the database assigned for the columns.
 
96
      Hopefully this is not a surprise, some times it can be! These
 
97
      are the data types that you should use if you want to do a
 
98
      parameterized query.</p>
 
99
    <code type="none">
 
100
 5 > odbc:describe_table(Ref, "EMPLOYEE").
 
101
      {ok, [{"NR", sql_integer},
 
102
            {"FIRSTNAME", {sql_varchar, 20}},
 
103
            {"LASTNAME", {sql_varchar, 20}}
 
104
            {"GENDER", {sql_char, 1}}]}
 
105
    </code>
 
106
    <p>      <marker id="param_query"></marker>
 
107
 Use a parameterized query
 
108
      to insert many rows in one go. </p>
 
109
    <code type="none">
 
110
 6 > odbc:param_query(Ref,"INSERT INTO EMPLOYEE (NR, FIRSTNAME, "
 
111
\011                  "LASTNAME, GENDER) VALUES(?, ?, ?, ?)",
 
112
\011                   [{sql_integer,[2,3,4,5,6,7,8]},
 
113
\011                    {{sql_varchar, 20},
 
114
                             ["John", "Monica", "Ross", "Rachel",
 
115
                             "Piper", "Prue", "Louise"]},
 
116
\011                   {{sql_varchar, 20},
 
117
                             ["Doe","Geller","Geller", "Green",
 
118
                              "Halliwell", "Halliwell", "Lane"]},
 
119
\011                   {{sql_char, 1}, ["M","F","M","F","F","F","F"]}]).
 
120
      {updated, 7}
 
121
    </code>
 
122
    <p>Fetch all data in the table employee </p>
 
123
    <code type="none">
 
124
 7> odbc:sql_query(Ref, "SELECT * FROM EMPLOYEE").
 
125
    {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],
 
126
          [{1,"Jane","Doe","F"},
 
127
           {2,"John","Doe","M"},
 
128
           {3,"Monica","Geller","F"},
 
129
           {4,"Ross","Geller","M"},
 
130
           {5,"Rachel","Green","F"},
 
131
           {6,"Piper","Halliwell","F"},
 
132
           {7,"Prue","Halliwell","F"},
 
133
           {8,"Louise","Lane","F"}]]}     </code>
 
134
    <p>Associate a result set containg the whole table
 
135
      <c>EMPLOYEE</c> to the connection. The number of rows in the
 
136
      result set is returned.</p>
 
137
    <code type="none">
 
138
 8 > odbc:select_count(Ref, "SELECT * FROM EMPLOYEE").
 
139
      {ok,8}     </code>
 
140
    <p>You can always traverse the result set sequential by using next</p>
 
141
    <code type="none">
 
142
 9 > odbc:next(Ref).
 
143
      {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],[{1,"Jane","Doe","F"}]}
 
144
    </code>
 
145
    <code type="none">
 
146
 10 > odbc:next(Ref).
 
147
      {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],[{2,"John","Doe","M"}]}
 
148
    </code>
 
149
    <p>If your driver supports scrollable cursors you have a little
 
150
      more freedom, and can do thigs like this. </p>
 
151
    <code type="none">
 
152
 11 > odbc:last(Ref).
 
153
      {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],[{8,"Louise","Lane","F"}]}    </code>
 
154
    <code type="none">
 
155
 12 > odbc:prev(Ref).
 
156
      {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],[{7,"Prue","Halliwell","F"}]}    </code>
 
157
    <code type="none">
 
158
 13 > odbc:first(Ref).
 
159
      {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],[{1,"Jane","Doe","F"}]}        </code>
 
160
    <code type="none">
 
161
 14 > odbc:next(Ref).
 
162
      {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],[{2,"John","Doe","M"}]}
 
163
    </code>
 
164
    <p>Fetch the fields <c>FIRSTNAME </c> and <c>NR </c> for all female
 
165
      employees</p>
 
166
    <code type="none">
 
167
 15 > odbc:sql_query(Ref, "SELECT FIRSTNAME, NR FROM EMPLOYEE WHERE GENDER = 'F'").
 
168
     {selected,["FIRSTNAME","NR"],
 
169
          [{"Jane",1},
 
170
           {"Monica",3},
 
171
           {"Rachel",5},
 
172
           {"Piper",6},
 
173
           {"Prue",7},
 
174
           {"Louise",8}]}     </code>
 
175
    <p>Fetch the fields <c>FIRSTNAME </c> and <c>NR </c> for all female
 
176
      employees and sort them on the field <c>FIRSTNAME </c>. </p>
 
177
    <code type="none">
 
178
 16 > odbc:sql_query(Ref, "SELECT FIRSTNAME, NR FROM EMPLOYEE WHERE GENDER = 'F'
 
179
      ORDER BY FIRSTNAME").
 
180
    {selected,["FIRSTNAME","NR"],
 
181
          [{"Jane",1},
 
182
           {"Louise",8},
 
183
           {"Monica",3},
 
184
           {"Piper",6},
 
185
           {"Prue",7},
 
186
           {"Rachel",5}]}
 
187
    </code>
 
188
    <p>Associate a result set that contains the fields <c>FIRSTNAME</c> and <c>NR </c> for all female employees to the
 
189
      connection. The number of rows in the result set is
 
190
      returned.</p>
 
191
    <code type="none">
 
192
 17 > odbc:select_count(Ref, "SELECT FIRSTNAME, NR FROM EMPLOYEE WHERE GENDER = 'F'").
 
193
      {ok,6}    </code>
 
194
    <p>A few more ways of retriving parts of the result set when the
 
195
      driver supports scrollable cursors. Note that next will work even
 
196
      without support for scrollable cursors. </p>
 
197
    <code type="none">
 
198
 18 > odbc:select(Ref, {relative, 2}, 3).
 
199
    {selected,["FIRSTNAME","NR"],[{"Monica",3},{"Rachel",5},{"Piper",6}]}
 
200
    </code>
 
201
    <code type="none">
 
202
 19 > odbc:select(Ref, next, 2).
 
203
      {selected,["FIRSTNAME","NR"],[{"Prue",7},{"Louise",8}]}
 
204
    </code>
 
205
    <code type="none">
 
206
 20 > odbc:select(Ref, {absolute, 1}, 2).
 
207
      {selected,["FIRSTNAME","NR"],[{"Jane",1},{"Monica",3}]}
 
208
    </code>
 
209
    <code type="none">
 
210
 21 > odbc:select(Ref, next, 2).
 
211
    {selected,["FIRSTNAME","NR"],[{"Rachel",5},{"Piper",6}]}
 
212
    </code>
 
213
    <code type="none">
 
214
 22 > odbc:select(Ref, {absolute, 1}, 4). 
 
215
      {selected,["FIRSTNAME","NR"],
 
216
                [{"Jane",1},{"Monica",3},{"Rachel",5},{"Piper",6}]}
 
217
    </code>
 
218
    <p>Select, using a parameterized query. </p>
 
219
    <code type="none">
 
220
 23 > odbc:param_query(Ref, "SELECT * FROM EMPLOYEE WHERE GENDER=?",
 
221
      [{{sql_char, 1}, ["M"]}]).
 
222
      {selected,["NR","FIRSTNAME","LASTNAME","GENDER"],
 
223
                [{2,"John", "Doe", "M"},{4,"Ross","Geller","M"}]} 
 
224
    </code>
 
225
    <p>Delete the table <c>EMPLOYEE</c>.</p>
 
226
    <code type="none">
 
227
 24 > odbc:sql_query(Ref, "DROP TABLE EMPLOYEE").
 
228
      {updated,undefined}
 
229
    </code>
 
230
    <p>Shut down the connection. </p>
 
231
    <code type="none">
 
232
 25 > odbc:disconnect(Ref).
 
233
      ok
 
234
    </code>
 
235
    <p>Shut down the application. </p>
 
236
    <code type="none">
 
237
 26 > odbc:stop().
 
238
    =INFO REPORT==== 7-Jan-2004::17:00:59 ===
 
239
    application: odbc
 
240
    exited: stopped
 
241
    type: temporary
 
242
 
 
243
    ok
 
244
    </code>
 
245
  </section>
 
246
</chapter>
 
247
 
 
248