reference/mysqli/mysqli/multi-query.xml
d470f625f96a83d65464619297cccad7ce46e743
d470f625f96a83d65464619297cccad7ce46e743
...
...
@@ -4,31 +4,67 @@
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
12
<para>&style.oop;</para>
13
-
<methodsynopsis role="oop">
14
-
<type>bool</type><methodname>mysqli::multi_query</methodname>
13
+
<methodsynopsis role="mysqli">
14
+
<modifier>public</modifier> <type>bool</type><methodname>mysqli::multi_query</methodname>
15
15
<methodparam><type>string</type><parameter>query</parameter></methodparam>
16
16
</methodsynopsis>
17
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;
26
27
<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>.
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.
31
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>
47
+
<para>
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.
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,11 +76,8 @@
40
76
<term><parameter>query</parameter></term>
41
77
<listitem>
42
78
<para>
43
-
The query, as a string.
44
-
</para>
45
-
<para>
46
-
Data inside the query should be <link
47
-
linkend="mysqli.real-escape-string">properly escaped</link>.
79
+
A string containing the queries to be executed.
80
+
Multiple queries must be separated by a semicolon.
48
81
</para>
49
82
</listitem>
50
83
</varlistentry>
...
...
@@ -61,6 +94,11 @@
61
94
</para>
62
95
</refsect1>
63
96
97
+
<refsect1 role="errors">
98
+
&reftitle.errors;
99
+
&mysqli.conditionalexception;
100
+
</refsect1>
101
+
64
102
<refsect1 role="examples">
65
103
&reftitle.examples;
66
104
<example>
...
...
@@ -69,74 +107,54 @@
69
107
<programlisting role="php">
70
108
<![CDATA[
71
109
<?php
72
-
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
73
110
74
-
/* check connection */
75
-
if (mysqli_connect_errno()) {
76
-
printf("Connect failed: %s\n", mysqli_connect_error());
77
-
exit();
78
-
}
111
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
112
+
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
79
113
80
-
$query = "SELECT CURRENT_USER();";
114
+
$query = "SELECT CURRENT_USER();";
81
115
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";
82
116
83
117
/* execute multi query */
84
-
if ($mysqli->multi_query($query)) {
85
-
do {
86
-
/* store first result set */
87
-
if ($result = $mysqli->store_result()) {
88
-
while ($row = $result->fetch_row()) {
89
-
printf("%s\n", $row[0]);
90
-
}
91
-
$result->free();
92
-
}
93
-
/* print divider */
94
-
if ($mysqli->more_results()) {
95
-
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]);
96
124
}
97
-
} while ($mysqli->next_result());
98
-
}
99
-
100
-
/* close connection */
101
-
$mysqli->close();
102
-
?>
125
+
}
126
+
/* print divider */
127
+
if ($mysqli->more_results()) {
128
+
printf("-----------------\n");
129
+
}
130
+
} while ($mysqli->next_result());
103
131
]]>
104
132
</programlisting>
105
133
<para>&style.procedural;</para>
106
134
<programlisting role="php">
107
135
<![CDATA[
108
136
<?php
109
-
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
110
137
111
-
/* check connection */
112
-
if (mysqli_connect_errno()) {
113
-
printf("Connect failed: %s\n", mysqli_connect_error());
114
-
exit();
115
-
}
138
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
139
+
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
116
140
117
-
$query = "SELECT CURRENT_USER();";
141
+
$query = "SELECT CURRENT_USER();";
118
142
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";
119
143
120
144
/* execute multi query */
121
-
if (mysqli_multi_query($link, $query)) {
122
-
do {
123
-
/* store first result set */
124
-
if ($result = mysqli_store_result($link)) {
125
-
while ($row = mysqli_fetch_row($result)) {
126
-
printf("%s\n", $row[0]);
127
-
}
128
-
mysqli_free_result($result);
129
-
}
130
-
/* print divider */
131
-
if (mysqli_more_results($link)) {
132
-
printf("-----------------\n");
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]);
133
151
}
134
-
} while (mysqli_next_result($link));
135
-
}
136
-
137
-
/* close connection */
138
-
mysqli_close($link);
139
-
?>
152
+
}
153
+
/* print divider */
154
+
if (mysqli_more_results($link)) {
155
+
printf("-----------------\n");
156
+
}
157
+
} while (mysqli_next_result($link));
140
158
]]>
141
159
</programlisting>
142
160
&examples.outputs.similar;
...
...
@@ -168,7 +186,6 @@ Haarlemmermeer
168
186
</refsect1>
169
187
170
188
</refentry>
171
-
172
189
<!-- Keep this comment at the end of the file
173
190
Local variables:
174
191
mode: sgml
175
192