6.4.21 mysql_stmt_prepare()

int
mysql_stmt_prepare(MYSQL_STMT *stmt,
                   const char *stmt_str,
                   unsigned long length)

Description

Given the statement handler returned by mysql_stmt_init(), prepares the SQL statement pointed to by the string stmt_str and returns a status value. The string length should be given by the length argument. The string must consist of a single SQL statement. You should not add a terminating semicolon (;) or \g to the statement.

The application can include one or more parameter markers in the SQL statement by embedding question mark (?) characters into the SQL string at the appropriate positions.

The markers are legal only in certain places in SQL statements. For example, they are permitted in the VALUES() list of an INSERT statement (to specify column values for a row), or in a comparison with a column in a WHERE clause to specify a comparison value. However, they are not permitted for identifiers (such as table or column names), or to specify both operands of a binary operator such as the = equal sign. The latter restriction is necessary because it would be impossible to determine the parameter type. In general, parameters are legal only in Data Manipulation Language (DML) statements, and not in Data Definition Language (DDL) statements.

The parameter markers must be bound to application variables using mysql_stmt_bind_param() before executing the statement.

Metadata changes to tables or views referred to by prepared statements are detected and cause automatic repreparation of the statement when it is next executed. For more information, see Caching of Prepared Statements and Stored Programs.

Return Values

Zero for success. Nonzero if an error occurred.

Errors

• CR_COMMANDS_OUT_OF_SYNC

  Commands were executed in an improper order.

• CR_OUT_OF_MEMORY

  Out of memory.

• 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.

If the prepare operation was unsuccessful (that is, mysql_stmt_prepare() returns nonzero), the error message can be obtained by calling mysql_stmt_error().

Example

See the Example in Section 6.4.10, “mysql_stmt_execute()”.