<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.mysql-unbuffered-query" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>mysql_unbuffered_query</refname>
  <refpurpose>Send an SQL query to MySQL without fetching and buffering the result rows</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <warning>
   &mysql.alternative.note;
   <simplelist role="alternatives">
    <member>See: <link linkend="mysqlinfo.concepts.buffering">Buffered and Unbuffered queries</link></member>
   </simplelist>
  </warning>
 </refsynopsisdiv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>resource</type><methodname>mysql_unbuffered_query</methodname>
   <methodparam><type>string</type><parameter>query</parameter></methodparam>
   <methodparam choice="opt"><type>resource</type><parameter>link_identifier</parameter><initializer>NULL</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>mysql_unbuffered_query</function> sends the SQL query
   <parameter>query</parameter> to MySQL without automatically
   fetching and buffering the result rows as
   <function>mysql_query</function> does.  This saves a considerable
   amount of memory with SQL queries that produce large result sets,
   and you can start working on the result set immediately after the
   first row has been retrieved as you don't have to wait until the
   complete SQL query has been performed.  To use
   <function>mysql_unbuffered_query</function> while multiple database
   connections are open, you must specify the optional parameter
   <parameter>link_identifier</parameter> to identify which connection
   you want to use.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>query</parameter></term>
     <listitem>
      <para>
       The SQL query to execute.
      </para>
      <para>
       Data inside the query should be <link
       linkend="function.mysql-real-escape-string">properly escaped</link>.
      </para>
     </listitem>
    </varlistentry>
    &mysql.linkid.description;
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   For SELECT, SHOW, DESCRIBE or EXPLAIN statements,
   <function>mysql_unbuffered_query</function> 
   returns a <type>resource</type> on success, or &false; on
   error.
  </para>
  <para>
   For other type of SQL statements, UPDATE, DELETE, DROP, etc,
   <function>mysql_unbuffered_query</function> returns &true; on success
   or &false; on error.
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    The benefits of <function>mysql_unbuffered_query</function> come
    at a cost: you cannot use <function>mysql_num_rows</function> and
    <function>mysql_data_seek</function> on a result set returned from
    <function>mysql_unbuffered_query</function>, until all rows are fetched.
    You also have to fetch all result rows from an unbuffered SQL query
    before you can send a new SQL query to MySQL, using the same
    <parameter>link_identifier</parameter>.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mysql_query</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
-->