mysql_stmt_result_metadata()

mysql_stmt_result_metadata() obtains the result set metadata of a prepared statement.

Syntax

MYSQL_RES *
mysql_stmt_result_metadata(MYSQL_STMT *stmt)

Return values

A MYSQL_RES result structure. If the prepared statement contains no metadata, NULL is returned.

Error messages

• CR_OUT_OF_MEMORY: The memory is insufficient.

• CR_UNKNOWN_ERROR: An unknown error occurred.

Notes

When you call mysql_stmt_result_metadata(), make sure that the statement executed by mysql_stmt_execute() has generated a result set.

You can call mysql_stmt_result_metadata() after mysql_stmt_prepare() prepares the statement and before the statement handle is closed. The metadata of the result set returned by mysql_stmt_result_metadata() is a pointer to the MYSQL_RES structure that can be used to process metadata such as the number of fields and the information of a single field. This result set pointer can be passed as a parameter to any field-based API function that processes the result set metadata, such as:

• mysql_num_fields()

• mysql_fetch_field()

• mysql_fetch_field_direct()

• mysql_fetch_fields()

• mysql_field_count()

• mysql_field_seek()

• mysql_field_tell()

• mysql_free_result()

After you obtain the metadata result set structure, you can call mysql_free_result() to release it. This is similar to releasing the obtained result set structure by calling mysql_store_result() .

If you call mysql_stmt_result_metadata() after mysql_stmt_prepare() but before mysql_stmt_execute(), the types of columns in the metadata are determined by the optimizer. If you call mysql_stmt_result_metadata() after mysql_stmt_execute(), then the types of columns in the metadata are, in most cases, consistent with those in the result set.

If the CALL statement is executed, it may generate multiple result sets. In this case, do not call mysql_stmt_result_metadata() immediately after calling mysql_stmt_prepare(). Instead, you need to call mysql_stmt_execute() and check the metadata of each result set.

The result set returned by mysql_stmt_result_metadata() contains only metadata and does not contain any row results. To obtain the row results, you need to call mysql_stmt_execute() to execute the statement and then use the statement handle containing mysql_stmt_fetch().