reference/mysqli/mysqli/multi-query.xml
d470f625f96a83d65464619297cccad7ce46e743
d470f625f96a83d65464619297cccad7ce46e743
...
...
@@ -1,34 +1,70 @@
1
-
<?xml version="1.0" encoding="iso-8859-1"?>
1
+
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
3
<refentry xml:id="mysqli.multi-query" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>mysqli::multi_query</refname>
6
6
<refname>mysqli_multi_query</refname>
7
-
<refpurpose>Performs a query on the database</refpurpose>
7
+
<refpurpose>Performs one or more queries on the database</refpurpose>
8
8
</refnamediv>
9
9
10
10
<refsect1 role="description">
11
11
&reftitle.description;
12
-
<para>Object oriented style (method):</para>
13
-
<methodsynopsis>
14
-
<type>bool</type><methodname>mysqli::multi_query</methodname>
15
-
<methodparam><type>string</type><parameter>query</parameter></methodparam>
16
-
</methodsynopsis>
17
-
<para>Procedural style:</para>
12
+
<para>&style.oop;</para>
13
+
<methodsynopsis role="mysqli">
14
+
<modifier>public</modifier> <type>bool</type><methodname>mysqli::multi_query</methodname>
15
+
<methodparam><type>string</type><parameter>query</parameter></methodparam>
16
+
</methodsynopsis>
17
+
<para>&style.procedural;</para>
18
18
<methodsynopsis>
19
19
<type>bool</type><methodname>mysqli_multi_query</methodname>
20
-
<methodparam><type>mysqli</type><parameter>link</parameter></methodparam>
20
+
<methodparam><type>mysqli</type><parameter>mysql</parameter></methodparam>
21
21
<methodparam><type>string</type><parameter>query</parameter></methodparam>
22
22
</methodsynopsis>
23
23
<para>
24
24
Executes one or multiple queries which are concatenated by a semicolon.
25
25
</para>
26
+
&mysqli.sqlinjection.warning;
27
+
<para>
28
+
Queries are sent asynchronously in a single call to the database, but the
29
+
database processes them sequentially.
30
+
<methodname>mysqli_multi_query</methodname> waits for the first query to
31
+
complete before returning control to PHP. The MySQL server will then process
32
+
the next query in the sequence. Once the next result is ready, MySQL will wait
33
+
for the next execution of <function>mysqli_next_result</function> from PHP.
34
+
</para>
35
+
<para>
36
+
It is recommended to use
37
+
<link linkend="control-structures.do.while">do-while</link> to process multiple
38
+
queries. The connection will be busy until all queries have completed and
39
+
their results are fetched to PHP. No other statement can be issued on the
40
+
same connection until all queries are processed.
41
+
To proceed to the next query in the sequence, use
42
+
<function>mysqli_next_result</function>. If the next result is not ready yet,
43
+
mysqli will wait for the response from the MySQL server.
44
+
To check if there are more results,
45
+
use <function>mysqli_more_results</function>.
46
+
</para>
26
47
<para>
27
-
To retrieve the resultset from the first query you can use
28
-
<function>mysqli_use_result</function> or <function>mysqli_store_result</function>.
29
-
All subsequent query results can be processed using
30
-
<function>mysqli_more_results</function> and <function>mysqli_next_result</function>.
48
+
For queries which produce a result set, such as
49
+
<literal>SELECT, SHOW, DESCRIBE</literal> or
50
+
<literal>EXPLAIN</literal>,
51
+
<function>mysqli_use_result</function> or <function>mysqli_store_result</function>
52
+
can be used to retrieve the result set. For queries which do not produce a
53
+
result set, the same functions can be used to retrieve information such as
54
+
the number of affected rows.
31
55
</para>
56
+
<tip>
57
+
<para>
58
+
Executing <literal>CALL</literal> statements for stored procedures can
59
+
produce multiple result sets. If the stored procedure contains
60
+
<literal>SELECT</literal> statements, the result sets are returned in the
61
+
order that they are produced as the procedure executes. In general, the
62
+
caller cannot know how many result sets a procedure will return and must be
63
+
prepared to retrieve multiple results. The final result from the procedure
64
+
is a status result that includes no result set. The status indicates whether
65
+
the procedure succeeded or an error occurred.
66
+
</para>
67
+
</tip>
32
68
</refsect1>
33
69
34
70
<refsect1 role="parameters">
...
...
@@ -40,7 +76,8 @@
40
76
<term><parameter>query</parameter></term>
41
77
<listitem>
42
78
<para>
43
-
The query, as a string.
79
+
A string containing the queries to be executed.
80
+
Multiple queries must be separated by a semicolon.
44
81
</para>
45
82
</listitem>
46
83
</varlistentry>
...
...
@@ -57,88 +94,71 @@
57
94
</para>
58
95
</refsect1>
59
96
97
+
<refsect1 role="errors">
98
+
&reftitle.errors;
99
+
&mysqli.conditionalexception;
100
+
</refsect1>
101
+
60
102
<refsect1 role="examples">
61
103
&reftitle.examples;
62
104
<example>
63
-
<title>Object oriented style</title>
105
+
<title><methodname>mysqli::multi_query</methodname> example</title>
106
+
<para>&style.oop;</para>
64
107
<programlisting role="php">
65
108
<![CDATA[
66
109
<?php
67
-
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
68
110
69
-
/* check connection */
70
-
if (mysqli_connect_errno()) {
71
-
printf("Connect failed: %s\n", mysqli_connect_error());
72
-
exit();
73
-
}
111
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
112
+
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
74
113
75
-
$query = "SELECT CURRENT_USER();";
114
+
$query = "SELECT CURRENT_USER();";
76
115
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";
77
116
78
117
/* execute multi query */
79
-
if ($mysqli->multi_query($query)) {
80
-
do {
81
-
/* store first result set */
82
-
if ($result = $mysqli->store_result()) {
83
-
while ($row = $result->fetch_row()) {
84
-
printf("%s\n", $row[0]);
85
-
}
86
-
$result->free();
87
-
}
88
-
/* print divider */
89
-
if ($mysqli->more_results()) {
90
-
printf("-----------------\n");
118
+
$mysqli->multi_query($query);
119
+
do {
120
+
/* store the result set in PHP */
121
+
if ($result = $mysqli->store_result()) {
122
+
while ($row = $result->fetch_row()) {
123
+
printf("%s\n", $row[0]);
91
124
}
92
-
} while ($mysqli->next_result());
93
-
}
94
-
95
-
/* close connection */
96
-
$mysqli->close();
97
-
?>
125
+
}
126
+
/* print divider */
127
+
if ($mysqli->more_results()) {
128
+
printf("-----------------\n");
129
+
}
130
+
} while ($mysqli->next_result());
98
131
]]>
99
-
</programlisting>
100
-
</example>
101
-
<example>
102
-
<title>Procedural style</title>
132
+
</programlisting>
133
+
<para>&style.procedural;</para>
103
134
<programlisting role="php">
104
135
<![CDATA[
105
136
<?php
106
-
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
107
137
108
-
/* check connection */
109
-
if (mysqli_connect_errno()) {
110
-
printf("Connect failed: %s\n", mysqli_connect_error());
111
-
exit();
112
-
}
138
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
139
+
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
113
140
114
-
$query = "SELECT CURRENT_USER();";
141
+
$query = "SELECT CURRENT_USER();";
115
142
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";
116
143
117
144
/* execute multi query */
118
-
if (mysqli_multi_query($link, $query)) {
119
-
do {
120
-
/* store first result set */
121
-
if ($result = mysqli_store_result($link)) {
122
-
while ($row = mysqli_fetch_row($result)) {
123
-
printf("%s\n", $row[0]);
124
-
}
125
-
mysqli_free_result($result);
145
+
mysqli_multi_query($link, $query);
146
+
do {
147
+
/* store the result set in PHP */
148
+
if ($result = mysqli_store_result($link)) {
149
+
while ($row = mysqli_fetch_row($result)) {
150
+
printf("%s\n", $row[0]);
126
151
}
127
-
/* print divider */
128
-
if (mysqli_more_results($link)) {
129
-
printf("-----------------\n");
130
-
}
131
-
} while (mysqli_next_result($link));
132
-
}
133
-
134
-
/* close connection */
135
-
mysqli_close($link);
136
-
?>
152
+
}
153
+
/* print divider */
154
+
if (mysqli_more_results($link)) {
155
+
printf("-----------------\n");
156
+
}
157
+
} while (mysqli_next_result($link));
137
158
]]>
138
159
</programlisting>
139
-
</example>
140
-
&example.outputs.similar;
141
-
<screen>
160
+
&examples.outputs.similar;
161
+
<screen>
142
162
<![CDATA[
143
163
my_user@localhost
144
164
-----------------
...
...
@@ -148,13 +168,15 @@ Dordrecht
148
168
Leiden
149
169
Haarlemmermeer
150
170
]]>
151
-
</screen>
171
+
</screen>
172
+
</example>
152
173
</refsect1>
153
174
154
175
<refsect1 role="seealso">
155
176
&reftitle.seealso;
156
177
<para>
157
178
<simplelist>
179
+
<member><function>mysqli_query</function></member>
158
180
<member><function>mysqli_use_result</function></member>
159
181
<member><function>mysqli_store_result</function></member>
160
182
<member><function>mysqli_next_result</function></member>
...
...
@@ -164,7 +186,6 @@ Haarlemmermeer
164
186
</refsect1>
165
187
166
188
</refentry>
167
-
168
189
<!-- Keep this comment at the end of the file
169
190
Local variables:
170
191
mode: sgml
...
...
@@ -176,7 +197,7 @@ sgml-indent-step:1
176
197
sgml-indent-data:t
177
198
indent-tabs-mode:nil
178
199
sgml-parent-document:nil
179
-
sgml-default-dtd-file:"../../../../manual.ced"
200
+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
180
201
sgml-exposed-tags:nil
181
202
sgml-local-catalogs:nil
182
203
sgml-local-ecat-files:nil
183
204