php-doc-en/reference/mysqli/functions/mysqli-use-result.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.12 $ -->
  <refentry id="function.mysqli-use-result">
   <refnamediv>
    <refname>mysqli_use_result</refname>
    <refname>mysqli->use_result</refname>
    <refpurpose>Initiate a result set retrieval</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <para>Procedural style:</para>
    <methodsynopsis>
     <type>mysqli_result</type><methodname>mysqli_use_result</methodname>
     <methodparam><type>mysqli</type><parameter>link</parameter></methodparam>
    </methodsynopsis>
    <para>Object oriented style (method):</para>
    <classsynopsis>
     <ooclass><classname>mysqli</classname></ooclass>
     <methodsynopsis>
      <type>mysqli_result</type><methodname>use_result</methodname>
      <void />
     </methodsynopsis>
    </classsynopsis>
    <para>
     <function>mysqli_use_result</function> is used to initiate the retrieval
     of a result set from the last query executed using the
     <function>mysqli_real_query</function> function on the database connection
     specified by the <parameter>link</parameter> parameter. Either this or the
     <function>mysqli_store_result</function> function must be called before the
     results of a query can be retrieved, and one or the other must be called
     to prevent the next query on that database connection from failing.
    </para>
    <note>
     <para>
      The <function>mysqli_use_result</function> function does not transfer
      the entire result set from the database and hence cannot be used functions
      such as <function>mysqli_data_seek</function> to move to a particular
      row within the set. To use this functionality, the result set must be
      stored using <function>mysqli_store_result</function>. One should not
      use <function>mysqli_use_result</function> if a lot of processing on
      the client side is performed, since this will tie up the server and
      prevent other threads from updating any tables from which the data is
      being fetched.
     </para>
    </note>
   </refsect1>
   <refsect1>
    &reftitle.returnvalues;
    <para>
     Returns an unbuffered result object or &false; if an error occurred.
    </para>
   </refsect1>
   <refsect1>
    &reftitle.seealso;
    <para>
     <function>mysqli_real_query</function>&listendand;
     <function>mysqli_store_result</function>.
    </para>
   </refsect1>
   <refsect1>
    &reftitle.examples;
    <example>
     <title>Object oriented style</title>
     <programlisting role="php">
<![CDATA[
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* check connection */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

$query  = "SELECT CURRENT_USER();";
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

/* execute multi query */
if ($mysqli->multi_query($query)) {
    do {
        /* store first result set */
        if ($result = $mysqli->use_result()) {
            while ($row = $result->fetch_row()) {
                printf("%s\n", $row[0]);
            }
            $result->close();
        }
        /* print divider */
        if ($mysqli->more_results()) {
            printf("-----------------\n");
        }
    } while ($mysqli->next_result());
}

/* close connection */
$mysqli->close();
?>
]]>
    </programlisting>
    </example>
    <example>
     <title>Procedural style</title>
     <programlisting role="php">
<![CDATA[
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* check connection */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

$query  = "SELECT CURRENT_USER();";
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

/* execute multi query */
if (mysqli_multi_query($link, $query)) {
    do {
        /* store first result set */
        if ($result = mysqli_use_result($link)) {
            while ($row = mysqli_fetch_row($result)) {
                printf("%s\n", $row[0]);
            }
            mysqli_free_result($result);
        }
        /* print divider */
        if (mysqli_more_results($link)) {
            printf("-----------------\n");
        }
    } while (mysqli_next_result($link));
}

/* close connection */
mysqli_close($link);
?>
]]>
     </programlisting>
    </example>
    &example.outputs;
    <screen>
<![CDATA[
my_user@localhost
-----------------
Amersfoort
Maastricht
Dordrecht
Leiden
Haarlemmermeer
]]>
    </screen>
   </refsect1>
  </refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->