Debian Codegraph @

doc/programmers-guide/quickstart-debriefing.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <HTML
3 ><HEAD
4 ><TITLE
5 >Quick Overview</TITLE
6 ><META
7 NAME="GENERATOR"
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
9 REL="HOME"
10 TITLE="Database Independent Abstraction Layer for C"
11 HREF="index.html"><LINK
12 REL="UP"
13 TITLE="libdbi in a Nutshell (Quickstart Guide)"
14 HREF="quickstart.html"><LINK
15 REL="PREVIOUS"
16 TITLE="libdbi in a Nutshell (Quickstart Guide)"
17 HREF="quickstart.html"><LINK
18 REL="NEXT"
19 TITLE="Generic Example Program"
20 HREF="quickstart-code.html"></HEAD
21 ><BODY
22 CLASS="SECTION"
23 BGCOLOR="#FFFFFF"
24 TEXT="#000000"
25 LINK="#0000FF"
26 VLINK="#840084"
27 ALINK="#0000FF"
28 ><DIV
29 CLASS="NAVHEADER"
30 ><TABLE
31 SUMMARY="Header navigation table"
32 WIDTH="100%"
33 BORDER="0"
34 CELLPADDING="0"
35 CELLSPACING="0"
36 ><TR
37 ><TH
38 COLSPAN="3"
39 ALIGN="center"
40 >Database Independent Abstraction Layer for C: libdbi Programmer's Guide</TH
41 ></TR
42 ><TR
43 ><TD
44 WIDTH="10%"
45 ALIGN="left"
46 VALIGN="bottom"
47 ><A
48 HREF="quickstart.html"
49 ACCESSKEY="P"
50 >Prev</A
51 ></TD
52 ><TD
53 WIDTH="80%"
54 ALIGN="center"
55 VALIGN="bottom"
56 >Chapter 3. libdbi in a Nutshell (Quickstart Guide)</TD
57 ><TD
58 WIDTH="10%"
59 ALIGN="right"
60 VALIGN="bottom"
61 ><A
62 HREF="quickstart-code.html"
63 ACCESSKEY="N"
64 >Next</A
65 ></TD
66 ></TR
67 ></TABLE
68 ><HR
69 ALIGN="LEFT"
70 WIDTH="100%"></DIV
71 ><DIV
72 CLASS="SECTION"
73 ><H1
74 CLASS="SECTION"
75 ><A
76 NAME="QUICKSTART-DEBRIEFING"
77 >3.1. Quick Overview</A
78 ></H1
79 ><P
80 >libdbi is implemented as a library and is usually available as a shared object (aka dynamically linked library). If your program is supposed to use libdbi's capabilities, your program must be linked against libdbi which will be explained shortly. At runtime, the first step is always to create a libdbi instance by calling <A
81 HREF="reference-core.html#DBI-INITIALIZE-R"
82 >dbi_initialize_r</A
83 >. Programs that use threads or a plugin system may create more than one instance if needed and use them independently of each other. libdbi uses a plugin system that allows various databases to be supported simultaneously, and can dynamically load or unload drivers that are supplied by libdbi or a third party. Each instance loads the available database drivers independently. Programs can then use one or more of these drivers to create connections to databases, either by calling <A
84 HREF="reference-driver.html#DBI-DRIVER-OPEN-R"
85 >dbi_driver_open_r</A
86 > followed by <A
87 HREF="reference-conn.html#DBI-CONN-OPEN"
88 >dbi_conn_open</A
89 >, or in a single step by calling <A
90 HREF="reference-conn.html#DBI-CONN-NEW-R"
91 >dbi_conn_new_r</A
92 >. Multiple connections may exist for a single driver, and all will function independently of each other. As not all database engine client libraries allow simultaneous access of a single connection by multiple threads, it is advisable to use separate connections per thread, even if you use a single libdbi instance for the entire process. Also, an instance may open connections using different drivers at the same time. Each libdbi instance can be independently shut down when no longer needed by calling <A
93 HREF="reference-core.html#DBI-SHUTDOWN-R"
94 >dbi_shutdown_r</A
95 > which frees the memory occupied by the loaded drivers.</P
96 ><DIV
97 CLASS="NOTE"
98 ><BLOCKQUOTE
99 CLASS="NOTE"
100 ><P
101 ><B
102 >Note: </B
103 >libdbi versions 0.8.x and earlier did not allow the use of separate instances per process. Instead, each process had exactly one instance which was managed by libdbi internally. This interface is still available for backwards compatibility but will eventually be dropped.</P
104 ></BLOCKQUOTE
105 ></DIV
106 ><P
107 > The connection's options (username, password, hostname, etc.) are set with <A
108 HREF="reference-conn.html#DBI-CONN-SET-OPTION"
109 >dbi_conn_set_option</A
110 > and <A
111 HREF="reference-conn.html#DBI-CONN-SET-OPTION-NUMERIC"
112 >dbi_conn_set_option_numeric</A
113 >. Once all options are set, <A
114 HREF="reference-database.html#DBI-CONN-CONNECT"
115 >dbi_conn_connect</A
116 > will connect to the database, waiting to handle a <A
117 HREF="reference-query.html#DBI-CONN-QUERY"
118 >dbi_conn_query</A
119 >. A query is a string containing a valid SQL statement. libdbi provides several functions to automatically quote any characters that might screw up the query string. The preferred functions are <A
120 HREF="reference-query.html#DBI-CONN-QUOTE-STRING"
121 >dbi_conn_quote_string</A
122 > and <A
123 HREF="reference-query.html#DBI-CONN-QUOTE-STRING-COPY"
124 >dbi_conn_quote_string_copy</A
125 > as they take into consideration the character encoding used by the current connection. The legacy functions <A
126 HREF="reference-driver.html#DBI-DRIVER-QUOTE-STRING"
127 >dbi_driver_quote_string</A
128 > and <A
129 HREF="reference-driver.html#DBI-DRIVER-QUOTE-STRING-COPY"
130 >dbi_driver_quote_string_copy</A
131 > are still supported but should be avoided in new code. After a successful query, you can retrieve rows with <A
132 HREF="reference-results.html#DBI-RESULT-FIRST-ROW"
133 >dbi_result_first_row</A
134 >, <A
135 HREF="reference-results.html#DBI-RESULT-LAST-ROW"
136 >dbi_result_last_row</A
137 >, <A
138 HREF="reference-results.html#DBI-RESULT-PREV-ROW"
139 >dbi_result_prev_row</A
140 >, <A
141 HREF="reference-results.html#DBI-RESULT-NEXT-ROW"
142 >dbi_result_next_row</A
143 >, and <A
144 HREF="reference-results.html#DBI-RESULT-SEEK-ROW"
145 >dbi_result_seek_row</A
146 >.
147 </P
148 ><P
149 >String data may be sent to and retrieved from a database using character encodings if they contain characters not covered by the ASCII character set. Most database engines support character encodings like ISO-8859-1, suitable for many European languages, or even the multibyte Unicode character sets like UTF-8. The character set used to store your data in your database is usually set by the <B
150 CLASS="COMMAND"
151 >CREATE DATABASE</B
152 > command, which you have to take care of yourself. libdbi uses the connection option "encoding" to select a particular character encoding for the current connection. If you set the value to "auto", libdbi will automatically use the database character encoding as the connection encoding. If you request a different character encoding, as defined by its <A
153 HREF="http://www.iana.org"
154 TARGET="_top"
155 >IANA</A
156 > name, libdbi will convert the data on the fly.</P
157 ><P
158 > There are two methods for fetching field data, and two ways to perform each method. You can either "pull" the data from DBI using the <TT
159 CLASS="LITERAL"
160 >dbi_result_get_*</TT
161 > family of functions, or have DBI automatically "push" the data into predefined variables with the <TT
162 CLASS="LITERAL"
163 >dbi_result_bind_*</TT
164 > family of functions. Both families of functions are as strongly typed as most SQL database engines are. That is, you must use the <TT
165 CLASS="LITERAL"
166 >dbi_result_get_*</TT
167 > or <TT
168 CLASS="LITERAL"
169 >dbi_result_bind_*</TT
170 > function that matches the type of the requested field. <A
171 HREF="quickstart-debriefing.html#TABLE-GET-BIND-FUNCTIONS"
172 >Table 3-1</A
173 > shows an overview of these functions sorted by the field type they retrieve.
174 </P
175 ><P
176 > Pulling the data from the database can be done with one of the "get" functions such as <A
177 HREF="reference-field.html#DBI-RESULT-GET-LONG"
178 >dbi_result_get_long</A
179 > or <A
180 HREF="reference-field.html#DBI-RESULT-GET-STRING"
181 >dbi_result_get_string</A
182 >, which simply return the data in the field you asked for. You should run the function <A
183 HREF="reference-conn.html#DBI-CONN-ERROR-FLAG"
184 >dbi_conn_error_flag</A
185 > immediately after each call to a "get" function to check for errors. You can also get more than one field at a time with <A
186 HREF="reference-field.html#DBI-RESULT-GET-FIELDS"
187 >dbi_result_get_fields</A
188 >, which uses a printf-like syntax.
189 </P
190 ><P
191 > If you want DBI to automatically fill your program's variables with field values whenever a new row is fetched, you can "bind" fields to your variables. Bindings are set up with <A
192 HREF="reference-field.html#DBI-RESULT-BIND-LONG"
193 >dbi_result_bind_long</A
194 >, <A
195 HREF="reference-field.html#DBI-RESULT-BIND-STRING"
196 >dbi_result_bind_string</A
197 >, and the rest of the bind family of functions. Like the associated "get" function, you can set up multiple bindings at once with the <A
198 HREF="reference-field.html#DBI-RESULT-BIND-FIELDS"
199 >dbi_result_bind_fields</A
200 > function.
201 </P
202 ><P
203 >String data can be safely included into query strings by using the <A
204 HREF="reference-query.html#DBI-CONN-QUOTE-STRING"
205 >dbi_conn_quote_string</A
206 > and <A
207 HREF="reference-query.html#DBI-CONN-QUOTE-STRING-COPY"
208 >dbi_conn_quote_string_copy</A
209 > functions. Binary data can be included into query strings by using the <A
210 HREF="reference-query.html#DBI-CONN-QUOTE-BINARY-COPY"
211 >dbi_conn_quote_binary_copy</A
212 > function. All of these functions return zero-terminated strings enclosed in the appropriate quoting characters. Binary strings are returned in their binary representation. That is, they may contain null bytes and other non-printable characters. It is mandatory to use the <A
213 HREF="reference-field-meta.html#DBI-RESULT-GET-FIELD-LENGTH"
214 >dbi_result_get_field_length</A
215 > or <A
216 HREF="reference-field-meta.html#DBI-RESULT-GET-FIELD-LENGTH-IDX"
217 >dbi_result_get_field_length_idx</A
218 > functions to determine the number of bytes contained in the binary string.</P
219 ><P
220 ><EM
221 >Caveats:</EM
222 ></P
223 ><P
224 ></P
225 ><UL
226 ><LI
227 ><P
228 >For fields holding integers (not fractional numbers), DBI differentiates between signed and unsigned variables. By default, DBI returns signed values. If you want an unsigned value, prepend a "u" to the name of the target type. For example, dbi_result_bind_short becomes dbi_result_bind_ushort.</P
229 ></LI
230 ><LI
231 ><P
232 >You must set up any bindings <EM
233 >after</EM
234 > a successful query but <EM
235 >before</EM
236 > you fetch any rows. Even if you are using field bindings, you can still use the dbi_result_get_* functions as usual. (actually, I lied... setting up a binding should theoretically work at any time, but don't plan on this behavior in future versions)</P
237 ></LI
238 ><LI
239 ><P
240 >All string and binary data returned or bound from DBI is <EM
241 >read-only</EM
242 >. If you want your own local copy that can be modified at will, use <A
243 HREF="reference-field.html#DBI-RESULT-GET-STRING-COPY"
244 >dbi_result_get_string_copy</A
245 >, <A
246 HREF="reference-field.html#DBI-RESULT-GET-BINARY-COPY"
247 >dbi_result_get_binary_copy</A
248 >, <A
249 HREF="reference-field.html#DBI-RESULT-BIND-STRING-COPY"
250 >dbi_result_bind_string_copy</A
251 >, or <A
252 HREF="reference-field.html#DBI-RESULT-BIND-BINARY-COPY"
253 >dbi_result_bind_binary_copy</A
254 >. You will be responsible for freeing the memory allocated by these functions.</P
255 ></LI
256 ></UL
257 ><P
258 > <A
259 HREF="reference-results.html#DBI-RESULT-NEXT-ROW"
260 >dbi_result_next_row</A
261 > and the other row-seeking functions will return zero when there are no more rows available. Before the program terminates, you must call <A
262 HREF="reference-results.html#DBI-RESULT-FREE"
263 >dbi_result_free</A
264 > on every result set and the connection must be disconnected and unloaded with <A
265 HREF="reference-conn.html#DBI-CONN-CLOSE"
266 >dbi_conn_close</A
267 >. Finally, libdbi must be unloaded with <A
268 HREF="reference-core.html#DBI-SHUTDOWN"
269 >dbi_shutdown</A
270 >.
271 </P
272 ><DIV
273 CLASS="TABLE"
274 ><A
275 NAME="TABLE-GET-BIND-FUNCTIONS"
276 ></A
277 ><P
278 ><B
279 >Table 3-1. get* and bind* functions sorted by field type</B
280 ></P
281 ><TABLE
282 BORDER="1"
283 CLASS="CALSTABLE"
284 ><COL><COL><COL><COL><THEAD
285 ><TR
286 ><TH
287 >field type</TH
288 ><TH
289 >get by name</TH
290 ><TH
291 >get by field index</TH
292 ><TH
293 >bind</TH
294 ></TR
295 ></THEAD
296 ><TBODY
297 ><TR
298 ><TD
299 >signed char</TD
300 ><TD
301 ><A
302 HREF="reference-field.html#DBI-RESULT-GET-CHAR"
303 >dbi_result_get_char</A
304 ></TD
305 ><TD
306 ><A
307 HREF="reference-field-idx.html#DBI-RESULT-GET-CHAR-IDX"
308 >dbi_result_get_char_idx</A
309 ></TD
310 ><TD
311 ><A
312 HREF="reference-field.html#DBI-RESULT-BIND-CHAR"
313 >dbi_result_bind_char</A
314 ></TD
315 ></TR
316 ><TR
317 ><TD
318 >unsigned char</TD
319 ><TD
320 ><A
321 HREF="reference-field.html#DBI-RESULT-GET-UCHAR"
322 >dbi_result_get_uchar</A
323 ></TD
324 ><TD
325 ><A
326 HREF="reference-field-idx.html#DBI-RESULT-GET-UCHAR-IDX"
327 >dbi_result_get_uchar_idx</A
328 ></TD
329 ><TD
330 ><A
331 HREF="reference-field.html#DBI-RESULT-BIND-UCHAR"
332 >dbi_result_bind_uchar</A
333 ></TD
334 ></TR
335 ><TR
336 ><TD
337 >short</TD
338 ><TD
339 ><A
340 HREF="reference-field.html#DBI-RESULT-GET-SHORT"
341 >dbi_result_get_short</A
342 ></TD
343 ><TD
344 ><A
345 HREF="reference-field-idx.html#DBI-RESULT-GET-SHORT-IDX"
346 >dbi_result_get_short_idx</A
347 ></TD
348 ><TD
349 ><A
350 HREF="reference-field.html#DBI-RESULT-BIND-SHORT"
351 >dbi_result_bind_short</A
352 ></TD
353 ></TR
354 ><TR
355 ><TD
356 >unsigned short</TD
357 ><TD
358 ><A
359 HREF="reference-field.html#DBI-RESULT-GET-USHORT"
360 >dbi_result_get_ushort</A
361 ></TD
362 ><TD
363 ><A
364 HREF="reference-field-idx.html#DBI-RESULT-GET-USHORT-IDX"
365 >dbi_result_get_ushort_idx</A
366 ></TD
367 ><TD
368 ><A
369 HREF="reference-field.html#DBI-RESULT-BIND-USHORT"
370 >dbi_result_bind_ushort</A
371 ></TD
372 ></TR
373 ><TR
374 ><TD
375 >int</TD
376 ><TD
377 ><A
378 HREF="reference-field.html#DBI-RESULT-GET-INT"
379 >dbi_result_get_int</A
380 ></TD
381 ><TD
382 ><A
383 HREF="reference-field-idx.html#DBI-RESULT-GET-INT-IDX"
384 >dbi_result_get_int_idx</A
385 ></TD
386 ><TD
387 ><A
388 HREF="reference-field.html#DBI-RESULT-BIND-INT"
389 >dbi_result_bind_int</A
390 ></TD
391 ></TR
392 ><TR
393 ><TD
394 >unsigned int</TD
395 ><TD
396 ><A
397 HREF="reference-field.html#DBI-RESULT-GET-UINT"
398 >dbi_result_get_uint</A
399 ></TD
400 ><TD
401 ><A
402 HREF="reference-field-idx.html#DBI-RESULT-GET-UINT-IDX"
403 >dbi_result_get_uint_idx</A
404 ></TD
405 ><TD
406 ><A
407 HREF="reference-field.html#DBI-RESULT-BIND-UINT"
408 >dbi_result_bind_uint</A
409 ></TD
410 ></TR
411 ><TR
412 ><TD
413 >long long</TD
414 ><TD
415 ><A
416 HREF="reference-field.html#DBI-RESULT-GET-LONGLONG"
417 >dbi_result_get_longlong</A
418 ></TD
419 ><TD
420 ><A
421 HREF="reference-field-idx.html#DBI-RESULT-GET-LONGLONG-IDX"
422 >dbi_result_get_longlong_idx</A
423 ></TD
424 ><TD
425 ><A
426 HREF="reference-field.html#DBI-RESULT-BIND-LONGLONG"
427 >dbi_result_bind_longlong</A
428 ></TD
429 ></TR
430 ><TR
431 ><TD
432 >unsigned long long</TD
433 ><TD
434 ><A
435 HREF="reference-field.html#DBI-RESULT-GET-ULONGLONG"
436 >dbi_result_get_ulonglong</A
437 ></TD
438 ><TD
439 ><A
440 HREF="reference-field-idx.html#DBI-RESULT-GET-ULONGLONG-IDX"
441 >dbi_result_get_ulonglong_idx</A
442 ></TD
443 ><TD
444 ><A
445 HREF="reference-field.html#DBI-RESULT-BIND-ULONGLONG"
446 >dbi_result_bind_ulonglong</A
447 ></TD
448 ></TR
449 ><TR
450 ><TD
451 >float</TD
452 ><TD
453 ><A
454 HREF="reference-field.html#DBI-RESULT-GET-FLOAT"
455 >dbi_result_get_float</A
456 ></TD
457 ><TD
458 ><A
459 HREF="reference-field-idx.html#DBI-RESULT-GET-FLOAT-IDX"
460 >dbi_result_get_float_idx</A
461 ></TD
462 ><TD
463 ><A
464 HREF="reference-field.html#DBI-RESULT-BIND-FLOAT"
465 >dbi_result_bind_float</A
466 ></TD
467 ></TR
468 ><TR
469 ><TD
470 >double</TD
471 ><TD
472 ><A
473 HREF="reference-field.html#DBI-RESULT-GET-DOUBLE"
474 >dbi_result_get_double</A
475 ></TD
476 ><TD
477 ><A
478 HREF="reference-field-idx.html#DBI-RESULT-GET-DOUBLE-IDX"
479 >dbi_result_get_double_idx</A
480 ></TD
481 ><TD
482 ><A
483 HREF="reference-field.html#DBI-RESULT-BIND-DOUBLE"
484 >dbi_result_bind_double</A
485 ></TD
486 ></TR
487 ><TR
488 ><TD
489 >character string</TD
490 ><TD
491 ><A
492 HREF="reference-field.html#DBI-RESULT-GET-STRING"
493 >dbi_result_get_string</A
494 >, <A
495 HREF="reference-field.html#DBI-RESULT-GET-STRING-COPY"
496 >dbi_result_get_string_copy</A
497 ></TD
498 ><TD
499 ><A
500 HREF="reference-field-idx.html#DBI-RESULT-GET-STRING-IDX"
501 >dbi_result_get_string_idx</A
502 >, <A
503 HREF="reference-field-idx.html#DBI-RESULT-GET-STRING-COPY-IDX"
504 >dbi_result_get_string_copy_idx</A
505 ></TD
506 ><TD
507 ><A
508 HREF="reference-field.html#DBI-RESULT-BIND-STRING"
509 >dbi_result_bind_string</A
510 ></TD
511 ></TR
512 ><TR
513 ><TD
514 >binary string</TD
515 ><TD
516 ><A
517 HREF="reference-field.html#DBI-RESULT-GET-BINARY"
518 >dbi_result_get_binary</A
519 >, <A
520 HREF="reference-field.html#DBI-RESULT-GET-BINARY-COPY"
521 >dbi_result_get_binary_copy</A
522 ></TD
523 ><TD
524 ><A
525 HREF="reference-field-idx.html#DBI-RESULT-GET-BINARY-IDX"
526 >dbi_result_get_binary_idx</A
527 >, <A
528 HREF="reference-field-idx.html#DBI-RESULT-GET-BINARY-COPY-IDX"
529 >dbi_result_get_binary_copy_idx</A
530 ></TD
531 ><TD
532 ><A
533 HREF="reference-field.html#DBI-RESULT-BIND-BINARY"
534 >dbi_result_bind_binary</A
535 ></TD
536 ></TR
537 ><TR
538 ><TD
539 >date/time</TD
540 ><TD
541 ><A
542 HREF="reference-field.html#DBI-RESULT-GET-DATETIME"
543 >dbi_result_get_datetime</A
544 ></TD
545 ><TD
546 ><A
547 HREF="reference-field-idx.html#DBI-RESULT-GET-DATETIME-IDX"
548 >dbi_result_get_datetime_idx</A
549 ></TD
550 ><TD
551 ><A
552 HREF="reference-field.html#DBI-RESULT-BIND-DATETIME"
553 >dbi_result_bind_datetime</A
554 ></TD
555 ></TR
556 ></TBODY
557 ></TABLE
558 ></DIV
559 ></DIV
560 ><DIV
561 CLASS="NAVFOOTER"
562 ><HR
563 ALIGN="LEFT"
564 WIDTH="100%"><TABLE
565 SUMMARY="Footer navigation table"
566 WIDTH="100%"
567 BORDER="0"
568 CELLPADDING="0"
569 CELLSPACING="0"
570 ><TR
571 ><TD
572 WIDTH="33%"
573 ALIGN="left"
574 VALIGN="top"
575 ><A
576 HREF="quickstart.html"
577 ACCESSKEY="P"
578 >Prev</A
579 ></TD
580 ><TD
581 WIDTH="34%"
582 ALIGN="center"
583 VALIGN="top"
584 ><A
585 HREF="index.html"
586 ACCESSKEY="H"
587 >Home</A
588 ></TD
589 ><TD
590 WIDTH="33%"
591 ALIGN="right"
592 VALIGN="top"
593 ><A
594 HREF="quickstart-code.html"
595 ACCESSKEY="N"
596 >Next</A
597 ></TD
598 ></TR
599 ><TR
600 ><TD
601 WIDTH="33%"
602 ALIGN="left"
603 VALIGN="top"
604 >libdbi in a Nutshell (Quickstart Guide)</TD
605 ><TD
606 WIDTH="34%"
607 ALIGN="center"
608 VALIGN="top"
609 ><A
610 HREF="quickstart.html"
611 ACCESSKEY="U"
612 >Up</A
613 ></TD
614 ><TD
615 WIDTH="33%"
616 ALIGN="right"
617 VALIGN="top"
618 >Generic Example Program</TD
619 ></TR
620 ></TABLE
621 ></DIV
622 ></BODY
623 ></HTML
624 >