MySQL :: MySQL 8.4 C API Developer Guide :: 5.4.51 mysql_next_result() (original) (raw)
5.4.51 mysql_next_result()
int
mysql_next_result(MYSQL *mysql)Description
mysql_next_result() is used when you execute multiple statements specified as a single statement string, or when you useCALL 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. Ifmysql_next_result() returns an error, there are no more results.
Before each call tomysql_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 callingmysql_next_result() the state of the connection is as if you had calledmysql_real_query() ormysql_query() for the next statement. This means that you can callmysql_store_result(),mysql_warning_count(),mysql_affected_rows(), and so forth.
If your program uses CALL statements to execute stored procedures, theCLIENT_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. BecauseCALL can return multiple results, process them using a loop that callsmysql_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 theCLIENT_MULTI_RESULTS flag itself, or implicitly by passingCLIENT_MULTI_STATEMENTS (which also enablesCLIENT_MULTI_RESULTS).CLIENT_MULTI_RESULTS is enabled by default.
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 callmysql_next_result() to advance to the next result.
For an example that shows how to usemysql_next_result(), seeSection 3.6.3, “Multiple Statement Execution Support”.
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
- CR_COMMANDS_OUT_OF_SYNC
Commands were executed in an improper order. For example, if you did not callmysql_use_result() for a previous result set. - CR_SERVER_GONE_ERROR
The MySQL server has gone away. - CR_SERVER_LOST
The connection to the server was lost during the query. - CR_UNKNOWN_ERROR
An unknown error occurred.