/
getting-started.html
395 lines (354 loc) · 29 KB
/
getting-started.html
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
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Getting Started with FDB — FDB 1.4.10 documentation</title>
<link rel="stylesheet" href="_static/fdbtheme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '1.4.10',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="FDB 1.4.10 documentation" href="index.html" />
<link rel="next" title="Usage Guide" href="usage-guide.html" />
<link rel="prev" title="Welcome to FDB’s documentation!" href="index.html" />
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton&subset=latin" type="text/css" media="screen" charset="utf-8" />
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Nobile:regular,italic,bold,bolditalic&subset=latin" type="text/css" media="screen" charset="utf-8" />
<!--[if lte IE 6]>
<link rel="stylesheet" href="_static/ie6.css" type="text/css" media="screen" charset="utf-8" />
<![endif]-->
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="usage-guide.html" title="Usage Guide"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="Welcome to FDB’s documentation!"
accesskey="P">previous</a> |</li>
<li><a href="index.html">FDB 1.4.10 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="getting-started-with-fdb">
<h1>Getting Started with FDB<a class="headerlink" href="#getting-started-with-fdb" title="Permalink to this headline">¶</a></h1>
<div class="section" id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2>
<p>FDB is written as pure-Python module on top of Firebird client library (fbclient.so/dll) using <a class="reference external" href="http://docs.python.org/library/ctypes.html">ctypes</a>,
so <em>make sure you have Firebird client properly installed before you try to install FDB</em>, otherwise the
installation will fail. FDB supports Firebird version 2.0 and higher.</p>
<p>FDB is distributed as <a class="reference external" href="https://bitbucket.org/pypa/setuptools">setuptools</a> package, so you’ll need setuptools or
<a class="reference external" href="http://pypi.python.org/pypi/distribute">compatible package</a> installed to
install FDB properly.</p>
<div class="section" id="installation-from-pypi">
<h3>Installation from <a class="reference external" href="http://pypi.python.org">PYPI</a><a class="headerlink" href="#installation-from-pypi" title="Permalink to this headline">¶</a></h3>
<p>Run easy_install or pip:</p>
<div class="highlight-python"><div class="highlight"><pre>$ pip install fdb
</pre></div>
</div>
<p>or:</p>
<div class="highlight-python"><div class="highlight"><pre>$ easy_install fdb
</pre></div>
</div>
</div>
<div class="section" id="installation-from-source">
<h3>Installation from source<a class="headerlink" href="#installation-from-source" title="Permalink to this headline">¶</a></h3>
<p>Download the source tarball, uncompress it, then run the install command:</p>
<div class="highlight-python"><div class="highlight"><pre>$ curl -O http://pypi.python.org/packages/source/f/fdb/fdb-1.2.tar.gz
$ tar -xzvf fdb-1.2.tar.gz
$ cd fdb-1.2
$ python setup.py install
</pre></div>
</div>
</div>
</div>
<div class="section" id="quick-start-guide">
<h2>Quick-start Guide<a class="headerlink" href="#quick-start-guide" title="Permalink to this headline">¶</a></h2>
<p>This brief tutorial aims to get the reader started by demonstrating
elementary usage of FDB. It is not a comprehensive Python
Database API tutorial, nor is it comprehensive in its coverage of
anything else.</p>
<p>The numerous advanced features of FDB are covered in another
section of this documentation, which is not in a tutorial format, though it
is replete with examples.</p>
<div class="section" id="connecting-to-a-database">
<h3>Connecting to a Database<a class="headerlink" href="#connecting-to-a-database" title="Permalink to this headline">¶</a></h3>
<p><strong>Example 1</strong></p>
<p>A database connection is typically established with code such as this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">fdb</span>
<span class="c"># The server is named 'bison'; the database file is at '/temp/test.db'.</span>
<span class="n">con</span> <span class="o">=</span> <span class="n">fdb</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">dsn</span><span class="o">=</span><span class="s">'bison:/temp/test.db'</span><span class="p">,</span> <span class="n">user</span><span class="o">=</span><span class="s">'sysdba'</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s">'pass'</span><span class="p">)</span>
<span class="c"># Or, equivalently:</span>
<span class="n">con</span> <span class="o">=</span> <span class="n">fdb</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span>
<span class="n">host</span><span class="o">=</span><span class="s">'bison'</span><span class="p">,</span> <span class="n">database</span><span class="o">=</span><span class="s">'/temp/test.db'</span><span class="p">,</span>
<span class="n">user</span><span class="o">=</span><span class="s">'sysdba'</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s">'pass'</span>
<span class="p">)</span>
</pre></div>
</div>
<p><strong>Example 2</strong></p>
<p>Suppose we want to connect to the database in SQL Dialect 1 and specifying
UTF-8 as the character set of the connection:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">fdb</span>
<span class="n">con</span> <span class="o">=</span> <span class="n">fdb</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span>
<span class="n">dsn</span><span class="o">=</span><span class="s">'bison:/temp/test.db'</span><span class="p">,</span>
<span class="n">user</span><span class="o">=</span><span class="s">'sysdba'</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s">'pass'</span><span class="p">,</span>
<span class="n">dialect</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="c"># necessary for all dialect 1 databases</span>
<span class="n">charset</span><span class="o">=</span><span class="s">'UTF8'</span> <span class="c"># specify a character set for the connection</span>
<span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="executing-sql-statements">
<h3>Executing SQL Statements<a class="headerlink" href="#executing-sql-statements" title="Permalink to this headline">¶</a></h3>
<p>For this section, suppose we have a table defined and populated by the
following SQL code:</p>
<div class="highlight-sql"><div class="highlight"><pre><span class="k">create</span> <span class="k">table</span> <span class="n">languages</span>
<span class="p">(</span>
<span class="n">name</span> <span class="nb">varchar</span><span class="p">(</span><span class="mi">20</span><span class="p">),</span>
<span class="n">year_released</span> <span class="nb">integer</span>
<span class="p">);</span>
<span class="k">insert</span> <span class="k">into</span> <span class="n">languages</span> <span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">year_released</span><span class="p">)</span> <span class="k">values</span> <span class="p">(</span><span class="s1">'C'</span><span class="p">,</span> <span class="mi">1972</span><span class="p">);</span>
<span class="k">insert</span> <span class="k">into</span> <span class="n">languages</span> <span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">year_released</span><span class="p">)</span> <span class="k">values</span> <span class="p">(</span><span class="s1">'Python'</span><span class="p">,</span> <span class="mi">1991</span><span class="p">);</span>
</pre></div>
</div>
<p><strong>Example 1</strong></p>
<p>This example shows the <em>simplest</em> way to print the entire contents of
the <cite>languages</cite> table:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">fdb</span>
<span class="n">con</span> <span class="o">=</span> <span class="n">fdb</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">dsn</span><span class="o">=</span><span class="s">'/temp/test.db'</span><span class="p">,</span> <span class="n">user</span><span class="o">=</span><span class="s">'sysdba'</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s">'masterkey'</span><span class="p">)</span>
<span class="c"># Create a Cursor object that operates in the context of Connection con:</span>
<span class="n">cur</span> <span class="o">=</span> <span class="n">con</span><span class="o">.</span><span class="n">cursor</span><span class="p">()</span>
<span class="c"># Execute the SELECT statement:</span>
<span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">"select * from languages order by year_released"</span><span class="p">)</span>
<span class="c"># Retrieve all rows as a sequence and print that sequence:</span>
<span class="k">print</span> <span class="n">cur</span><span class="o">.</span><span class="n">fetchall</span><span class="p">()</span>
</pre></div>
</div>
<p>Sample output:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">[(</span><span class="s">'C'</span><span class="p">,</span> <span class="mi">1972</span><span class="p">),</span> <span class="p">(</span><span class="s">'Python'</span><span class="p">,</span> <span class="mi">1991</span><span class="p">)]</span>
</pre></div>
</div>
<p><strong>Example 2</strong></p>
<p>Here’s another trivial example that demonstrates various ways of
fetching a single row at a time from a <cite>SELECT</cite>-cursor:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">fdb</span>
<span class="n">con</span> <span class="o">=</span> <span class="n">fdb</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">dsn</span><span class="o">=</span><span class="s">'/temp/test.db'</span><span class="p">,</span> <span class="n">user</span><span class="o">=</span><span class="s">'sysdba'</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s">'masterkey'</span><span class="p">)</span>
<span class="n">cur</span> <span class="o">=</span> <span class="n">con</span><span class="o">.</span><span class="n">cursor</span><span class="p">()</span>
<span class="n">SELECT</span> <span class="o">=</span> <span class="s">"select name, year_released from languages order by year_released"</span>
<span class="c"># 1. Iterate over the rows available from the cursor, unpacking the</span>
<span class="c"># resulting sequences to yield their elements (name, year_released):</span>
<span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">SELECT</span><span class="p">)</span>
<span class="k">for</span> <span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">year_released</span><span class="p">)</span> <span class="ow">in</span> <span class="n">cur</span><span class="p">:</span>
<span class="k">print</span> <span class="s">'</span><span class="si">%s</span><span class="s"> has been publicly available since </span><span class="si">%d</span><span class="s">.'</span> <span class="o">%</span> <span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">year_released</span><span class="p">)</span>
<span class="c"># 2. Equivalently:</span>
<span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">SELECT</span><span class="p">)</span>
<span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">cur</span><span class="p">:</span>
<span class="k">print</span> <span class="s">'</span><span class="si">%s</span><span class="s"> has been publicly available since </span><span class="si">%d</span><span class="s">.'</span> <span class="o">%</span> <span class="p">(</span><span class="n">row</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">row</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span>
<span class="c"># 3. Using mapping-iteration rather than sequence-iteration:</span>
<span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">SELECT</span><span class="p">)</span>
<span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">cur</span><span class="o">.</span><span class="n">itermap</span><span class="p">():</span>
<span class="k">print</span> <span class="s">'</span><span class="si">%(name)s</span><span class="s"> has been publicly available since </span><span class="si">%(year_released)d</span><span class="s">.'</span> <span class="o">%</span> <span class="n">row</span>
</pre></div>
</div>
<p>Sample output:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">C</span> <span class="n">has</span> <span class="n">been</span> <span class="n">publicly</span> <span class="n">available</span> <span class="n">since</span> <span class="mf">1972.</span>
<span class="n">Python</span> <span class="n">has</span> <span class="n">been</span> <span class="n">publicly</span> <span class="n">available</span> <span class="n">since</span> <span class="mf">1991.</span>
<span class="n">C</span> <span class="n">has</span> <span class="n">been</span> <span class="n">publicly</span> <span class="n">available</span> <span class="n">since</span> <span class="mf">1972.</span>
<span class="n">Python</span> <span class="n">has</span> <span class="n">been</span> <span class="n">publicly</span> <span class="n">available</span> <span class="n">since</span> <span class="mf">1991.</span>
<span class="n">C</span> <span class="n">has</span> <span class="n">been</span> <span class="n">publicly</span> <span class="n">available</span> <span class="n">since</span> <span class="mf">1972.</span>
<span class="n">Python</span> <span class="n">has</span> <span class="n">been</span> <span class="n">publicly</span> <span class="n">available</span> <span class="n">since</span> <span class="mf">1991.</span>
</pre></div>
</div>
<p><strong>Example 3</strong></p>
<p>The following program is a simplistic table printer (applied in this
example to <cite>languages</cite>):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">fdb</span>
<span class="n">TABLE_NAME</span> <span class="o">=</span> <span class="s">'languages'</span>
<span class="n">SELECT</span> <span class="o">=</span> <span class="s">'select * from </span><span class="si">%s</span><span class="s"> order by year_released'</span> <span class="o">%</span> <span class="n">TABLE_NAME</span>
<span class="n">con</span> <span class="o">=</span> <span class="n">fdb</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">dsn</span><span class="o">=</span><span class="s">'/temp/test.db'</span><span class="p">,</span> <span class="n">user</span><span class="o">=</span><span class="s">'sysdba'</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s">'masterkey'</span><span class="p">)</span>
<span class="n">cur</span> <span class="o">=</span> <span class="n">con</span><span class="o">.</span><span class="n">cursor</span><span class="p">()</span>
<span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">SELECT</span><span class="p">)</span>
<span class="c"># Print a header.</span>
<span class="k">for</span> <span class="n">fieldDesc</span> <span class="ow">in</span> <span class="n">cur</span><span class="o">.</span><span class="n">description</span><span class="p">:</span>
<span class="k">print</span> <span class="n">fieldDesc</span><span class="p">[</span><span class="n">fdb</span><span class="o">.</span><span class="n">DESCRIPTION_NAME</span><span class="p">]</span><span class="o">.</span><span class="n">ljust</span><span class="p">(</span><span class="n">fieldDesc</span><span class="p">[</span><span class="n">fdb</span><span class="o">.</span><span class="n">DESCRIPTION_DISPLAY_SIZE</span><span class="p">])</span> <span class="p">,</span>
<span class="k">print</span> <span class="c"># Finish the header with a newline.</span>
<span class="k">print</span> <span class="s">'-'</span> <span class="o">*</span> <span class="mi">78</span>
<span class="c"># For each row, print the value of each field left-justified within</span>
<span class="c"># the maximum possible width of that field.</span>
<span class="n">fieldIndices</span> <span class="o">=</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">cur</span><span class="o">.</span><span class="n">description</span><span class="p">))</span>
<span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">cur</span><span class="p">:</span>
<span class="k">for</span> <span class="n">fieldIndex</span> <span class="ow">in</span> <span class="n">fieldIndices</span><span class="p">:</span>
<span class="n">fieldValue</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">row</span><span class="p">[</span><span class="n">fieldIndex</span><span class="p">])</span>
<span class="n">fieldMaxWidth</span> <span class="o">=</span> <span class="n">cur</span><span class="o">.</span><span class="n">description</span><span class="p">[</span><span class="n">fieldIndex</span><span class="p">][</span><span class="n">fdb</span><span class="o">.</span><span class="n">DESCRIPTION_DISPLAY_SIZE</span><span class="p">]</span>
<span class="k">print</span> <span class="n">fieldValue</span><span class="o">.</span><span class="n">ljust</span><span class="p">(</span><span class="n">fieldMaxWidth</span><span class="p">)</span> <span class="p">,</span>
<span class="k">print</span> <span class="c"># Finish the row with a newline.</span>
</pre></div>
</div>
<p>Sample output:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">NAME</span> <span class="n">YEAR_RELEASED</span>
<span class="o">------------------------------------------------------------------------------</span>
<span class="n">C</span> <span class="mi">1972</span>
<span class="n">Python</span> <span class="mi">1991</span>
</pre></div>
</div>
<p><strong>Example 4</strong></p>
<p>Let’s insert more languages:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">fdb</span>
<span class="n">con</span> <span class="o">=</span> <span class="n">fdb</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">dsn</span><span class="o">=</span><span class="s">'/temp/test.db'</span><span class="p">,</span> <span class="n">user</span><span class="o">=</span><span class="s">'sysdba'</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s">'masterkey'</span><span class="p">)</span>
<span class="n">cur</span> <span class="o">=</span> <span class="n">con</span><span class="o">.</span><span class="n">cursor</span><span class="p">()</span>
<span class="n">newLanguages</span> <span class="o">=</span> <span class="p">[</span>
<span class="p">(</span><span class="s">'Lisp'</span><span class="p">,</span> <span class="mi">1958</span><span class="p">),</span>
<span class="p">(</span><span class="s">'Dylan'</span><span class="p">,</span> <span class="mi">1995</span><span class="p">),</span>
<span class="p">]</span>
<span class="n">cur</span><span class="o">.</span><span class="n">executemany</span><span class="p">(</span><span class="s">"insert into languages (name, year_released) values (?, ?)"</span><span class="p">,</span>
<span class="n">newLanguages</span>
<span class="p">)</span>
<span class="c"># The changes will not be saved unless the transaction is committed explicitly:</span>
<span class="n">con</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span>
</pre></div>
</div>
<p>Note the use of a <em>parameterized</em> SQL statement above. When dealing
with repetitive statements, this is much faster and less error-prone
than assembling each SQL statement manually. (You can read more about
parameterized SQL statements in the section on <a class="reference internal" href="usage-guide.html#prepared-statements"><em>Prepared Statements</em></a>.)</p>
<p>After running Example 4, the table printer from Example 3 would print:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">NAME</span> <span class="n">YEAR_RELEASED</span>
<span class="o">------------------------------------------------------------------------------</span>
<span class="n">Lisp</span> <span class="mi">1958</span>
<span class="n">C</span> <span class="mi">1972</span>
<span class="n">Python</span> <span class="mi">1991</span>
<span class="n">Dylan</span> <span class="mi">1995</span>
</pre></div>
</div>
</div>
<div class="section" id="calling-stored-procedures">
<h3>Calling Stored Procedures<a class="headerlink" href="#calling-stored-procedures" title="Permalink to this headline">¶</a></h3>
<p>Firebird supports stored procedures written in a proprietary procedural
SQL language. Firebird stored procedures can have <em>input</em> parameters and/or
<em>output</em> parameters. Some databases support <em>input/output</em> parameters,
where the same parameter is used for both input and output; Firebird does
not support this.</p>
<p>It is important to distinguish between procedures that <em>return a
result set</em> and procedures that <em>populate and return their output
parameters exactly once</em>. Conceptually, the latter “return their
output parameters” like a Python function, whereas the former “yield
result rows” like a Python generator.</p>
<p>Firebird’s <em>server-side</em> procedural SQL syntax makes no such distinction,
but <em>client-side</em> SQL code (and C API code) must. A result set is
retrieved from a stored procedure by <cite>SELECT`ing from the procedure,
whereas output parameters are retrieved with an `EXECUTE PROCEDURE</cite>
statement.</p>
<p>To <em>retrieve a result set</em> from a stored procedure with FDB,
use code such as this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">"select output1, output2 from the_proc(?, ?)"</span><span class="p">,</span> <span class="p">(</span><span class="n">input1</span><span class="p">,</span> <span class="n">input2</span><span class="p">))</span>
<span class="c"># Ordinary fetch code here, such as:</span>
<span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">cur</span><span class="p">:</span>
<span class="o">...</span> <span class="c"># process row</span>
<span class="n">con</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span> <span class="c"># If the procedure had any side effects, commit them.</span>
</pre></div>
</div>
<p>To <em>execute</em> a stored procedure and <em>access its output parameters</em>,
use code such as this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">cur</span><span class="o">.</span><span class="n">callproc</span><span class="p">(</span><span class="s">"the_proc"</span><span class="p">,</span> <span class="p">(</span><span class="n">input1</span><span class="p">,</span> <span class="n">input2</span><span class="p">))</span>
<span class="c"># If there are output parameters, retrieve them as though they were the</span>
<span class="c"># first row of a result set. For example:</span>
<span class="n">outputParams</span> <span class="o">=</span> <span class="n">cur</span><span class="o">.</span><span class="n">fetchone</span><span class="p">()</span>
<span class="n">con</span><span class="o">.</span><span class="n">commit</span><span class="p">()</span> <span class="c"># If the procedure had any side effects, commit them.</span>
</pre></div>
</div>
<p>This latter is not very elegant; it would be preferable to access the
procedure’s output parameters as the return value of
<cite>Cursor.callproc()</cite>. The Python DB API specification requires the
current behavior, however.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Getting Started with FDB</a><ul>
<li><a class="reference internal" href="#installation">Installation</a><ul>
<li><a class="reference internal" href="#installation-from-pypi">Installation from PYPI</a></li>
<li><a class="reference internal" href="#installation-from-source">Installation from source</a></li>
</ul>
</li>
<li><a class="reference internal" href="#quick-start-guide">Quick-start Guide</a><ul>
<li><a class="reference internal" href="#connecting-to-a-database">Connecting to a Database</a></li>
<li><a class="reference internal" href="#executing-sql-statements">Executing SQL Statements</a></li>
<li><a class="reference internal" href="#calling-stored-procedures">Calling Stored Procedures</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">Welcome to FDB’s documentation!</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="usage-guide.html"
title="next chapter">Usage Guide</a></p>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="usage-guide.html" title="Usage Guide"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="Welcome to FDB’s documentation!"
>previous</a> |</li>
<li><a href="index.html">FDB 1.4.10 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2009-2015, David Rushby, Pavel Cisar.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
</div>
</body>
</html>