use-result.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mysqli.use-result" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>mysqli::use_result</refname>
  <refname>mysqli_use_result</refname>
  <refpurpose>Initiate a result set retrieval</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <para>&style.oop;</para>
  <methodsynopsis role="oop">
   <type>mysqli_result</type><methodname>mysqli::use_result</methodname>
   <void />
  </methodsynopsis>
  <para>&style.procedural;</para>
  <methodsynopsis>
   <type>mysqli_result</type><methodname>mysqli_use_result</methodname>
   <methodparam><type>mysqli</type><parameter>link</parameter></methodparam>
  </methodsynopsis>
  <para>
   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.
  </para>
  <para>
   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 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns an unbuffered result object or &false; if an error occurred.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><methodname>mysqli::use_result</methodname> example</title>
   <para>&style.oop;</para>
   <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>
   <para>&style.procedural;</para>
   <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>
  &examples.outputs;
  <screen>
<![CDATA[
my_user@localhost
-----------------
Amersfoort
Maastricht
Dordrecht
Leiden
Haarlemmermeer
]]>
   </screen>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mysqli_real_query</function></member>
    <member><function>mysqli_store_result</function></member>
   </simplelist>
  </para>
 </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:"~/.phpdoc/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
-->