Debian Codegraph @

doc/programmers-guide/reference-results.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 >Managing Results</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="Managing Queries"
17 HREF="reference-query.html"><LINK
18 REL="NEXT"
19 TITLE="Retrieving Field Meta-data"
20 HREF="reference-field-meta.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-query.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-field-meta.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-RESULTS"
77 >7.6. Managing Results</A
78 ></H1
79 ><DIV
80 CLASS="SECTION"
81 ><H2
82 CLASS="SECTION"
83 ><A
84 NAME="DBI-RESULT-GET-CONN"
85 >7.6.1. dbi_result_get_conn</A
86 ></H2
87 ><DIV
88 CLASS="FUNCSYNOPSIS"
89 ><P
90 ></P
91 ><A
92 NAME="AEN2261"
93 ></A
94 ><P
95 ><CODE
96 ><CODE
97 CLASS="FUNCDEF"
98 >dbi_conn <B
99 CLASS="FSFUNC"
100 >dbi_result_get_conn</B
101 ></CODE
102 >(dbi_result <VAR
103 CLASS="PDPARAM"
104 >Result</VAR
105 >);</CODE
106 ></P
107 ><P
108 ></P
109 ></DIV
110 ><P
111 >Returns the connection belonging to the specified result object.</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 >Result</TT
124 >: The target query result.</P
125 ></DD
126 ><DT
127 >Returns</DT
128 ><DD
129 ><P
130 >The connection belonging to the target query result.If an error occurs, the return value is NULL, and the <A
131 HREF="errornumbers.html"
132 >error number</A
133 > is set to DBI_ERROR_BADPTR.</P
134 ></DD
135 ></DL
136 ></DIV
137 ></DIV
138 ><DIV
139 CLASS="SECTION"
140 ><H2
141 CLASS="SECTION"
142 ><A
143 NAME="DBI-RESULT-FREE"
144 >7.6.2. dbi_result_free</A
145 ></H2
146 ><DIV
147 CLASS="FUNCSYNOPSIS"
148 ><P
149 ></P
150 ><A
151 NAME="AEN2281"
152 ></A
153 ><P
154 ><CODE
155 ><CODE
156 CLASS="FUNCDEF"
157 >int <B
158 CLASS="FSFUNC"
159 >dbi_result_free</B
160 ></CODE
161 >(dbi_result <VAR
162 CLASS="PDPARAM"
163 >Result</VAR
164 >);</CODE
165 ></P
166 ><P
167 ></P
168 ></DIV
169 ><P
170 >Frees the result's query, disables all stored field bindings, and releases internally stored variables.</P
171 ><P
172 ></P
173 ><DIV
174 CLASS="VARIABLELIST"
175 ><DL
176 ><DT
177 >Arguments</DT
178 ><DD
179 ><P
180 ><TT
181 CLASS="LITERAL"
182 >Result</TT
183 >: The target query result.</P
184 ></DD
185 ><DT
186 >Returns</DT
187 ><DD
188 ><P
189 >-1 on failure, zero on success. If a failure was caused by the database client library, the <A
190 HREF="errornumbers.html"
191 >error number</A
192 > is set to the database engine-specific nonzero error code.</P
193 ></DD
194 ></DL
195 ></DIV
196 ></DIV
197 ><DIV
198 CLASS="SECTION"
199 ><H2
200 CLASS="SECTION"
201 ><A
202 NAME="DBI-RESULT-SEEK-ROW"
203 >7.6.3. dbi_result_seek_row</A
204 ></H2
205 ><DIV
206 CLASS="FUNCSYNOPSIS"
207 ><P
208 ></P
209 ><A
210 NAME="AEN2301"
211 ></A
212 ><P
213 ><CODE
214 ><CODE
215 CLASS="FUNCDEF"
216 >int <B
217 CLASS="FSFUNC"
218 >dbi_result_seek_row</B
219 ></CODE
220 >(dbi_result <VAR
221 CLASS="PDPARAM"
222 >Result</VAR
223 >, unsigned long long <VAR
224 CLASS="PDPARAM"
225 >rowidx</VAR
226 >);</CODE
227 ></P
228 ><P
229 ></P
230 ></DIV
231 ><P
232 >Jump to a specific row in a result set.</P
233 ><P
234 ></P
235 ><DIV
236 CLASS="VARIABLELIST"
237 ><DL
238 ><DT
239 >Arguments</DT
240 ><DD
241 ><P
242 ><TT
243 CLASS="LITERAL"
244 >Result</TT
245 >: The target query result.</P
246 ><P
247 ><TT
248 CLASS="LITERAL"
249 >rowidx</TT
250 >: The ordinal number of the row to seek to. The first row is at position 1, not zero.</P
251 ></DD
252 ><DT
253 >Returns</DT
254 ><DD
255 ><P
256 >1 if successful, or 0 if there was an error. In the latter case, the <A
257 HREF="errornumbers.html"
258 >error number</A
259 > is one of DBI_ERROR_BADPTR, DBI_ERROR_BADIDX, or a database engine-specific nonzero value.</P
260 ></DD
261 ></DL
262 ></DIV
263 ></DIV
264 ><DIV
265 CLASS="SECTION"
266 ><H2
267 CLASS="SECTION"
268 ><A
269 NAME="DBI-RESULT-FIRST-ROW"
270 >7.6.4. dbi_result_first_row</A
271 ></H2
272 ><DIV
273 CLASS="FUNCSYNOPSIS"
274 ><P
275 ></P
276 ><A
277 NAME="AEN2325"
278 ></A
279 ><P
280 ><CODE
281 ><CODE
282 CLASS="FUNCDEF"
283 >int <B
284 CLASS="FSFUNC"
285 >dbi_result_first_row</B
286 ></CODE
287 >(dbi_result <VAR
288 CLASS="PDPARAM"
289 >Result</VAR
290 >);</CODE
291 ></P
292 ><P
293 ></P
294 ></DIV
295 ><P
296 >Jump to the first row in a result set.</P
297 ><P
298 ></P
299 ><DIV
300 CLASS="VARIABLELIST"
301 ><DL
302 ><DT
303 >Arguments</DT
304 ><DD
305 ><P
306 ><TT
307 CLASS="LITERAL"
308 >Result</TT
309 >: The target query result.</P
310 ></DD
311 ><DT
312 >Returns</DT
313 ><DD
314 ><P
315 >1 if successful, or 0 if there was an error. In the latter case, the <A
316 HREF="errornumbers.html"
317 >error number</A
318 > is one of DBI_ERROR_BADPTR, DBI_ERROR_BADIDX, or a database engine-specific nonzero value.</P
319 ></DD
320 ></DL
321 ></DIV
322 ></DIV
323 ><DIV
324 CLASS="SECTION"
325 ><H2
326 CLASS="SECTION"
327 ><A
328 NAME="DBI-RESULT-LAST-ROW"
329 >7.6.5. dbi_result_last_row</A
330 ></H2
331 ><DIV
332 CLASS="FUNCSYNOPSIS"
333 ><P
334 ></P
335 ><A
336 NAME="AEN2345"
337 ></A
338 ><P
339 ><CODE
340 ><CODE
341 CLASS="FUNCDEF"
342 >int <B
343 CLASS="FSFUNC"
344 >dbi_result_last_row</B
345 ></CODE
346 >(dbi_result <VAR
347 CLASS="PDPARAM"
348 >Result</VAR
349 >);</CODE
350 ></P
351 ><P
352 ></P
353 ></DIV
354 ><P
355 >Jump to the last row in a result set.</P
356 ><P
357 ></P
358 ><DIV
359 CLASS="VARIABLELIST"
360 ><DL
361 ><DT
362 >Arguments</DT
363 ><DD
364 ><P
365 ><TT
366 CLASS="LITERAL"
367 >Result</TT
368 >: The target query result.</P
369 ></DD
370 ><DT
371 >Returns</DT
372 ><DD
373 ><P
374 >1 if successful, or 0 if there was an error. In the latter case, the <A
375 HREF="errornumbers.html"
376 >error number</A
377 > is one of DBI_ERROR_BADPTR, DBI_ERROR_BADIDX, or a database engine-specific nonzero value.</P
378 ></DD
379 ></DL
380 ></DIV
381 ></DIV
382 ><DIV
383 CLASS="SECTION"
384 ><H2
385 CLASS="SECTION"
386 ><A
387 NAME="DBI-RESULT-PREV-ROW"
388 >7.6.6. dbi_result_prev_row</A
389 ></H2
390 ><DIV
391 CLASS="FUNCSYNOPSIS"
392 ><P
393 ></P
394 ><A
395 NAME="AEN2365"
396 ></A
397 ><P
398 ><CODE
399 ><CODE
400 CLASS="FUNCDEF"
401 >int <B
402 CLASS="FSFUNC"
403 >dbi_result_prev_row</B
404 ></CODE
405 >(dbi_result <VAR
406 CLASS="PDPARAM"
407 >Result</VAR
408 >);</CODE
409 ></P
410 ><P
411 ></P
412 ></DIV
413 ><P
414 >Jump to the previous row in a result set.</P
415 ><P
416 ></P
417 ><DIV
418 CLASS="VARIABLELIST"
419 ><DL
420 ><DT
421 >Arguments</DT
422 ><DD
423 ><P
424 ><TT
425 CLASS="LITERAL"
426 >Result</TT
427 >: The target query result.</P
428 ></DD
429 ><DT
430 >Returns</DT
431 ><DD
432 ><P
433 >1 if successful, or 0 if there is an error. In the latter case, the <A
434 HREF="errornumbers.html"
435 >error number</A
436 > is one of DBI_ERROR_BADPTR, DBI_ERROR_BADIDX, or a database engine-specific nonzero value.</P
437 ></DD
438 ></DL
439 ></DIV
440 ></DIV
441 ><DIV
442 CLASS="SECTION"
443 ><H2
444 CLASS="SECTION"
445 ><A
446 NAME="DBI-RESULT-NEXT-ROW"
447 >7.6.7. dbi_result_next_row</A
448 ></H2
449 ><DIV
450 CLASS="FUNCSYNOPSIS"
451 ><P
452 ></P
453 ><A
454 NAME="AEN2385"
455 ></A
456 ><P
457 ><CODE
458 ><CODE
459 CLASS="FUNCDEF"
460 >int <B
461 CLASS="FSFUNC"
462 >dbi_result_next_row</B
463 ></CODE
464 >(dbi_result <VAR
465 CLASS="PDPARAM"
466 >Result</VAR
467 >);</CODE
468 ></P
469 ><P
470 ></P
471 ></DIV
472 ><P
473 >Jump to the next row in a result set.</P
474 ><P
475 ></P
476 ><DIV
477 CLASS="VARIABLELIST"
478 ><DL
479 ><DT
480 >Arguments</DT
481 ><DD
482 ><P
483 ><TT
484 CLASS="LITERAL"
485 >Result</TT
486 >: The target query result.</P
487 ></DD
488 ><DT
489 >Returns</DT
490 ><DD
491 ><P
492 >1 if successful, or 0 if there was an error. In the latter case, the <A
493 HREF="errornumbers.html"
494 >error number</A
495 > is one of DBI_ERROR_BADPTR, DBI_ERROR_BADIDX, or a database engine-specific nonzero value.</P
496 ></DD
497 ></DL
498 ></DIV
499 ></DIV
500 ><DIV
501 CLASS="SECTION"
502 ><H2
503 CLASS="SECTION"
504 ><A
505 NAME="DBI-RESULT-GET-CURROW"
506 >7.6.8. dbi_result_get_currow</A
507 ></H2
508 ><DIV
509 CLASS="FUNCSYNOPSIS"
510 ><P
511 ></P
512 ><A
513 NAME="AEN2405"
514 ></A
515 ><P
516 ><CODE
517 ><CODE
518 CLASS="FUNCDEF"
519 >unsigned long long <B
520 CLASS="FSFUNC"
521 >dbi_result_get_currow</B
522 ></CODE
523 >(dbi_result <VAR
524 CLASS="PDPARAM"
525 >Result</VAR
526 >);</CODE
527 ></P
528 ><P
529 ></P
530 ></DIV
531 ><P
532 >Returns the ordinal number of the current row in the specified result set.</P
533 ><P
534 ></P
535 ><DIV
536 CLASS="VARIABLELIST"
537 ><DL
538 ><DT
539 >Arguments</DT
540 ><DD
541 ><P
542 ><TT
543 CLASS="LITERAL"
544 >Result</TT
545 >: The target query result.</P
546 ></DD
547 ><DT
548 >Returns</DT
549 ><DD
550 ><P
551 >The ordinal number of the row, or 0 if there was an error. The first row has the number 1. In case of an error, the <A
552 HREF="errornumbers.html"
553 >error number</A
554 > is DBI_ERROR_BADPTR.</P
555 ></DD
556 ></DL
557 ></DIV
558 ></DIV
559 ><DIV
560 CLASS="SECTION"
561 ><H2
562 CLASS="SECTION"
563 ><A
564 NAME="DBI-RESULT-GET-NUMROWS"
565 >7.6.9. dbi_result_get_numrows</A
566 ></H2
567 ><DIV
568 CLASS="FUNCSYNOPSIS"
569 ><P
570 ></P
571 ><A
572 NAME="AEN2425"
573 ></A
574 ><P
575 ><CODE
576 ><CODE
577 CLASS="FUNCDEF"
578 >unsigned long long <B
579 CLASS="FSFUNC"
580 >dbi_result_get_numrows</B
581 ></CODE
582 >(dbi_result <VAR
583 CLASS="PDPARAM"
584 >Result</VAR
585 >);</CODE
586 ></P
587 ><P
588 ></P
589 ></DIV
590 ><P
591 >Returns the number of rows in the specified result set.</P
592 ><P
593 ></P
594 ><DIV
595 CLASS="VARIABLELIST"
596 ><DL
597 ><DT
598 >Arguments</DT
599 ><DD
600 ><P
601 ><TT
602 CLASS="LITERAL"
603 >Result</TT
604 >: The target query result.</P
605 ></DD
606 ><DT
607 >Returns</DT
608 ><DD
609 ><P
610 >The number of rows in the result set, which may be 0 if the query did not return any datasets, or DBI_ROW_ERROR in case of an error. In that case, the <A
611 HREF="errornumbers.html"
612 >error number</A
613 > is DBI_ERROR_BADPTR.</P
614 ></DD
615 ></DL
616 ></DIV
617 ></DIV
618 ><DIV
619 CLASS="SECTION"
620 ><H2
621 CLASS="SECTION"
622 ><A
623 NAME="DBI-RESULT-GET-NUMROWS-AFFECTED"
624 >7.6.10. dbi_result_get_numrows_affected</A
625 ></H2
626 ><DIV
627 CLASS="FUNCSYNOPSIS"
628 ><P
629 ></P
630 ><A
631 NAME="AEN2445"
632 ></A
633 ><P
634 ><CODE
635 ><CODE
636 CLASS="FUNCDEF"
637 >unsigned long long <B
638 CLASS="FSFUNC"
639 >dbi_result_get_numrows_affected</B
640 ></CODE
641 >(dbi_result <VAR
642 CLASS="PDPARAM"
643 >Result</VAR
644 >);</CODE
645 ></P
646 ><P
647 ></P
648 ></DIV
649 ><P
650 >Returns the number of rows in the specified result set that were actually modified. Note that not all database servers support this, in which case it will always be zero. See the documentation for each specific driver for details.</P
651 ><P
652 ></P
653 ><DIV
654 CLASS="VARIABLELIST"
655 ><DL
656 ><DT
657 >Arguments</DT
658 ><DD
659 ><P
660 ><TT
661 CLASS="LITERAL"
662 >Result</TT
663 >: The target query result.</P
664 ></DD
665 ><DT
666 >Returns</DT
667 ><DD
668 ><P
669 >The number of modified rows in the result set which may be 0 if no row was affected by the previous query. Also returns 0 if the database engine does not support this feature. The return value will be DBI_ROW_ERROR in case of an error. In case of an error, the <A
670 HREF="errornumbers.html"
671 >error number</A
672 > is DBI_ERROR_BADPTR.</P
673 ></DD
674 ></DL
675 ></DIV
676 ></DIV
677 ></DIV
678 ><DIV
679 CLASS="NAVFOOTER"
680 ><HR
681 ALIGN="LEFT"
682 WIDTH="100%"><TABLE
683 SUMMARY="Footer navigation table"
684 WIDTH="100%"
685 BORDER="0"
686 CELLPADDING="0"
687 CELLSPACING="0"
688 ><TR
689 ><TD
690 WIDTH="33%"
691 ALIGN="left"
692 VALIGN="top"
693 ><A
694 HREF="reference-query.html"
695 ACCESSKEY="P"
696 >Prev</A
697 ></TD
698 ><TD
699 WIDTH="34%"
700 ALIGN="center"
701 VALIGN="top"
702 ><A
703 HREF="index.html"
704 ACCESSKEY="H"
705 >Home</A
706 ></TD
707 ><TD
708 WIDTH="33%"
709 ALIGN="right"
710 VALIGN="top"
711 ><A
712 HREF="reference-field-meta.html"
713 ACCESSKEY="N"
714 >Next</A
715 ></TD
716 ></TR
717 ><TR
718 ><TD
719 WIDTH="33%"
720 ALIGN="left"
721 VALIGN="top"
722 >Managing Queries</TD
723 ><TD
724 WIDTH="34%"
725 ALIGN="center"
726 VALIGN="top"
727 ><A
728 HREF="reference.html"
729 ACCESSKEY="U"
730 >Up</A
731 ></TD
732 ><TD
733 WIDTH="33%"
734 ALIGN="right"
735 VALIGN="top"
736 >Retrieving Field Meta-data</TD
737 ></TR
738 ></TABLE
739 ></DIV
740 ></BODY
741 ></HTML
742 >