6.4.23 mysql_stmt_result_metadata()

MYSQL_RES *
mysql_stmt_result_metadata(MYSQL_STMT *stmt)

Description

mysql_stmt_result_metadata() is used to obtain result set metadata for a prepared statement. Its use requires that the statement when executed by mysql_stmt_execute() does produce a result set.

mysql_stmt_result_metadata() may be called after preparing the statement with mysql_stmt_prepare() and before closing the statement handler. The result set metadata returned by mysql_stmt_result_metadata() is in the form of a pointer to a MYSQL_RES structure that can be used to process the meta information such as number of fields and individual field information. This result set pointer can be passed as an argument to any of the field-based API functions that process 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()

If the client has suppressed metadata (as described in Section 3.6.7, “Optional Result Set Metadata”), the MYSQL_RES structure has the field count filled in but is no field information.

When you are done with the metadata result set structure, free it by passing it to mysql_free_result(). This is similar to the way you free a result set structure obtained from a call to mysql_store_result().

If you call mysql_stmt_result_metadata() after mysql_stmt_prepare() but before mysql_stmt_execute(), the column types in the metadata are as determined by the optimizer. If you call mysql_stmt_result_metadata() after mysql_stmt_execute(), the column types in the metadata are as actually present in the result set. In most cases, these should be the same.

If the executed statement is a CALL statement, it may produce multiple result sets. In this case, do not call mysql_stmt_result_metadata() immediately after mysql_stmt_prepare(). Instead, check the metadata for each result set separately after calling mysql_stmt_execute(). For an example of this technique, see Section 3.6.5, “Prepared CALL Statement Support”.

The result set returned by mysql_stmt_result_metadata() contains only metadata. It does not contain any row results. To obtain the row results, use the statement handler with mysql_stmt_fetch() after executing the statement with mysql_stmt_execute(), as usual.

Return Values

A MYSQL_RES result structure. NULL if no meta information exists for the prepared statement.

Errors

• CR_OUT_OF_MEMORY

  Out of memory.

• CR_UNKNOWN_ERROR

  An unknown error occurred.

Example

See the Example in Section 6.4.11, “mysql_stmt_fetch()”.