multi-query.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d470f625f96a83d65464619297cccad7ce46e743 Maintainer: samesch Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="mysqli.multi-query" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>mysqli::multi_query</refname>
  <refname>mysqli_multi_query</refname>
  <refpurpose>Führt eine oder mehrere Abfragen in einer Datenbank durch</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>
   Führt eine oder mehrere Abfragen aus, die durch Semikolons getrennt sind.
  </para>
  &mysqli.sqlinjection.warning;
  <para>
   Die Abfragen werden dabei asynchron in einem einzigen Aufruf an die
   Datenbank gesendet, aber die Datenbank verarbeitet sie sequentiell.
   <methodname>mysqli_multi_query</methodname> wartet, bis die erste Abfrage
   abgeschlossen ist, bevor es die Kontrolle an PHP zurückgibt. Der
   MySQL-Server verarbeitet dann der Reihe nach die nächsten Abfragen. Sobald
   das nächste Ergebnis vorliegt, wartet MySQL darauf, dass die Funktion
   <function>mysqli_next_result</function> von PHP erneut ausgeführt wird.
  </para>
  <para>
   Es wird empfohlen, eine
   <link linkend="control-structures.do.while">do-while</link>-Schleife zu
   verwenden, um mehrere Abfragen zu verarbeiten. Die Verbindung ist so lange
   belegt, bis alle Abfragen abgeschlossen sind und ihre Ergebnisse an PHP
   übermittelt wurden. Solange nicht alle Abfragen abgearbeitet sind, kann
   keine andere Anweisung auf derselben Verbindung ausgeführt werden. Um mit
   der nächsten Abfrage in der Reihenfolge fortzufahren, muss
   <function>mysqli_next_result</function> verwendet werden. Wenn das nächste
   Ergebnis noch nicht bereit ist, wartet mysqli auf die Antwort des
   MySQL-Servers. Um zu prüfen, ob es weitere Ergebnisse gibt, kann
   <function>mysqli_more_results</function> verwendet werden.
  </para>
  <para>
   Bei Abfragen, die eine Ergebnismenge zurückgeben, also zum Beispiel
   <literal>SELECT, SHOW, DESCRIBE</literal> oder <literal>EXPLAIN</literal>,
   können die Funktionen <function>mysqli_use_result</function> oder
   <function>mysqli_store_result</function> verwendet werden, um die
   Ergebnismenge abzurufen. Bei Abfragen, die keine Ergebnismenge zurückgeben,
   können die gleichen Funktionen verwendet werden, um Informationen wie die
   Anzahl der betroffenen Zeilen abzurufen.
  </para>
  <tip>
   <para>
    Wenn <literal>CALL</literal>-Anweisungen für gespeicherte Prozeduren
    ausgeführt werden, können mehrere Ergebnismengen erzeugt werden. Wenn die
    gespeicherte Prozedur <literal>SELECT</literal>-Anweisungen enthält,
    werden die Ergebnismengen in der Reihenfolge zurückgegeben, in der sie bei
    der Ausführung der Prozedur erzeugt werden. Im Allgemeinen kann der
    Aufrufende nicht wissen, wie viele Ergebnismengen eine Prozedur
    zurückgeben wird, und muss damit rechnen, mehrere Ergebnisse abrufen zu
    müssen. Das letzte Ergebnis der Prozedur ist ein Statusergebnis, das keine
    Ergebnismenge enthält. Der Status gibt an, ob die Prozedur erfolgreich war
    oder ein Fehler aufgetreten ist.
   </para>
  </tip>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    &mysqli.link.description;
    <varlistentry>
     <term><parameter>query</parameter></term>
     <listitem>
      <para>
       Eine Zeichenkette mit den Abfragen, die ausgeführt werden sollen.
       Mehrere Abfragen müssen durch ein Semikolon getrennt werden.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Wenn die erste Anweisung fehlgeschlagen ist, wird &false; zurückgegeben. Um
   nachfolgende Fehler von anderen Anweisungen zu erhalten, muss zuerst die
   Funktion <function>mysqli_next_result</function> aufgerufen werden.
  </para>
 </refsect1>

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

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><methodname>mysqli::multi_query</methodname>-Beispiel</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";

/* Mehrfachabfrage ausführen */
$mysqli->multi_query($query);
do {
    /* Ergebnismenge in PHP speichern */
    if ($result = $mysqli->store_result()) {
        while ($row = $result->fetch_row()) {
            printf("%s\n", $row[0]);
        }
    }
    /* Trennlinie ausgeben */
    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";

/* Mehrfachabfrage ausführen */
mysqli_multi_query($link, $query);
do {
    /* Ergebnismenge in PHP speichern */
    if ($result = mysqli_store_result($link)) {
        while ($row = mysqli_fetch_row($result)) {
            printf("%s\n", $row[0]);
        }
    }
    /* Trennlinie ausgeben */
    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
-->