multi-query.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d470f625f96a83d65464619297cccad7ce46e743 Maintainer: yuanyuqiang Status: ready -->
<!-- CREDITS: mowangjuanzi -->
<refentry xml:id="mysqli.multi-query" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>mysqli::multi_query</refname>
  <refname>mysqli_multi_query</refname>
  <refpurpose>在数据库上执行一个或多个查询</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <para>&style.oop;</para>
  <methodsynopsis role="mysqli">
   <modifier>public</modifier> <type>bool</type><methodname>mysqli::multi_query</methodname>
   <methodparam><type>string</type><parameter>query</parameter></methodparam>
  </methodsynopsis>
  <para>&style.procedural;</para>
  <methodsynopsis>
   <type>bool</type><methodname>mysqli_multi_query</methodname>
   <methodparam><type>mysqli</type><parameter>mysql</parameter></methodparam>
   <methodparam><type>string</type><parameter>query</parameter></methodparam>
  </methodsynopsis>
  <para>
   执行一个或多个由分号分隔的查询。
  </para>
  &mysqli.sqlinjection.warning;
  <para>
   对数据库的单个调用中，查询是异步发送，但数据库会按顺序处理。

   <methodname>mysqli_multi_query</methodname> 在将控制返回给 PHP 之前等待第一个查询完成。MySQL
   服务器将会按照顺序处理下一个查询。一旦下一个结果就绪，MySQL 将等待 PHP 的下一次
   <function>mysqli_next_result</function> 执行。
  </para>
  <para>
   推荐使用 <link linkend="control-structures.do.while">do-while</link> 处理多个查询。在所有查询完成并将结果返回给
   PHP 之前，连接一直处于繁忙状态。在处理完成所有查询之前，不能在同一连接上发出其它语句。要继续处理顺序中的下一个查询，请使用
   <function>mysqli_next_result</function>。如果下一个结果还没准备好，mysqli 就会等待 MySQL
   服务器的响应。要检查是否有更多结果，使用 <function>mysqli_more_results</function>。
  </para>
  <para>
   对于产生查询结果集的查询，比如 <literal>SELECT, SHOW, DESCRIBE</literal> 或 <literal>EXPLAIN</literal>，<function>mysqli_use_result</function>
   或 <function>mysqli_store_result</function> 可用于检索结果集。对于不产生结果集的查询（比如受影响的行数），可以使用相同函数查询。
  </para>
  <tip>
   <para>
    为存储过程执行 <literal>CALL</literal> 语句可以产生多个结果集。如果存储过程包含 <literal>SELECT</literal>
    语句，结果集将按照执行过程中的顺序返回。通常，调用者不会知道过程将返回多少个结果集，必须准备好检索多个结果。该过程的最终结果是不包含结果集的
    status 结果。status 表示过程是成功还是发生错误。
   </para>
  </tip>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    &mysqli.link.description;
    <varlistentry>
     <term><parameter>query</parameter></term>
     <listitem>
      <para>
       包含要执行查询的字符串。多个查询必须用分号分隔。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   如果第一个 SQL 语句就失败了，返回 &false;。要从其它语句中检索后续错误，必须先调用
   <function>mysqli_next_result</function>。
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  &mysqli.conditionalexception;
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><methodname>mysqli::multi_query</methodname> 示例</title>
   <para>&style.oop;</para>
   <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

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

/* 批量执行查询 */
$mysqli->multi_query($query);
do {
    /* store the result set in PHP */
    if ($result = $mysqli->store_result()) {
        while ($row = $result->fetch_row()) {
            printf("%s\n", $row[0]);
        }
    }
    /* print divider */
    if ($mysqli->more_results()) {
        printf("-----------------\n");
    }
} while ($mysqli->next_result());
]]>
   </programlisting>
   <para>&style.procedural;</para>
   <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

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

/* 批量执行查询 */
mysqli_multi_query($link, $query);
do {
    /* store the result set in PHP */
    if ($result = mysqli_store_result($link)) {
        while ($row = mysqli_fetch_row($result)) {
            printf("%s\n", $row[0]);
        }
    }
    /* print divider */
    if (mysqli_more_results($link)) {
        printf("-----------------\n");
    }
} while (mysqli_next_result($link));
]]>
   </programlisting>
   &examples.outputs.similar;
   <screen>
<![CDATA[
my_user@localhost
-----------------
Amersfoort
Maastricht
Dordrecht
Leiden
Haarlemmermeer
]]>
   </screen>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mysqli_query</function></member>
    <member><function>mysqli_use_result</function></member>
    <member><function>mysqli_store_result</function></member>
    <member><function>mysqli_next_result</function></member>
    <member><function>mysqli_more_results</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
-->