Debian Codegraph @

doc/programmers-guide/reference-conn.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 >Connection 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="Driver Infrastructure"
17 HREF="reference-driver.html"><LINK
18 REL="NEXT"
19 TITLE="SQL and Database Infrastructure"
20 HREF="reference-database.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-driver.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-database.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-CONN"
77 >7.3. Connection Infrastructure</A
78 ></H1
79 ><DIV
80 CLASS="SECTION"
81 ><H2
82 CLASS="SECTION"
83 ><A
84 NAME="DBI-CONN-NEW-R"
85 >7.3.1. dbi_conn_new_r</A
86 ></H2
87 ><DIV
88 CLASS="FUNCSYNOPSIS"
89 ><P
90 ></P
91 ><A
92 NAME="AEN1113"
93 ></A
94 ><P
95 ><CODE
96 ><CODE
97 CLASS="FUNCDEF"
98 >dbi_conn <B
99 CLASS="FSFUNC"
100 >dbi_conn_new_r</B
101 ></CODE
102 >(const char *<VAR
103 CLASS="PDPARAM"
104 >name</VAR
105 >, dbi_inst <VAR
106 CLASS="PDPARAM"
107 >Inst</VAR
108 >);</CODE
109 ></P
110 ><P
111 ></P
112 ></DIV
113 ><P
114 >Creates a connection instance of the driver specified by "name" loaded by the given libdbi instance. This is a shortcut for calling <A
115 HREF="reference-driver.html#DBI-DRIVER-OPEN-R"
116 >dbi_driver_open_r</A
117 > and passing the result to <A
118 HREF="reference-conn.html#DBI-CONN-OPEN"
119 >dbi_conn_open</A
120 >.</P
121 ><P
122 ></P
123 ><DIV
124 CLASS="VARIABLELIST"
125 ><DL
126 ><DT
127 >Arguments</DT
128 ><DD
129 ><P
130 ><TT
131 CLASS="LITERAL"
132 >name</TT
133 >: The name of the desired driver.</P
134 ><P
135 ><TT
136 CLASS="LITERAL"
137 >Inst</TT
138 >: The instance handle.</P
139 ></DD
140 ><DT
141 >Returns</DT
142 ><DD
143 ><P
144 >A connection instance of the specified driver, or NULL if there was an error.</P
145 ></DD
146 ></DL
147 ></DIV
148 ></DIV
149 ><DIV
150 CLASS="SECTION"
151 ><H2
152 CLASS="SECTION"
153 ><A
154 NAME="DBI-CONN-NEW"
155 >7.3.2. dbi_conn_new</A
156 ></H2
157 ><DIV
158 CLASS="FUNCSYNOPSIS"
159 ><P
160 ></P
161 ><A
162 NAME="AEN1138"
163 ></A
164 ><P
165 ><CODE
166 ><CODE
167 CLASS="FUNCDEF"
168 >dbi_conn <B
169 CLASS="FSFUNC"
170 >dbi_conn_new</B
171 ></CODE
172 >(const char *<VAR
173 CLASS="PDPARAM"
174 >name</VAR
175 >);</CODE
176 ></P
177 ><P
178 ></P
179 ></DIV
180 ><P
181 >Creates a connection instance of the driver specified by "name". This is a shortcut for calling <A
182 HREF="reference-driver.html#DBI-DRIVER-OPEN"
183 >dbi_driver_open</A
184 > and passing the result to <A
185 HREF="reference-conn.html#DBI-CONN-OPEN"
186 >dbi_conn_open</A
187 >.</P
188 ><DIV
189 CLASS="NOTE"
190 ><BLOCKQUOTE
191 CLASS="NOTE"
192 ><P
193 ><B
194 >Note: </B
195 >This function is deprecated. Use <A
196 HREF="reference-conn.html#DBI-CONN-NEW-R"
197 >dbi_conn_new_r</A
198 > instead.</P
199 ></BLOCKQUOTE
200 ></DIV
201 ><P
202 ></P
203 ><DIV
204 CLASS="VARIABLELIST"
205 ><DL
206 ><DT
207 >Arguments</DT
208 ><DD
209 ><P
210 ><TT
211 CLASS="LITERAL"
212 >name</TT
213 >: The name of the desired driver.</P
214 ></DD
215 ><DT
216 >Returns</DT
217 ><DD
218 ><P
219 >A connection instance of the specified driver, or NULL if there was an error.</P
220 ></DD
221 ></DL
222 ></DIV
223 ></DIV
224 ><DIV
225 CLASS="SECTION"
226 ><H2
227 CLASS="SECTION"
228 ><A
229 NAME="DBI-CONN-OPEN"
230 >7.3.3. dbi_conn_open</A
231 ></H2
232 ><DIV
233 CLASS="FUNCSYNOPSIS"
234 ><P
235 ></P
236 ><A
237 NAME="AEN1162"
238 ></A
239 ><P
240 ><CODE
241 ><CODE
242 CLASS="FUNCDEF"
243 >dbi_conn <B
244 CLASS="FSFUNC"
245 >dbi_conn_open</B
246 ></CODE
247 >(dbi_driver <VAR
248 CLASS="PDPARAM"
249 >Driver</VAR
250 >);</CODE
251 ></P
252 ><P
253 ></P
254 ></DIV
255 ><P
256 >Creates a connection instance of the specified driver. This connection can be used to perform queries and set options.</P
257 ><P
258 ></P
259 ><DIV
260 CLASS="VARIABLELIST"
261 ><DL
262 ><DT
263 >Arguments</DT
264 ><DD
265 ><P
266 ><TT
267 CLASS="LITERAL"
268 >Driver</TT
269 >: The target driver.</P
270 ></DD
271 ><DT
272 >Returns</DT
273 ><DD
274 ><P
275 >A connection instance of the specified driver, or NULL if there was an error.</P
276 ></DD
277 ></DL
278 ></DIV
279 ></DIV
280 ><DIV
281 CLASS="SECTION"
282 ><H2
283 CLASS="SECTION"
284 ><A
285 NAME="DBI-CONN-CLOSE"
286 >7.3.4. dbi_conn_close</A
287 ></H2
288 ><DIV
289 CLASS="FUNCSYNOPSIS"
290 ><P
291 ></P
292 ><A
293 NAME="AEN1181"
294 ></A
295 ><P
296 ><CODE
297 ><CODE
298 CLASS="FUNCDEF"
299 >void <B
300 CLASS="FSFUNC"
301 >dbi_conn_close</B
302 ></CODE
303 >(dbi_conn <VAR
304 CLASS="PDPARAM"
305 >Conn</VAR
306 >);</CODE
307 ></P
308 ><P
309 ></P
310 ></DIV
311 ><P
312 >Disconnects the specified connection connection from the database and cleans up the connection session.</P
313 ><P
314 ></P
315 ><DIV
316 CLASS="VARIABLELIST"
317 ><DL
318 ><DT
319 >Arguments</DT
320 ><DD
321 ><P
322 ><TT
323 CLASS="LITERAL"
324 >Conn</TT
325 >: The target connection.</P
326 ></DD
327 ></DL
328 ></DIV
329 ></DIV
330 ><DIV
331 CLASS="SECTION"
332 ><H2
333 CLASS="SECTION"
334 ><A
335 NAME="DBI-CONN-GET-DRIVER"
336 >7.3.5. dbi_conn_get_driver</A
337 ></H2
338 ><DIV
339 CLASS="FUNCSYNOPSIS"
340 ><P
341 ></P
342 ><A
343 NAME="AEN1196"
344 ></A
345 ><P
346 ><CODE
347 ><CODE
348 CLASS="FUNCDEF"
349 >dbi_driver <B
350 CLASS="FSFUNC"
351 >dbi_conn_get_driver</B
352 ></CODE
353 >(dbi_conn <VAR
354 CLASS="PDPARAM"
355 >Conn</VAR
356 >);</CODE
357 ></P
358 ><P
359 ></P
360 ></DIV
361 ><P
362 >Returns the driver type of the specified connection.</P
363 ><P
364 ></P
365 ><DIV
366 CLASS="VARIABLELIST"
367 ><DL
368 ><DT
369 >Arguments</DT
370 ><DD
371 ><P
372 ><TT
373 CLASS="LITERAL"
374 >Conn</TT
375 >: The target connection.</P
376 ></DD
377 ><DT
378 >Returns</DT
379 ><DD
380 ><P
381 >The driver type of the target connection.</P
382 ></DD
383 ></DL
384 ></DIV
385 ></DIV
386 ><DIV
387 CLASS="SECTION"
388 ><H2
389 CLASS="SECTION"
390 ><A
391 NAME="DBI-CONN-SET-OPTION"
392 >7.3.6. dbi_conn_set_option</A
393 ></H2
394 ><DIV
395 CLASS="FUNCSYNOPSIS"
396 ><P
397 ></P
398 ><A
399 NAME="AEN1215"
400 ></A
401 ><P
402 ><CODE
403 ><CODE
404 CLASS="FUNCDEF"
405 >int <B
406 CLASS="FSFUNC"
407 >dbi_conn_set_option</B
408 ></CODE
409 >(dbi_conn <VAR
410 CLASS="PDPARAM"
411 >Conn</VAR
412 >, const char *<VAR
413 CLASS="PDPARAM"
414 >key</VAR
415 >, char *<VAR
416 CLASS="PDPARAM"
417 >value</VAR
418 >);</CODE
419 ></P
420 ><P
421 ></P
422 ></DIV
423 ><P
424 >Sets a specified connection option to a string value.</P
425 ><P
426 ></P
427 ><DIV
428 CLASS="VARIABLELIST"
429 ><DL
430 ><DT
431 >Arguments</DT
432 ><DD
433 ><P
434 ><TT
435 CLASS="LITERAL"
436 >Conn</TT
437 >: The target connection.</P
438 ><P
439 ><TT
440 CLASS="LITERAL"
441 >key</TT
442 >: The name of the target setting. Must only contain alphanumerics and the underscore character.</P
443 ><P
444 ><TT
445 CLASS="LITERAL"
446 >value</TT
447 >: The string value of the target setting.</P
448 ></DD
449 ><DT
450 >Returns</DT
451 ><DD
452 ><P
453 >-1 on error, 0 on success. In case of an error, the <A
454 HREF="errornumbers.html"
455 >error number</A
456 > is DBI_ERROR_NOMEM.</P
457 ></DD
458 ></DL
459 ></DIV
460 ></DIV
461 ><DIV
462 CLASS="SECTION"
463 ><H2
464 CLASS="SECTION"
465 ><A
466 NAME="DBI-CONN-SET-OPTION-NUMERIC"
467 >7.3.7. dbi_conn_set_option_numeric</A
468 ></H2
469 ><DIV
470 CLASS="FUNCSYNOPSIS"
471 ><P
472 ></P
473 ><A
474 NAME="AEN1243"
475 ></A
476 ><P
477 ><CODE
478 ><CODE
479 CLASS="FUNCDEF"
480 >int <B
481 CLASS="FSFUNC"
482 >dbi_conn_set_option_numeric</B
483 ></CODE
484 >(dbi_conn <VAR
485 CLASS="PDPARAM"
486 >Conn</VAR
487 >, const char *<VAR
488 CLASS="PDPARAM"
489 >key</VAR
490 >, int <VAR
491 CLASS="PDPARAM"
492 >value</VAR
493 >);</CODE
494 ></P
495 ><P
496 ></P
497 ></DIV
498 ><P
499 >Sets a specified connection option to a numeric value.</P
500 ><P
501 ></P
502 ><DIV
503 CLASS="VARIABLELIST"
504 ><DL
505 ><DT
506 >Arguments</DT
507 ><DD
508 ><P
509 ><TT
510 CLASS="LITERAL"
511 >Conn</TT
512 >: The target connection.</P
513 ><P
514 ><TT
515 CLASS="LITERAL"
516 >key</TT
517 >: The name of the target setting. Must only contain alphanumerics and the underscore character.</P
518 ><P
519 ><TT
520 CLASS="LITERAL"
521 >value</TT
522 >: The numeric value of the target setting.</P
523 ></DD
524 ><DT
525 >Returns</DT
526 ><DD
527 ><P
528 >-1 on error, 0 on success. In case of an error, the <A
529 HREF="errornumbers.html"
530 >error number</A
531 > is DBI_ERROR_NOMEM.</P
532 ></DD
533 ></DL
534 ></DIV
535 ></DIV
536 ><DIV
537 CLASS="SECTION"
538 ><H2
539 CLASS="SECTION"
540 ><A
541 NAME="DBI-CONN-GET-OPTION"
542 >7.3.8. dbi_conn_get_option</A
543 ></H2
544 ><DIV
545 CLASS="FUNCSYNOPSIS"
546 ><P
547 ></P
548 ><A
549 NAME="AEN1271"
550 ></A
551 ><P
552 ><CODE
553 ><CODE
554 CLASS="FUNCDEF"
555 >const char *<B
556 CLASS="FSFUNC"
557 >dbi_conn_get_option</B
558 ></CODE
559 >(dbi_conn <VAR
560 CLASS="PDPARAM"
561 >Conn</VAR
562 >, const char *<VAR
563 CLASS="PDPARAM"
564 >key</VAR
565 >);</CODE
566 ></P
567 ><P
568 ></P
569 ></DIV
570 ><P
571 >Retrieves the string value of the specified option set for a connection if available.</P
572 ><P
573 ></P
574 ><DIV
575 CLASS="VARIABLELIST"
576 ><DL
577 ><DT
578 >Arguments</DT
579 ><DD
580 ><P
581 ><TT
582 CLASS="LITERAL"
583 >Conn</TT
584 >: The target connection.</P
585 ><P
586 ><TT
587 CLASS="LITERAL"
588 >key</TT
589 >: The name of the target setting.</P
590 ></DD
591 ><DT
592 >Returns</DT
593 ><DD
594 ><P
595 >A read-only string with the setting, or NULL if it is not available. It is not considered an error if the setting is not available.</P
596 ></DD
597 ></DL
598 ></DIV
599 ></DIV
600 ><DIV
601 CLASS="SECTION"
602 ><H2
603 CLASS="SECTION"
604 ><A
605 NAME="DBI-CONN-REQUIRE-OPTION"
606 >7.3.9. dbi_conn_require_option</A
607 ></H2
608 ><DIV
609 CLASS="FUNCSYNOPSIS"
610 ><P
611 ></P
612 ><A
613 NAME="AEN1294"
614 ></A
615 ><P
616 ><CODE
617 ><CODE
618 CLASS="FUNCDEF"
619 >const char *<B
620 CLASS="FSFUNC"
621 >dbi_conn_require_option</B
622 ></CODE
623 >(dbi_conn <VAR
624 CLASS="PDPARAM"
625 >Conn</VAR
626 >, const char *<VAR
627 CLASS="PDPARAM"
628 >key</VAR
629 >);</CODE
630 ></P
631 ><P
632 ></P
633 ></DIV
634 ><P
635 >Retrieves the string value of the specified option set for a connection and throws an error if the option was not set.</P
636 ><P
637 ></P
638 ><DIV
639 CLASS="VARIABLELIST"
640 ><DL
641 ><DT
642 >Arguments</DT
643 ><DD
644 ><P
645 ><TT
646 CLASS="LITERAL"
647 >Conn</TT
648 >: The target connection.</P
649 ><P
650 ><TT
651 CLASS="LITERAL"
652 >key</TT
653 >: The name of the target setting.</P
654 ></DD
655 ><DT
656 >Returns</DT
657 ><DD
658 ><P
659 >A read-only string with the setting, or NULL if it is not available. In the latter case, the <A
660 HREF="errornumbers.html"
661 >error number</A
662 > is DBI_ERROR_BADNAME.</P
663 ></DD
664 ></DL
665 ></DIV
666 ></DIV
667 ><DIV
668 CLASS="SECTION"
669 ><H2
670 CLASS="SECTION"
671 ><A
672 NAME="DBI-CONN-GET-OPTION-NUMERIC"
673 >7.3.10. dbi_conn_get_option_numeric</A
674 ></H2
675 ><DIV
676 CLASS="FUNCSYNOPSIS"
677 ><P
678 ></P
679 ><A
680 NAME="AEN1318"
681 ></A
682 ><P
683 ><CODE
684 ><CODE
685 CLASS="FUNCDEF"
686 >int <B
687 CLASS="FSFUNC"
688 >dbi_conn_get_option_numeric</B
689 ></CODE
690 >(dbi_conn <VAR
691 CLASS="PDPARAM"
692 >Conn</VAR
693 >, const char *<VAR
694 CLASS="PDPARAM"
695 >key</VAR
696 >);</CODE
697 ></P
698 ><P
699 ></P
700 ></DIV
701 ><P
702 >Retrieves the integer value of the specified option set for a connection if available.</P
703 ><P
704 ></P
705 ><DIV
706 CLASS="VARIABLELIST"
707 ><DL
708 ><DT
709 >Arguments</DT
710 ><DD
711 ><P
712 ><TT
713 CLASS="LITERAL"
714 >Conn</TT
715 >: The target connection.</P
716 ><P
717 ><TT
718 CLASS="LITERAL"
719 >key</TT
720 >: The name of the target setting.</P
721 ></DD
722 ><DT
723 >Returns</DT
724 ><DD
725 ><P
726 >The value of the setting, or 0 (zero) if it is not available. It is not considered an error if the option has not been set.</P
727 ></DD
728 ></DL
729 ></DIV
730 ></DIV
731 ><DIV
732 CLASS="SECTION"
733 ><H2
734 CLASS="SECTION"
735 ><A
736 NAME="DBI-CONN-REQUIRE-OPTION-NUMERIC"
737 >7.3.11. dbi_conn_require_option_numeric</A
738 ></H2
739 ><DIV
740 CLASS="FUNCSYNOPSIS"
741 ><P
742 ></P
743 ><A
744 NAME="AEN1341"
745 ></A
746 ><P
747 ><CODE
748 ><CODE
749 CLASS="FUNCDEF"
750 >int <B
751 CLASS="FSFUNC"
752 >dbi_conn_require_option_numeric</B
753 ></CODE
754 >(dbi_conn <VAR
755 CLASS="PDPARAM"
756 >Conn</VAR
757 >, const char *<VAR
758 CLASS="PDPARAM"
759 >key</VAR
760 >);</CODE
761 ></P
762 ><P
763 ></P
764 ></DIV
765 ><P
766 >Retrieves the integer value of the specified option set for a connection and throws an error if it is not available.</P
767 ><P
768 ></P
769 ><DIV
770 CLASS="VARIABLELIST"
771 ><DL
772 ><DT
773 >Arguments</DT
774 ><DD
775 ><P
776 ><TT
777 CLASS="LITERAL"
778 >Conn</TT
779 >: The target connection.</P
780 ><P
781 ><TT
782 CLASS="LITERAL"
783 >key</TT
784 >: The name of the target setting.</P
785 ></DD
786 ><DT
787 >Returns</DT
788 ><DD
789 ><P
790 >The value of the setting, or -1 if it is not available. In the latter case, the <A
791 HREF="errornumbers.html"
792 >error number</A
793 > is DBI_ERROR_BADNAME.</P
794 ></DD
795 ></DL
796 ></DIV
797 ></DIV
798 ><DIV
799 CLASS="SECTION"
800 ><H2
801 CLASS="SECTION"
802 ><A
803 NAME="DBI-CONN-GET-OPTION-LIST"
804 >7.3.12. dbi_conn_get_option_list</A
805 ></H2
806 ><DIV
807 CLASS="FUNCSYNOPSIS"
808 ><P
809 ></P
810 ><A
811 NAME="AEN1365"
812 ></A
813 ><P
814 ><CODE
815 ><CODE
816 CLASS="FUNCDEF"
817 >const char *<B
818 CLASS="FSFUNC"
819 >dbi_conn_get_option_list</B
820 ></CODE
821 >(dbi_conn <VAR
822 CLASS="PDPARAM"
823 >Conn</VAR
824 >, const char *<VAR
825 CLASS="PDPARAM"
826 >current</VAR
827 >);</CODE
828 ></P
829 ><P
830 ></P
831 ></DIV
832 ><P
833 >Enumerates the list of available options for a connection. If current is NULL, the first available option will be returned. If current is a valid option name, the next available option will be returned.</P
834 ><P
835 ></P
836 ><DIV
837 CLASS="VARIABLELIST"
838 ><DL
839 ><DT
840 >Arguments</DT
841 ><DD
842 ><P
843 ><TT
844 CLASS="LITERAL"
845 >Conn</TT
846 >: The target connection.</P
847 ><P
848 ><TT
849 CLASS="LITERAL"
850 >current</TT
851 >: The key name of the target option.</P
852 ></DD
853 ><DT
854 >Returns</DT
855 ><DD
856 ><P
857 >The key name of the next option, or NULL if there are no more options or if there was an error. In the latter case the <A
858 HREF="errornumbers.html"
859 >error number</A
860 > is set to DBI_ERROR_BADPTR.</P
861 ></DD
862 ></DL
863 ></DIV
864 ></DIV
865 ><DIV
866 CLASS="SECTION"
867 ><H2
868 CLASS="SECTION"
869 ><A
870 NAME="DBI-CONN-CLEAR-OPTION"
871 >7.3.13. dbi_conn_clear_option</A
872 ></H2
873 ><DIV
874 CLASS="FUNCSYNOPSIS"
875 ><P
876 ></P
877 ><A
878 NAME="AEN1389"
879 ></A
880 ><P
881 ><CODE
882 ><CODE
883 CLASS="FUNCDEF"
884 >void <B
885 CLASS="FSFUNC"
886 >dbi_conn_clear_option</B
887 ></CODE
888 >(dbi_conn <VAR
889 CLASS="PDPARAM"
890 >Conn</VAR
891 >, const char *<VAR
892 CLASS="PDPARAM"
893 >key</VAR
894 >);</CODE
895 ></P
896 ><P
897 ></P
898 ></DIV
899 ><P
900 >Removes the target option setting from a connection. It is not considered an error if the requested option was not set before.</P
901 ><P
902 ></P
903 ><DIV
904 CLASS="VARIABLELIST"
905 ><DL
906 ><DT
907 >Arguments</DT
908 ><DD
909 ><P
910 ><TT
911 CLASS="LITERAL"
912 >Conn</TT
913 >: The target connection.</P
914 ><P
915 ><TT
916 CLASS="LITERAL"
917 >key</TT
918 >: The name of the target setting.</P
919 ></DD
920 ></DL
921 ></DIV
922 ></DIV
923 ><DIV
924 CLASS="SECTION"
925 ><H2
926 CLASS="SECTION"
927 ><A
928 NAME="DBI-CONN-CLEAR-OPTIONS"
929 >7.3.14. dbi_conn_clear_options</A
930 ></H2
931 ><DIV
932 CLASS="FUNCSYNOPSIS"
933 ><P
934 ></P
935 ><A
936 NAME="AEN1408"
937 ></A
938 ><P
939 ><CODE
940 ><CODE
941 CLASS="FUNCDEF"
942 >void <B
943 CLASS="FSFUNC"
944 >dbi_conn_clear_options</B
945 ></CODE
946 >(dbi_conn <VAR
947 CLASS="PDPARAM"
948 >Conn</VAR
949 >);</CODE
950 ></P
951 ><P
952 ></P
953 ></DIV
954 ><P
955 >Removes all option settings from a connection.</P
956 ><P
957 ></P
958 ><DIV
959 CLASS="VARIABLELIST"
960 ><DL
961 ><DT
962 >Arguments</DT
963 ><DD
964 ><P
965 ><TT
966 CLASS="LITERAL"
967 >Conn</TT
968 >: The target connection.</P
969 ></DD
970 ></DL
971 ></DIV
972 ></DIV
973 ><DIV
974 CLASS="SECTION"
975 ><H2
976 CLASS="SECTION"
977 ><A
978 NAME="DBI-CONN-CAP-GET"
979 >7.3.15. dbi_conn_cap_get</A
980 ></H2
981 ><DIV
982 CLASS="FUNCSYNOPSIS"
983 ><P
984 ></P
985 ><A
986 NAME="AEN1423"
987 ></A
988 ><P
989 ><CODE
990 ><CODE
991 CLASS="FUNCDEF"
992 >int <B
993 CLASS="FSFUNC"
994 >dbi_conn_cap_get</B
995 ></CODE
996 >(dbi_conn <VAR
997 CLASS="PDPARAM"
998 >Conn</VAR
999 >, const char *<VAR
1000 CLASS="PDPARAM"
1001 >capname</VAR
1002 >);</CODE
1003 ></P
1004 ><P
1005 ></P
1006 ></DIV
1007 ><P
1008 >Requests the value of a driver capability associated with the current connection. The name of the capability is specified as an argument.</P
1009 ><P
1010 ></P
1011 ><DIV
1012 CLASS="VARIABLELIST"
1013 ><DL
1014 ><DT
1015 >Arguments</DT
1016 ><DD
1017 ><P
1018 ><TT
1019 CLASS="LITERAL"
1020 >Conn</TT
1021 >: The target connection.</P
1022 ><P
1023 ><TT
1024 CLASS="LITERAL"
1025 >capname</TT
1026 >: A pointer to a string containing the name of the driver capability to be queried.</P
1027 ></DD
1028 ><DT
1029 >Returns</DT
1030 ><DD
1031 ><P
1032 >The numeric value of the driver capability.</P
1033 ></DD
1034 ></DL
1035 ></DIV
1036 ></DIV
1037 ><DIV
1038 CLASS="SECTION"
1039 ><H2
1040 CLASS="SECTION"
1041 ><A
1042 NAME="DBI-CONN-GET-SOCKET"
1043 >7.3.16. dbi_conn_get_socket</A
1044 ></H2
1045 ><DIV
1046 CLASS="FUNCSYNOPSIS"
1047 ><P
1048 ></P
1049 ><A
1050 NAME="AEN1446"
1051 ></A
1052 ><P
1053 ><CODE
1054 ><CODE
1055 CLASS="FUNCDEF"
1056 >int <B
1057 CLASS="FSFUNC"
1058 >dbi_conn_get_socket</B
1059 ></CODE
1060 >(dbi_conn <VAR
1061 CLASS="PDPARAM"
1062 >Conn</VAR
1063 >);</CODE
1064 ></P
1065 ><P
1066 ></P
1067 ></DIV
1068 ><P
1069 >Obtain the file descriptor number for the backend connection socket.</P
1070 ><P
1071 ></P
1072 ><DIV
1073 CLASS="VARIABLELIST"
1074 ><DL
1075 ><DT
1076 >Arguments</DT
1077 ><DD
1078 ><P
1079 ><TT
1080 CLASS="LITERAL"
1081 >Conn</TT
1082 >: The target connection</P
1083 ></DD
1084 ><DT
1085 >Returns</DT
1086 ><DD
1087 ><P
1088 >-1 on failure, the file descriptor number on success</P
1089 ></DD
1090 ></DL
1091 ></DIV
1092 ></DIV
1093 ><DIV
1094 CLASS="SECTION"
1095 ><H2
1096 CLASS="SECTION"
1097 ><A
1098 NAME="DBI-CONN-GET-ENCODING"
1099 >7.3.17. dbi_conn_get_encoding</A
1100 ></H2
1101 ><DIV
1102 CLASS="FUNCSYNOPSIS"
1103 ><P
1104 ></P
1105 ><A
1106 NAME="AEN1465"
1107 ></A
1108 ><P
1109 ><CODE
1110 ><CODE
1111 CLASS="FUNCDEF"
1112 >const char *<B
1113 CLASS="FSFUNC"
1114 >dbi_conn_get_encoding</B
1115 ></CODE
1116 >(dbi_conn <VAR
1117 CLASS="PDPARAM"
1118 >Conn</VAR
1119 >);</CODE
1120 ></P
1121 ><P
1122 ></P
1123 ></DIV
1124 ><P
1125 >Requests the character encoding used by the current connection. This may be different from the encoding <A
1126 HREF="reference-conn.html#DBI-CONN-SET-OPTION"
1127 >requested</A
1128 > when the connection was opened, most notably if the connection option was set to "auto".</P
1129 ><P
1130 ></P
1131 ><DIV
1132 CLASS="VARIABLELIST"
1133 ><DL
1134 ><DT
1135 >Arguments</DT
1136 ><DD
1137 ><P
1138 ><TT
1139 CLASS="LITERAL"
1140 >Conn</TT
1141 >: The current encoding.</P
1142 ></DD
1143 ><DT
1144 >Returns</DT
1145 ><DD
1146 ><P
1147 >A string containing the <A
1148 HREF="http://www.iana.org"
1149 TARGET="_top"
1150 >IANA</A
1151 > name of the connection encoding. If the encoding option was set to "auto", the function returns the encoding the database was created with. In all other cases, the current connection encoding is returned, which may be different from the database encoding. Use the <A
1152 HREF="reference-driver.html#DBI-DRIVER-ENCODING-FROM-IANA"
1153 >dbi_driver_encoding_from_iana</A
1154 > function to translate the encoding name to that of the currently used database engine if necessary.</P
1155 ></DD
1156 ></DL
1157 ></DIV
1158 ></DIV
1159 ><DIV
1160 CLASS="SECTION"
1161 ><H2
1162 CLASS="SECTION"
1163 ><A
1164 NAME="DBI-CONN-GET-ENGINE-VERSION-STRING"
1165 >7.3.18. dbi_conn_get_engine_version_string</A
1166 ></H2
1167 ><DIV
1168 CLASS="FUNCSYNOPSIS"
1169 ><P
1170 ></P
1171 ><A
1172 NAME="AEN1487"
1173 ></A
1174 ><P
1175 ><CODE
1176 ><CODE
1177 CLASS="FUNCDEF"
1178 >char *<B
1179 CLASS="FSFUNC"
1180 >dbi_conn_get_engine_version_string</B
1181 ></CODE
1182 >(dbi_conn <VAR
1183 CLASS="PDPARAM"
1184 >Conn</VAR
1185 >, char *<VAR
1186 CLASS="PDPARAM"
1187 >versionstring</VAR
1188 >);</CODE
1189 ></P
1190 ><P
1191 ></P
1192 ></DIV
1193 ><P
1194 >Requests the version of the database engine that serves the current connection as a string.</P
1195 ><P
1196 ></P
1197 ><DIV
1198 CLASS="VARIABLELIST"
1199 ><DL
1200 ><DT
1201 >Arguments</DT
1202 ><DD
1203 ><P
1204 ><TT
1205 CLASS="LITERAL"
1206 >Conn</TT
1207 >: The current connection.</P
1208 ><P
1209 ><TT
1210 CLASS="LITERAL"
1211 >versionstring</TT
1212 >: A string buffer that can hold at least VERSIONSTRING_LENGTH bytes.</P
1213 ></DD
1214 ><DT
1215 >Returns</DT
1216 ><DD
1217 ><P
1218 >A string representation of the version. This will be something like "4.1.10". The result is written to the buffer that <CODE
1219 CLASS="PARAMETER"
1220 >versionstring</CODE
1221 > points to. If successful, the function returns a pointer to that buffer. If the version cannot be determined, the function returns the string "0".</P
1222 ><DIV
1223 CLASS="NOTE"
1224 ><BLOCKQUOTE
1225 CLASS="NOTE"
1226 ><P
1227 ><B
1228 >Note: </B
1229 >This string is useful to display the version to the user. In order to check for particular version requirements in your program, <A
1230 HREF="reference-conn.html#DBI-CONN-GET-ENGINE-VERSION"
1231 >dbi_conn_get_engine_version</A
1232 > is the better choice.</P
1233 ></BLOCKQUOTE
1234 ></DIV
1235 ></DD
1236 ><DT
1237 >Availability</DT
1238 ><DD
1239 ><P
1240 >0.8.0</P
1241 ></DD
1242 ></DL
1243 ></DIV
1244 ></DIV
1245 ><DIV
1246 CLASS="SECTION"
1247 ><H2
1248 CLASS="SECTION"
1249 ><A
1250 NAME="DBI-CONN-GET-ENGINE-VERSION"
1251 >7.3.19. dbi_conn_get_engine_version</A
1252 ></H2
1253 ><DIV
1254 CLASS="FUNCSYNOPSIS"
1255 ><P
1256 ></P
1257 ><A
1258 NAME="AEN1518"
1259 ></A
1260 ><P
1261 ><CODE
1262 ><CODE
1263 CLASS="FUNCDEF"
1264 >unsigned int <B
1265 CLASS="FSFUNC"
1266 >dbi_conn_get_engine_version</B
1267 ></CODE
1268 >(dbi_conn <VAR
1269 CLASS="PDPARAM"
1270 >Conn</VAR
1271 >);</CODE
1272 ></P
1273 ><P
1274 ></P
1275 ></DIV
1276 ><P
1277 >Requests the version of the database engine that serves the current connection in a numeric form.</P
1278 ><P
1279 ></P
1280 ><DIV
1281 CLASS="VARIABLELIST"
1282 ><DL
1283 ><DT
1284 >Arguments</DT
1285 ><DD
1286 ><P
1287 ><TT
1288 CLASS="LITERAL"
1289 >Conn</TT
1290 >: The current connection.</P
1291 ></DD
1292 ><DT
1293 >Returns</DT
1294 ><DD
1295 ><P
1296 >A numeric representation of the version. String representations of the version (e.g. "4.1.10") do not lend themselves to an easy comparison in order to find out whether a particular engine feature is already implemented. For example, a string comparison would claim that "4.1.9" is a later version than "4.1.10". Therefore libdbi computes a numeric representation of the version number [[[[A.]B.]C.]D.]E[.] according to the formula E + D*100 + C*10000 + B*1000000 + A*100000000. The resulting integers (40109 and 40110 in the example above) will be sorted correctly. Returns 0 if the version number cannot be retrieved.</P
1297 ></DD
1298 ><DT
1299 >Availability</DT
1300 ><DD
1301 ><P
1302 >0.8.0</P
1303 ></DD
1304 ></DL
1305 ></DIV
1306 ></DIV
1307 ><DIV
1308 CLASS="SECTION"
1309 ><H2
1310 CLASS="SECTION"
1311 ><A
1312 NAME="REFERENCE-CONN-ERROR"
1313 >7.3.20. Error Handling</A
1314 ></H2
1315 ><DIV
1316 CLASS="SECTION"
1317 ><H3
1318 CLASS="SECTION"
1319 ><A
1320 NAME="DBI-CONN-ERROR"
1321 >7.3.20.1. dbi_conn_error</A
1322 ></H3
1323 ><DIV
1324 CLASS="FUNCSYNOPSIS"
1325 ><P
1326 ></P
1327 ><A
1328 NAME="AEN1543"
1329 ></A
1330 ><P
1331 ><CODE
1332 ><CODE
1333 CLASS="FUNCDEF"
1334 >int <B
1335 CLASS="FSFUNC"
1336 >dbi_conn_error</B
1337 ></CODE
1338 >(dbi_conn <VAR
1339 CLASS="PDPARAM"
1340 >Conn</VAR
1341 >, const char **<VAR
1342 CLASS="PDPARAM"
1343 >errmsg_dest</VAR
1344 >);</CODE
1345 ></P
1346 ><P
1347 ></P
1348 ></DIV
1349 ><P
1350 >Returns a formatted message with the error number and description resulting from the previous database operation.</P
1351 ><P
1352 ></P
1353 ><DIV
1354 CLASS="VARIABLELIST"
1355 ><DL
1356 ><DT
1357 >Arguments</DT
1358 ><DD
1359 ><P
1360 ><TT
1361 CLASS="LITERAL"
1362 >Conn</TT
1363 >: The target connection.</P
1364 ><P
1365 ><TT
1366 CLASS="LITERAL"
1367 >errmsg_dest</TT
1368 >: The target string pointer, which will point to the error message. If NULL, no error message will be created, but the error number will still be returned. This string is managed by libdbi, so it must not be modified or freed. The pointer to the string is only valid until the next call to this function, so make a copy in time if you need to keep the error message.</P
1369 ></DD
1370 ><DT
1371 >Returns</DT
1372 ><DD
1373 ><P
1374 >The error number of the most recent database operation if it resulted in an error. If not, this will return DBI_ERROR_NONE. See <A
1375 HREF="errorhandling.html"
1376 >Chapter 4</A
1377 > for further information.</P
1378 ></DD
1379 ></DL
1380 ></DIV
1381 ></DIV
1382 ><DIV
1383 CLASS="SECTION"
1384 ><H3
1385 CLASS="SECTION"
1386 ><A
1387 NAME="DBI-CONN-ERROR-HANDLER"
1388 >7.3.20.2. dbi_conn_error_handler</A
1389 ></H3
1390 ><DIV
1391 CLASS="FUNCSYNOPSIS"
1392 ><P
1393 ></P
1394 ><A
1395 NAME="AEN1567"
1396 ></A
1397 ><P
1398 ><CODE
1399 ><CODE
1400 CLASS="FUNCDEF"
1401 >void <B
1402 CLASS="FSFUNC"
1403 >dbi_conn_error_handler</B
1404 ></CODE
1405 >(dbi_conn <VAR
1406 CLASS="PDPARAM"
1407 >Conn</VAR
1408 >, dbi_conn_error_handler_func <VAR
1409 CLASS="PDPARAM"
1410 >function</VAR
1411 >, void *<VAR
1412 CLASS="PDPARAM"
1413 >user_argument</VAR
1414 >);</CODE
1415 ></P
1416 ><P
1417 ></P
1418 ></DIV
1419 ><P
1420 > Registers an error handler callback to be triggered whenever the database encounters an error. The callback function should perform as little work as possible, since the state in which it is called can be uncertain. The actual function declaration must accept two parameters (and return nothing):
1421 </P
1422 ><P
1423 ></P
1424 ><UL
1425 ><LI
1426 ><P
1427 >dbi_conn Conn: the connection object that triggered the error, from which dbi_conn_error() can be called, and</P
1428 ></LI
1429 ><LI
1430 ><P
1431 >void *user_argument: a pointer to whatever data (if any) was registered along with the handler.</P
1432 ></LI
1433 ></UL
1434 ><P
1435 > To remove the error handler callback, specify NULL as the function and user_argument.
1436 </P
1437 ><P
1438 ></P
1439 ><DIV
1440 CLASS="VARIABLELIST"
1441 ><DL
1442 ><DT
1443 >Arguments</DT
1444 ><DD
1445 ><P
1446 ><TT
1447 CLASS="LITERAL"
1448 >Conn</TT
1449 >: The target connection.</P
1450 ><P
1451 ><TT
1452 CLASS="LITERAL"
1453 >function</TT
1454 >: A pointer to the function to call when the error handler should be triggered.</P
1455 ><P
1456 ><TT
1457 CLASS="LITERAL"
1458 >user_argument</TT
1459 >: Any data to pass along to the function when it is triggered. Set to NULL if unused.</P
1460 ></DD
1461 ></DL
1462 ></DIV
1463 ></DIV
1464 ><DIV
1465 CLASS="SECTION"
1466 ><H3
1467 CLASS="SECTION"
1468 ><A
1469 NAME="DBI-CONN-ERROR-FLAG"
1470 >7.3.20.3. dbi_conn_error_flag</A
1471 ></H3
1472 ><DIV
1473 CLASS="FUNCSYNOPSIS"
1474 ><P
1475 ></P
1476 ><A
1477 NAME="AEN1596"
1478 ></A
1479 ><P
1480 ><CODE
1481 ><CODE
1482 CLASS="FUNCDEF"
1483 >dbi_error_flag <B
1484 CLASS="FSFUNC"
1485 >dbi_conn_error_flag</B
1486 ></CODE
1487 >(dbi_conn <VAR
1488 CLASS="PDPARAM"
1489 >Conn</VAR
1490 >);</CODE
1491 ></P
1492 ><P
1493 ></P
1494 ></DIV
1495 ><P
1496 >The libdbi query functions set an error flag in order to distinguish e.g. the return value "0" from a "0" returned due to an error condition. Use this function after each query that may fail to read out the error status.</P
1497 ><P
1498 ></P
1499 ><DIV
1500 CLASS="VARIABLELIST"
1501 ><DL
1502 ><DT
1503 ><EM
1504 >Arguments</EM
1505 ></DT
1506 ><DD
1507 ><P
1508 ><TT
1509 CLASS="LITERAL"
1510 >Conn</TT
1511 >: The target connection.</P
1512 ></DD
1513 ><DT
1514 ><EM
1515 >Returns</EM
1516 ></DT
1517 ><DD
1518 ><P
1519 >0 means the previous query finished without errors. A value larger than zero means an error occurred.</P
1520 ></DD
1521 ></DL
1522 ></DIV
1523 ><DIV
1524 CLASS="NOTE"
1525 ><BLOCKQUOTE
1526 CLASS="NOTE"
1527 ><P
1528 ><B
1529 >Note: </B
1530 >This function is deprecated. Use <A
1531 HREF="reference-conn.html#DBI-CONN-ERROR"
1532 >dbi_conn_error</A
1533 > instead. Both functions return the same error code to maintain backwards compatibility.</P
1534 ></BLOCKQUOTE
1535 ></DIV
1536 ></DIV
1537 ><DIV
1538 CLASS="SECTION"
1539 ><H3
1540 CLASS="SECTION"
1541 ><A
1542 NAME="DBI-CONN-SET-ERROR"
1543 >7.3.20.4. dbi_conn_set_error</A
1544 ></H3
1545 ><DIV
1546 CLASS="FUNCSYNOPSIS"
1547 ><P
1548 ></P
1549 ><A
1550 NAME="AEN1620"
1551 ></A
1552 ><P
1553 ><CODE
1554 ><CODE
1555 CLASS="FUNCDEF"
1556 >int <B
1557 CLASS="FSFUNC"
1558 >dbi_conn_set_error</B
1559 ></CODE
1560 >(dbi_conn <VAR
1561 CLASS="PDPARAM"
1562 >Conn</VAR
1563 >, int <VAR
1564 CLASS="PDPARAM"
1565 >errnum</VAR
1566 >, const char <VAR
1567 CLASS="PDPARAM"
1568 >*formatstr</VAR
1569 >, ...);</CODE
1570 ></P
1571 ><P
1572 ></P
1573 ></DIV
1574 ><P
1575 >Applications may set an error status and an error message which are accessible through the libdbi error API function <A
1576 HREF="reference-conn.html#DBI-CONN-ERROR"
1577 >dbi_conn_error</A
1578 >.</P
1579 ><P
1580 ></P
1581 ><DIV
1582 CLASS="VARIABLELIST"
1583 ><DL
1584 ><DT
1585 ><EM
1586 >Arguments</EM
1587 ></DT
1588 ><DD
1589 ><P
1590 ><TT
1591 CLASS="LITERAL"
1592 >Conn</TT
1593 >: The target connection.</P
1594 ><P
1595 ><TT
1596 CLASS="LITERAL"
1597 >errnum</TT
1598 >: An application-defined error code. Applications should use only positive nonzero integers to indicate errors.</P
1599 ><P
1600 >The remainder of the argument list is interpreted using a printf(3)-like syntax to define an error message.</P
1601 ></DD
1602 ><DT
1603 ><EM
1604 >Returns</EM
1605 ></DT
1606 ><DD
1607 ><P
1608 >The length of the error message in bytes, or 0 if there was an error.</P
1609 ></DD
1610 ></DL
1611 ></DIV
1612 ></DIV
1613 ></DIV
1614 ><DIV
1615 CLASS="SECTION"
1616 ><H2
1617 CLASS="SECTION"
1618 ><A
1619 NAME="REFERENCE-CONN-TRANSACTIONS-SAVEPOINTS"
1620 >7.3.21. Transactions and Savepoints</A
1621 ></H2
1622 ><DIV
1623 CLASS="SECTION"
1624 ><H3
1625 CLASS="SECTION"
1626 ><A
1627 NAME="DBI-CONN-TRANSACTION-BEGIN"
1628 >7.3.21.1. dbi_conn_transaction_begin</A
1629 ></H3
1630 ><DIV
1631 CLASS="FUNCSYNOPSIS"
1632 ><P
1633 ></P
1634 ><A
1635 NAME="AEN1652"
1636 ></A
1637 ><P
1638 ><CODE
1639 ><CODE
1640 CLASS="FUNCDEF"
1641 >int <B
1642 CLASS="FSFUNC"
1643 >dbi_conn_transaction_begin</B
1644 ></CODE
1645 >(dbi_conn <VAR
1646 CLASS="PDPARAM"
1647 >Conn</VAR
1648 >);</CODE
1649 ></P
1650 ><P
1651 ></P
1652 ></DIV
1653 ><P
1654 >Starts a transaction.</P
1655 ><P
1656 ></P
1657 ><DIV
1658 CLASS="VARIABLELIST"
1659 ><DL
1660 ><DT
1661 >Arguments</DT
1662 ><DD
1663 ><P
1664 ><TT
1665 CLASS="LITERAL"
1666 >Conn</TT
1667 >: The target connection.</P
1668 ></DD
1669 ><DT
1670 >Returns</DT
1671 ><DD
1672 ><P
1673 >0 (zero) if successful, otherwise nonzero.</P
1674 ></DD
1675 ></DL
1676 ></DIV
1677 ></DIV
1678 ><DIV
1679 CLASS="SECTION"
1680 ><H3
1681 CLASS="SECTION"
1682 ><A
1683 NAME="DBI-CONN-TRANSACTION-COMMIT"
1684 >7.3.21.2. dbi_conn_transaction_commit</A
1685 ></H3
1686 ><DIV
1687 CLASS="FUNCSYNOPSIS"
1688 ><P
1689 ></P
1690 ><A
1691 NAME="AEN1671"
1692 ></A
1693 ><P
1694 ><CODE
1695 ><CODE
1696 CLASS="FUNCDEF"
1697 >int <B
1698 CLASS="FSFUNC"
1699 >dbi_conn_transaction_commit</B
1700 ></CODE
1701 >(dbi_conn <VAR
1702 CLASS="PDPARAM"
1703 >Conn</VAR
1704 >);</CODE
1705 ></P
1706 ><P
1707 ></P
1708 ></DIV
1709 ><P
1710 >Commits a transaction, i.e. writes all changes since the transaction was started to the database.</P
1711 ><P
1712 ></P
1713 ><DIV
1714 CLASS="VARIABLELIST"
1715 ><DL
1716 ><DT
1717 >Arguments</DT
1718 ><DD
1719 ><P
1720 ><TT
1721 CLASS="LITERAL"
1722 >Conn</TT
1723 >: The target connection.</P
1724 ></DD
1725 ><DT
1726 >Returns</DT
1727 ><DD
1728 ><P
1729 >0 (zero) if successful, otherwise nonzero.</P
1730 ></DD
1731 ></DL
1732 ></DIV
1733 ></DIV
1734 ><DIV
1735 CLASS="SECTION"
1736 ><H3
1737 CLASS="SECTION"
1738 ><A
1739 NAME="DBI-CONN-TRANSACTION-ROLLBACK"
1740 >7.3.21.3. dbi_conn_transaction_rollback</A
1741 ></H3
1742 ><DIV
1743 CLASS="FUNCSYNOPSIS"
1744 ><P
1745 ></P
1746 ><A
1747 NAME="AEN1690"
1748 ></A
1749 ><P
1750 ><CODE
1751 ><CODE
1752 CLASS="FUNCDEF"
1753 >int <B
1754 CLASS="FSFUNC"
1755 >dbi_conn_transaction_rollback</B
1756 ></CODE
1757 >(dbi_conn <VAR
1758 CLASS="PDPARAM"
1759 >Conn</VAR
1760 >);</CODE
1761 ></P
1762 ><P
1763 ></P
1764 ></DIV
1765 ><P
1766 >Rolls back a transaction, i.e. reverts all changes since the transaction started.</P
1767 ><P
1768 ></P
1769 ><DIV
1770 CLASS="VARIABLELIST"
1771 ><DL
1772 ><DT
1773 ><EM
1774 >Arguments</EM
1775 ></DT
1776 ><DD
1777 ><P
1778 ><TT
1779 CLASS="LITERAL"
1780 >Conn</TT
1781 >: The target connection.</P
1782 ></DD
1783 ><DT
1784 ><EM
1785 >Returns</EM
1786 ></DT
1787 ><DD
1788 ><P
1789 >0 (zero) if successful, otherwise nonzero.</P
1790 ></DD
1791 ></DL
1792 ></DIV
1793 ></DIV
1794 ><DIV
1795 CLASS="SECTION"
1796 ><H3
1797 CLASS="SECTION"
1798 ><A
1799 NAME="DBI-CONN-SAVEPOINT"
1800 >7.3.21.4. dbi_conn_savepoint</A
1801 ></H3
1802 ><DIV
1803 CLASS="FUNCSYNOPSIS"
1804 ><P
1805 ></P
1806 ><A
1807 NAME="AEN1711"
1808 ></A
1809 ><P
1810 ><CODE
1811 ><CODE
1812 CLASS="FUNCDEF"
1813 >int <B
1814 CLASS="FSFUNC"
1815 >dbi_conn_savepoint</B
1816 ></CODE
1817 >(dbi_conn <VAR
1818 CLASS="PDPARAM"
1819 >Conn</VAR
1820 >, const char *<VAR
1821 CLASS="PDPARAM"
1822 >savepoint</VAR
1823 >);</CODE
1824 ></P
1825 ><P
1826 ></P
1827 ></DIV
1828 ><P
1829 >Sets a savepoint named <CODE
1830 CLASS="PARAMETER"
1831 >savepoint</CODE
1832 > within the current transaction.</P
1833 ><P
1834 ></P
1835 ><DIV
1836 CLASS="VARIABLELIST"
1837 ><DL
1838 ><DT
1839 ><EM
1840 >Arguments</EM
1841 ></DT
1842 ><DD
1843 ><P
1844 ><TT
1845 CLASS="LITERAL"
1846 >Conn</TT
1847 >: The target connection.</P
1848 ><P
1849 ><TT
1850 CLASS="LITERAL"
1851 >savepoint</TT
1852 >: a pointer to a string containing the name of the savepoint.</P
1853 ></DD
1854 ><DT
1855 ><EM
1856 >Returns</EM
1857 ></DT
1858 ><DD
1859 ><P
1860 >0 (zero) if successful, otherwise nonzero.</P
1861 ></DD
1862 ></DL
1863 ></DIV
1864 ></DIV
1865 ><DIV
1866 CLASS="SECTION"
1867 ><H3
1868 CLASS="SECTION"
1869 ><A
1870 NAME="DBI-CONN-ROLLBACK-TO-SAVEPOINT"
1871 >7.3.21.5. dbi_conn_rollback_to_savepoint</A
1872 ></H3
1873 ><DIV
1874 CLASS="FUNCSYNOPSIS"
1875 ><P
1876 ></P
1877 ><A
1878 NAME="AEN1737"
1879 ></A
1880 ><P
1881 ><CODE
1882 ><CODE
1883 CLASS="FUNCDEF"
1884 >int <B
1885 CLASS="FSFUNC"
1886 >dbi_conn_rollback_to_savepoint</B
1887 ></CODE
1888 >(dbi_conn <VAR
1889 CLASS="PDPARAM"
1890 >Conn</VAR
1891 >, const char *<VAR
1892 CLASS="PDPARAM"
1893 >savepoint</VAR
1894 >);</CODE
1895 ></P
1896 ><P
1897 ></P
1898 ></DIV
1899 ><P
1900 >Rolls back all changes since the savepoint named <CODE
1901 CLASS="PARAMETER"
1902 >savepoint</CODE
1903 > was established within the current transaction.</P
1904 ><P
1905 ></P
1906 ><DIV
1907 CLASS="VARIABLELIST"
1908 ><DL
1909 ><DT
1910 ><EM
1911 >Arguments</EM
1912 ></DT
1913 ><DD
1914 ><P
1915 ><TT
1916 CLASS="LITERAL"
1917 >Conn</TT
1918 >: The target connection.</P
1919 ><P
1920 ><TT
1921 CLASS="LITERAL"
1922 >savepoint</TT
1923 >: a pointer to a string containing the name of the savepoint.</P
1924 ></DD
1925 ><DT
1926 ><EM
1927 >Returns</EM
1928 ></DT
1929 ><DD
1930 ><P
1931 >0 (zero) if successful, otherwise nonzero.</P
1932 ></DD
1933 ></DL
1934 ></DIV
1935 ></DIV
1936 ><DIV
1937 CLASS="SECTION"
1938 ><H3
1939 CLASS="SECTION"
1940 ><A
1941 NAME="DBI-CONN-RELEASE-SAVEPOINT"
1942 >7.3.21.6. dbi_conn_release_savepoint</A
1943 ></H3
1944 ><DIV
1945 CLASS="FUNCSYNOPSIS"
1946 ><P
1947 ></P
1948 ><A
1949 NAME="AEN1763"
1950 ></A
1951 ><P
1952 ><CODE
1953 ><CODE
1954 CLASS="FUNCDEF"
1955 >int <B
1956 CLASS="FSFUNC"
1957 >dbi_conn_release_savepoint</B
1958 ></CODE
1959 >(dbi_conn <VAR
1960 CLASS="PDPARAM"
1961 >Conn</VAR
1962 >, const char *<VAR
1963 CLASS="PDPARAM"
1964 >savepoint</VAR
1965 >);</CODE
1966 ></P
1967 ><P
1968 ></P
1969 ></DIV
1970 ><P
1971 >Removes the savepoint named <CODE
1972 CLASS="PARAMETER"
1973 >savepoint</CODE
1974 > within the current transaction and releases all resources associated with it. Changes can no longer be rolled back to that particular savepoint. However, changes may still be rolled back to different savepoints, or to the beginning of the entire transaction.</P
1975 ><P
1976 ></P
1977 ><DIV
1978 CLASS="VARIABLELIST"
1979 ><DL
1980 ><DT
1981 ><EM
1982 >Arguments</EM
1983 ></DT
1984 ><DD
1985 ><P
1986 ><TT
1987 CLASS="LITERAL"
1988 >Conn</TT
1989 >: The target connection.</P
1990 ><P
1991 ><TT
1992 CLASS="LITERAL"
1993 >savepoint</TT
1994 >: a pointer to a string containing the name of the savepoint.</P
1995 ></DD
1996 ><DT
1997 ><EM
1998 >Returns</EM
1999 ></DT
2000 ><DD
2001 ><P
2002 >0 (zero) if successful, otherwise nonzero.</P
2003 ></DD
2004 ></DL
2005 ></DIV
2006 ></DIV
2007 ></DIV
2008 ></DIV
2009 ><DIV
2010 CLASS="NAVFOOTER"
2011 ><HR
2012 ALIGN="LEFT"
2013 WIDTH="100%"><TABLE
2014 SUMMARY="Footer navigation table"
2015 WIDTH="100%"
2016 BORDER="0"
2017 CELLPADDING="0"
2018 CELLSPACING="0"
2019 ><TR
2020 ><TD
2021 WIDTH="33%"
2022 ALIGN="left"
2023 VALIGN="top"
2024 ><A
2025 HREF="reference-driver.html"
2026 ACCESSKEY="P"
2027 >Prev</A
2028 ></TD
2029 ><TD
2030 WIDTH="34%"
2031 ALIGN="center"
2032 VALIGN="top"
2033 ><A
2034 HREF="index.html"
2035 ACCESSKEY="H"
2036 >Home</A
2037 ></TD
2038 ><TD
2039 WIDTH="33%"
2040 ALIGN="right"
2041 VALIGN="top"
2042 ><A
2043 HREF="reference-database.html"
2044 ACCESSKEY="N"
2045 >Next</A
2046 ></TD
2047 ></TR
2048 ><TR
2049 ><TD
2050 WIDTH="33%"
2051 ALIGN="left"
2052 VALIGN="top"
2053 >Driver Infrastructure</TD
2054 ><TD
2055 WIDTH="34%"
2056 ALIGN="center"
2057 VALIGN="top"
2058 ><A
2059 HREF="reference.html"
2060 ACCESSKEY="U"
2061 >Up</A
2062 ></TD
2063 ><TD
2064 WIDTH="33%"
2065 ALIGN="right"
2066 VALIGN="top"
2067 >SQL and Database Infrastructure</TD
2068 ></TR
2069 ></TABLE
2070 ></DIV
2071 ></BODY
2072 ></HTML
2073 >