Debian Codegraph @

doc/programmers-guide/reference-core.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 >Instance Infrastructure</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 API Reference"
14 HREF="reference.html"><LINK
15 REL="PREVIOUS"
16 TITLE="libdbi API Reference"
17 HREF="reference.html"><LINK
18 REL="NEXT"
19 TITLE="Driver Infrastructure"
20 HREF="reference-driver.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="reference.html"
49 ACCESSKEY="P"
50 >Prev</A
51 ></TD
52 ><TD
53 WIDTH="80%"
54 ALIGN="center"
55 VALIGN="bottom"
56 >Chapter 7. libdbi API Reference</TD
57 ><TD
58 WIDTH="10%"
59 ALIGN="right"
60 VALIGN="bottom"
61 ><A
62 HREF="reference-driver.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="REFERENCE-CORE"
77 >7.1. Instance Infrastructure</A
78 ></H1
79 ><DIV
80 CLASS="SECTION"
81 ><H2
82 CLASS="SECTION"
83 ><A
84 NAME="DBI-INITIALIZE-R"
85 >7.1.1. dbi_initialize_r</A
86 ></H2
87 ><DIV
88 CLASS="FUNCSYNOPSIS"
89 ><P
90 ></P
91 ><A
92 NAME="AEN509"
93 ></A
94 ><P
95 ><CODE
96 ><CODE
97 CLASS="FUNCDEF"
98 >int <B
99 CLASS="FSFUNC"
100 >dbi_initialize_r</B
101 ></CODE
102 >(const char *<VAR
103 CLASS="PDPARAM"
104 >driverdir</VAR
105 >, dbi_inst *pInst);</CODE
106 ></P
107 ><P
108 ></P
109 ></DIV
110 ><P
111 >Creates an instance of libdbi, locates all available database drivers and loads them into memory.</P
112 ><P
113 ></P
114 ><DIV
115 CLASS="VARIABLELIST"
116 ><DL
117 ><DT
118 >Arguments</DT
119 ><DD
120 ><P
121 ><TT
122 CLASS="LITERAL"
123 >driverdir</TT
124 >: The directory to search for drivers. If NULL, DBI_DRIVER_DIR (defined at compile time) will be used instead.</P
125 ><P
126 ><TT
127 CLASS="LITERAL"
128 >pInst</TT
129 >: A pointer to an instance handle. The function will fill in the new instance handle if successful, or set it to NULL if an error occurred.</P
130 ></DD
131 ><DT
132 >Returns</DT
133 ><DD
134 ><P
135 >The number of drivers successfully loaded, or -1 if there was an error. The latter may be due to an incorrect driver directory or to a lack of permissions.</P
136 ></DD
137 ><DT
138 >Availability</DT
139 ><DD
140 ><P
141 >0.9.0</P
142 ></DD
143 ></DL
144 ></DIV
145 ></DIV
146 ><DIV
147 CLASS="SECTION"
148 ><H2
149 CLASS="SECTION"
150 ><A
151 NAME="DBI-INITIALIZE"
152 >7.1.2. dbi_initialize</A
153 ></H2
154 ><DIV
155 CLASS="FUNCSYNOPSIS"
156 ><P
157 ></P
158 ><A
159 NAME="AEN535"
160 ></A
161 ><P
162 ><CODE
163 ><CODE
164 CLASS="FUNCDEF"
165 >int <B
166 CLASS="FSFUNC"
167 >dbi_initialize</B
168 ></CODE
169 >(const char *<VAR
170 CLASS="PDPARAM"
171 >driverdir</VAR
172 >);</CODE
173 ></P
174 ><P
175 ></P
176 ></DIV
177 ><P
178 >Locates all available database drivers and loads them into memory.</P
179 ><DIV
180 CLASS="NOTE"
181 ><BLOCKQUOTE
182 CLASS="NOTE"
183 ><P
184 ><B
185 >Note: </B
186 >This function is deprecated. Use <A
187 HREF="reference-core.html#DBI-INITIALIZE-R"
188 >dbi_initialize_r</A
189 > instead. In contrast to that function, dbi_initialize allows only one (internally managed) libdbi instance per process.</P
190 ></BLOCKQUOTE
191 ></DIV
192 ><P
193 ></P
194 ><DIV
195 CLASS="VARIABLELIST"
196 ><DL
197 ><DT
198 >Arguments</DT
199 ><DD
200 ><P
201 ><TT
202 CLASS="LITERAL"
203 >driverdir</TT
204 >: The directory to search for drivers. If NULL, DBI_DRIVER_DIR (defined at compile time) will be used instead.</P
205 ></DD
206 ><DT
207 >Returns</DT
208 ><DD
209 ><P
210 >The number of drivers successfully loaded, or -1 if there was an error.</P
211 ></DD
212 ></DL
213 ></DIV
214 ></DIV
215 ><DIV
216 CLASS="SECTION"
217 ><H2
218 CLASS="SECTION"
219 ><A
220 NAME="DBI-SHUTDOWN-R"
221 >7.1.3. dbi_shutdown_r</A
222 ></H2
223 ><DIV
224 CLASS="FUNCSYNOPSIS"
225 ><P
226 ></P
227 ><A
228 NAME="AEN557"
229 ></A
230 ><P
231 ><CODE
232 ><CODE
233 CLASS="FUNCDEF"
234 >void <B
235 CLASS="FSFUNC"
236 >dbi_shutdown_r</B
237 ></CODE
238 >(dbi_inst <VAR
239 CLASS="PDPARAM"
240 >Inst</VAR
241 >);</CODE
242 ></P
243 ><P
244 ></P
245 ></DIV
246 ><P
247 >Frees all loaded drivers and terminates the libdbi instance. You should close each connection you opened before shutting down, but libdbi will clean up after you if you don't.</P
248 ><P
249 ></P
250 ><DIV
251 CLASS="VARIABLELIST"
252 ><DL
253 ><DT
254 >Arguments</DT
255 ><DD
256 ><P
257 ><TT
258 CLASS="LITERAL"
259 >Inst</TT
260 >: The instance handle.</P
261 ></DD
262 ><DT
263 >Availability</DT
264 ><DD
265 ><P
266 >0.9.0</P
267 ></DD
268 ></DL
269 ></DIV
270 ></DIV
271 ><DIV
272 CLASS="SECTION"
273 ><H2
274 CLASS="SECTION"
275 ><A
276 NAME="DBI-SHUTDOWN"
277 >7.1.4. dbi_shutdown</A
278 ></H2
279 ><DIV
280 CLASS="FUNCSYNOPSIS"
281 ><P
282 ></P
283 ><A
284 NAME="AEN576"
285 ></A
286 ><P
287 ><CODE
288 ><CODE
289 CLASS="FUNCDEF"
290 >void <B
291 CLASS="FSFUNC"
292 >dbi_shutdown</B
293 ></CODE
294 >(void);</CODE
295 ></P
296 ><P
297 ></P
298 ></DIV
299 ><P
300 >Frees all loaded drivers and terminates the DBI system. You should close each connection you opened before shutting down, but libdbi will clean up after you if you don't.</P
301 ><DIV
302 CLASS="NOTE"
303 ><BLOCKQUOTE
304 CLASS="NOTE"
305 ><P
306 ><B
307 >Note: </B
308 >This function is deprecated. Use <A
309 HREF="reference-core.html#DBI-SHUTDOWN-R"
310 >dbi_shutdown_r</A
311 > instead.</P
312 ></BLOCKQUOTE
313 ></DIV
314 ></DIV
315 ><DIV
316 CLASS="SECTION"
317 ><H2
318 CLASS="SECTION"
319 ><A
320 NAME="DBI-SET-VERBOSITY-R"
321 >7.1.5. dbi_set_verbosity_r</A
322 ></H2
323 ><DIV
324 CLASS="FUNCSYNOPSIS"
325 ><P
326 ></P
327 ><A
328 NAME="AEN587"
329 ></A
330 ><P
331 ><CODE
332 ><CODE
333 CLASS="FUNCDEF"
334 >int <B
335 CLASS="FSFUNC"
336 >dbi_set_verbosity_r</B
337 ></CODE
338 >(int <VAR
339 CLASS="PDPARAM"
340 >verbosity</VAR
341 >, dbi_inst Inst);</CODE
342 ></P
343 ><P
344 ></P
345 ></DIV
346 ><P
347 >Toggles internal error messages on or off in the given libdbi instance. This affects only those error messages which are directly sent to stderr, not those handled by the <A
348 HREF="errorhandling.html"
349 >connection error API</A
350 >.</P
351 ><P
352 ></P
353 ><DIV
354 CLASS="VARIABLELIST"
355 ><DL
356 ><DT
357 >Arguments</DT
358 ><DD
359 ><P
360 ><TT
361 CLASS="LITERAL"
362 >verbosity</TT
363 >: A nonzero value causes error messages to be printed on stderr. 0 (zero) suppresses error messages.</P
364 ><P
365 ><TT
366 CLASS="LITERAL"
367 >Inst</TT
368 >: The instance handle.</P
369 ></DD
370 ><DT
371 >Returns</DT
372 ><DD
373 ><P
374 >The previous setting of <CODE
375 CLASS="PARAMETER"
376 >verbosity</CODE
377 >.</P
378 ></DD
379 ><DT
380 >Availability</DT
381 ><DD
382 ><P
383 >0.9.0</P
384 ></DD
385 ></DL
386 ></DIV
387 ></DIV
388 ><DIV
389 CLASS="SECTION"
390 ><H2
391 CLASS="SECTION"
392 ><A
393 NAME="DBI-SET-VERBOSITY"
394 >7.1.6. dbi_set_verbosity</A
395 ></H2
396 ><DIV
397 CLASS="FUNCSYNOPSIS"
398 ><P
399 ></P
400 ><A
401 NAME="AEN615"
402 ></A
403 ><P
404 ><CODE
405 ><CODE
406 CLASS="FUNCDEF"
407 >int <B
408 CLASS="FSFUNC"
409 >dbi_set_verbosity</B
410 ></CODE
411 >(int <VAR
412 CLASS="PDPARAM"
413 >verbosity</VAR
414 >);</CODE
415 ></P
416 ><P
417 ></P
418 ></DIV
419 ><P
420 >Toggles internal error messages on or off. This affects only those error messages which are directly sent to stderr, not those handled by the <A
421 HREF="errorhandling.html"
422 >connection error API</A
423 >.</P
424 ><DIV
425 CLASS="NOTE"
426 ><BLOCKQUOTE
427 CLASS="NOTE"
428 ><P
429 ><B
430 >Note: </B
431 >This function is deprecated. Use <A
432 HREF="reference-core.html#DBI-SET-VERBOSITY-R"
433 >dbi_set_verbosity_r</A
434 > instead.</P
435 ></BLOCKQUOTE
436 ></DIV
437 ><P
438 ></P
439 ><DIV
440 CLASS="VARIABLELIST"
441 ><DL
442 ><DT
443 >Arguments</DT
444 ><DD
445 ><P
446 ><TT
447 CLASS="LITERAL"
448 >verbosity</TT
449 >: A nonzero value causes error messages to be printed on stderr. 0 (zero) suppresses error messages.</P
450 ></DD
451 ><DT
452 >Returns</DT
453 ><DD
454 ><P
455 >The previous setting of <CODE
456 CLASS="PARAMETER"
457 >verbosity</CODE
458 >.</P
459 ></DD
460 ></DL
461 ></DIV
462 ></DIV
463 ><DIV
464 CLASS="SECTION"
465 ><H2
466 CLASS="SECTION"
467 ><A
468 NAME="DBI-VERSION"
469 >7.1.7. dbi_version</A
470 ></H2
471 ><DIV
472 CLASS="FUNCSYNOPSIS"
473 ><P
474 ></P
475 ><A
476 NAME="AEN639"
477 ></A
478 ><P
479 ><CODE
480 ><CODE
481 CLASS="FUNCDEF"
482 >const char *<B
483 CLASS="FSFUNC"
484 >dbi_version</B
485 ></CODE
486 >(void);</CODE
487 ></P
488 ><P
489 ></P
490 ></DIV
491 ><P
492 >Requests the version of libdbi as a read-only string. The calling program must not attempt to free the returned string.</P
493 ><P
494 ></P
495 ><DIV
496 CLASS="VARIABLELIST"
497 ><DL
498 ><DT
499 >Returns</DT
500 ><DD
501 ><P
502 >A string containing the library's name and version.</P
503 ></DD
504 ></DL
505 ></DIV
506 ></DIV
507 ><DIV
508 CLASS="SECTION"
509 ><H2
510 CLASS="SECTION"
511 ><A
512 NAME="DBI-VERSION-NUMERIC"
513 >7.1.8. dbi_version_numeric</A
514 ></H2
515 ><DIV
516 CLASS="FUNCSYNOPSIS"
517 ><P
518 ></P
519 ><A
520 NAME="AEN652"
521 ></A
522 ><P
523 ><CODE
524 ><CODE
525 CLASS="FUNCDEF"
526 >unsigned int <B
527 CLASS="FSFUNC"
528 >dbi_version_numeric</B
529 ></CODE
530 >(void);</CODE
531 ></P
532 ><P
533 ></P
534 ></DIV
535 ><P
536 >Requests the version of libdbi as an integer.</P
537 ><P
538 ></P
539 ><DIV
540 CLASS="VARIABLELIST"
541 ><DL
542 ><DT
543 >Returns</DT
544 ><DD
545 ><P
546 >The version, computed as ((major * 10000) + (minor * 100) + patch).</P
547 ></DD
548 ><DT
549 >Availability</DT
550 ><DD
551 ><P
552 >0.9.0</P
553 ></DD
554 ></DL
555 ></DIV
556 ></DIV
557 ></DIV
558 ><DIV
559 CLASS="NAVFOOTER"
560 ><HR
561 ALIGN="LEFT"
562 WIDTH="100%"><TABLE
563 SUMMARY="Footer navigation table"
564 WIDTH="100%"
565 BORDER="0"
566 CELLPADDING="0"
567 CELLSPACING="0"
568 ><TR
569 ><TD
570 WIDTH="33%"
571 ALIGN="left"
572 VALIGN="top"
573 ><A
574 HREF="reference.html"
575 ACCESSKEY="P"
576 >Prev</A
577 ></TD
578 ><TD
579 WIDTH="34%"
580 ALIGN="center"
581 VALIGN="top"
582 ><A
583 HREF="index.html"
584 ACCESSKEY="H"
585 >Home</A
586 ></TD
587 ><TD
588 WIDTH="33%"
589 ALIGN="right"
590 VALIGN="top"
591 ><A
592 HREF="reference-driver.html"
593 ACCESSKEY="N"
594 >Next</A
595 ></TD
596 ></TR
597 ><TR
598 ><TD
599 WIDTH="33%"
600 ALIGN="left"
601 VALIGN="top"
602 >libdbi API Reference</TD
603 ><TD
604 WIDTH="34%"
605 ALIGN="center"
606 VALIGN="top"
607 ><A
608 HREF="reference.html"
609 ACCESSKEY="U"
610 >Up</A
611 ></TD
612 ><TD
613 WIDTH="33%"
614 ALIGN="right"
615 VALIGN="top"
616 >Driver Infrastructure</TD
617 ></TR
618 ></TABLE
619 ></DIV
620 ></BODY
621 ></HTML
622 >