int mysql_next_result(MYSQL *mysql)
Description
This function is used when you execute multiple statements
specified as a single statement string, or when you use
CALL
statements to execute stored
procedures, which can return multiple result sets.
mysql_next_result()
reads the
next statement result and returns a status to indicate whether
more results exist. If
mysql_next_result()
returns an
error, there are no more results.
Before each call to
mysql_next_result()
, you must
call mysql_free_result()
for the
current statement if it is a statement that returned a result
set (rather than just a result status).
After calling
mysql_next_result()
the state of
the connection is as if you had called
mysql_real_query()
or
mysql_query()
for the next
statement. This means that you can call
mysql_store_result()
,
mysql_warning_count()
,
mysql_affected_rows()
, and so
forth.
If your program uses CALL
statements to execute stored procedures, the
CLIENT_MULTI_RESULTS
flag must be enabled.
This is because each CALL
returns
a result to indicate the call status, in addition to any result
sets that might be returned by statements executed within the
procedure. Because CALL
can
return multiple results, you should process them using a loop
that calls mysql_next_result()
to determine whether there are more results.
CLIENT_MULTI_RESULTS
can be enabled when you
call mysql_real_connect()
,
either explicitly by passing the
CLIENT_MULTI_RESULTS
flag itself, or
implicitly by passing CLIENT_MULTI_STATEMENTS
(which also enables CLIENT_MULTI_RESULTS
).
It is also possible to test whether there are more results by
calling mysql_more_results()
.
However, this function does not change the connection state, so
if it returns true, you must still call
mysql_next_result()
to advance
to the next result.
For an example that shows how to use
mysql_next_result()
, see
Section 20.9.12, “C API Support for Multiple Statement Execution”.
Return Values
Return Value | Description |
0 | Successful and there are more results |
-1 | Successful and there are no more results |
>0 | An error occurred |
Errors
Commands were executed in an improper order. For example, if
you didn't call
mysql_use_result()
for a
previous result set.
The MySQL server has gone away.
The connection to the server was lost during the query.
An unknown error occurred.
User Comments
Add your own comment.