<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <HTML ><HEAD ><TITLE >Managing Results</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK REL="HOME" TITLE="Database Independent Abstraction Layer for C" HREF="index.html"><LINK REL="UP" TITLE="libdbi API Reference" HREF="reference.html"><LINK REL="PREVIOUS" TITLE="Managing Queries" HREF="reference-query.html"><LINK REL="NEXT" TITLE="Retrieving Field Meta-data" HREF="reference-field-meta.html"></HEAD ><BODY CLASS="SECTION" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >Database Independent Abstraction Layer for C: libdbi Programmer's Guide</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="reference-query.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" >Chapter 7. libdbi API Reference</TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="reference-field-meta.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="SECTION" ><H1 CLASS="SECTION" ><A NAME="REFERENCE-RESULTS" >7.6. Managing Results</A ></H1 ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-CONN" >7.6.1. dbi_result_get_conn</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2261" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >dbi_conn <B CLASS="FSFUNC" >dbi_result_get_conn</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the connection belonging to the specified result object.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ></DD ><DT >Returns</DT ><DD ><P >The connection belonging to the target query result.If an error occurs, the return value is NULL, and the <A HREF="errornumbers.html" >error number</A > is set to DBI_ERROR_BADPTR.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-FREE" >7.6.2. dbi_result_free</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2281" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >int <B CLASS="FSFUNC" >dbi_result_free</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >);</CODE ></P ><P ></P ></DIV ><P >Frees the result's query, disables all stored field bindings, and releases internally stored variables.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ></DD ><DT >Returns</DT ><DD ><P >-1 on failure, zero on success. If a failure was caused by the database client library, the <A HREF="errornumbers.html" >error number</A > is set to the database engine-specific nonzero error code.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-SEEK-ROW" >7.6.3. dbi_result_seek_row</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2301" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >int <B CLASS="FSFUNC" >dbi_result_seek_row</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >, unsigned long long <VAR CLASS="PDPARAM" >rowidx</VAR >);</CODE ></P ><P ></P ></DIV ><P >Jump to a specific row in a result set.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ><P ><TT CLASS="LITERAL" >rowidx</TT >: The ordinal number of the row to seek to. The first row is at position 1, not zero.</P ></DD ><DT >Returns</DT ><DD ><P >1 if successful, or 0 if there was an error. In the latter case, the <A HREF="errornumbers.html" >error number</A > is one of DBI_ERROR_BADPTR, DBI_ERROR_BADIDX, or a database engine-specific nonzero value.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-FIRST-ROW" >7.6.4. dbi_result_first_row</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2325" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >int <B CLASS="FSFUNC" >dbi_result_first_row</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >);</CODE ></P ><P ></P ></DIV ><P >Jump to the first row in a result set.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ></DD ><DT >Returns</DT ><DD ><P >1 if successful, or 0 if there was an error. In the latter case, the <A HREF="errornumbers.html" >error number</A > is one of DBI_ERROR_BADPTR, DBI_ERROR_BADIDX, or a database engine-specific nonzero value.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-LAST-ROW" >7.6.5. dbi_result_last_row</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2345" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >int <B CLASS="FSFUNC" >dbi_result_last_row</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >);</CODE ></P ><P ></P ></DIV ><P >Jump to the last row in a result set.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ></DD ><DT >Returns</DT ><DD ><P >1 if successful, or 0 if there was an error. In the latter case, the <A HREF="errornumbers.html" >error number</A > is one of DBI_ERROR_BADPTR, DBI_ERROR_BADIDX, or a database engine-specific nonzero value.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-PREV-ROW" >7.6.6. dbi_result_prev_row</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2365" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >int <B CLASS="FSFUNC" >dbi_result_prev_row</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >);</CODE ></P ><P ></P ></DIV ><P >Jump to the previous row in a result set.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ></DD ><DT >Returns</DT ><DD ><P >1 if successful, or 0 if there is an error. In the latter case, the <A HREF="errornumbers.html" >error number</A > is one of DBI_ERROR_BADPTR, DBI_ERROR_BADIDX, or a database engine-specific nonzero value.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-NEXT-ROW" >7.6.7. dbi_result_next_row</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2385" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >int <B CLASS="FSFUNC" >dbi_result_next_row</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >);</CODE ></P ><P ></P ></DIV ><P >Jump to the next row in a result set.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ></DD ><DT >Returns</DT ><DD ><P >1 if successful, or 0 if there was an error. In the latter case, the <A HREF="errornumbers.html" >error number</A > is one of DBI_ERROR_BADPTR, DBI_ERROR_BADIDX, or a database engine-specific nonzero value.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-CURROW" >7.6.8. dbi_result_get_currow</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2405" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >unsigned long long <B CLASS="FSFUNC" >dbi_result_get_currow</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the ordinal number of the current row in the specified result set.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ></DD ><DT >Returns</DT ><DD ><P >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 HREF="errornumbers.html" >error number</A > is DBI_ERROR_BADPTR.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-NUMROWS" >7.6.9. dbi_result_get_numrows</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2425" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >unsigned long long <B CLASS="FSFUNC" >dbi_result_get_numrows</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >);</CODE ></P ><P ></P ></DIV ><P >Returns the number of rows in the specified result set.</P ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ></DD ><DT >Returns</DT ><DD ><P >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 HREF="errornumbers.html" >error number</A > is DBI_ERROR_BADPTR.</P ></DD ></DL ></DIV ></DIV ><DIV CLASS="SECTION" ><H2 CLASS="SECTION" ><A NAME="DBI-RESULT-GET-NUMROWS-AFFECTED" >7.6.10. dbi_result_get_numrows_affected</A ></H2 ><DIV CLASS="FUNCSYNOPSIS" ><P ></P ><A NAME="AEN2445" ></A ><P ><CODE ><CODE CLASS="FUNCDEF" >unsigned long long <B CLASS="FSFUNC" >dbi_result_get_numrows_affected</B ></CODE >(dbi_result <VAR CLASS="PDPARAM" >Result</VAR >);</CODE ></P ><P ></P ></DIV ><P >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 ><P ></P ><DIV CLASS="VARIABLELIST" ><DL ><DT >Arguments</DT ><DD ><P ><TT CLASS="LITERAL" >Result</TT >: The target query result.</P ></DD ><DT >Returns</DT ><DD ><P >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 HREF="errornumbers.html" >error number</A > is DBI_ERROR_BADPTR.</P ></DD ></DL ></DIV ></DIV ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="reference-query.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="reference-field-meta.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Managing Queries</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="reference.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Retrieving Field Meta-data</TD ></TR ></TABLE ></DIV ></BODY ></HTML >