Informix DataBlade API Programmer's Manual DataBlade API Function Descriptions

The mi_exec_prepared_statement() function sends a prepared statement to the database server for execution.

mi_integer mi_exec_prepared_statement(stmt_desc, control, params_are_binary,

n_params, values, lengths, nulls, types, retlen, rettypes)

MI_STATEMENT *stmt_desc;

mi_integer control;

mi_integer params_are_binary;

mi_integer n_params;

MI_DATUM values[];

mi_integer lengths[];

mi_integer nulls[];

mi_string *types[];

mi_integer retlen;

mi_string *rettypes[];

stmt_desc	is a pointer to a statement descriptor for the prepared statement to execute. The mi_prepare() function generates this statement descriptor.
control	is a bit mask of flags that controls the behavior of mi_exec_prepared_statement(). Currently, the valid control flags are:
	MI_BINARY	Return results in binary representation.
	0	Return results in text representation.
params_are_binary		is set to one of the following values:
	1 (MI_TRUE)	The input parameters are passed in their internal (binary) representation.
	0 (MI_FALSE)	The input parameters are passed in their external (text) representation.
n_params	is the number of input parameters in the prepared SQL statement. It is also the number of entries in the input-parameter-value arrays: values, lengths, nulls, and types.
values	is an array of MI_DATUM structures that contain the values of the input parameters in the prepared statement.
lengths	is an array of the lengths (in bytes) of the input-parameter values.
nulls	is an array that indicates whether each input parameter contains an SQL NULL value. Each array element is set to one of the following values:
	1 (MI_TRUE)	The value of the associated input parameter is an SQL NULL value.
	0 (MI_FALSE)	The value of the associated input parameter is not an SQL NULL value.
types	is an array of pointers to the name of the data type for each input parameter. This array can be a NULL-valued pointer.
retlen	is the length of the rettypes array. Currently, the valid values are:
	>0	Indicates the number of columns that the query returns.
	0	Indicates that no result values exist.
rettypes	is an array of pointers to the type names to which the return columns are cast. It can be a NULL-valued pointer if result values do not need to be cast.

Valid in Client LIBMI Application?	Valid in User-Defined Routine?
Yes	Yes

The mi_exec_prepared_statement() function performs the following tasks:

• Bind any input-parameter values to the input-parameter placeholders in the prepared SQL statement that the stmt_desc statement descriptor references.

For any input parameters specified in the statement text of the SQL statement, you must initialize the values, lengths, and nulls arrays. If the prepared statement has input parameters and is not an INSERT statement, you must supply the data types of the parameters in the types array. You can provide the input-parameter values in either of the representation that corresponds with the params_are_binary flag.

For information on how to bind input-parameter values, see Assigning Values to Input Parameters.

• Send the prepared statement to the database server for execution.
• If the prepared statement is a query (that is, it returns rows), open an implicit cursor.

The cursor is stored as part of the statement descriptor. Only one cursor per statement descriptor is current. An implicit cursor is a read-only sequential cursor. If you need some other kind of cursor to access the returned rows, use the mi_open_prepared_statement() function to define an explicit cursor.

The mi_exec_prepared_statement() function only sends the statement to the database server; it does not return results to the application. To get results after the execution mi_exec_prepared_statement(), the DataBlade API module must examine the results via a loop with mi_get_result(). However, the control argument of mi_exec_prepared_statement() does determine the control mode for the statement results.

If the prepared statement is a SELECT statement, you can set the data types of the selected columns by setting a pointer to type name for each returned column in the rettypes array. If the pointer is NULL, the type is not modified. It will either be the return type of the column or the type set by a previous mi_exec_prepared_statement() call. You cannot set the return types of subcolumns of columns of a row type.

A successful return indicates only that the connection is valid and the statement was successfully executed (for statements other than SELECT) or a cursor was successfully opened (for SELECT). It does not indicate the success of the SQL statement. Use mi_get_result() to determine the success of the SQL statement.

See the descriptions of the following functions: mi_drop_prepared_statement(), mi_exec(), mi_open_prepared_statement(), and mi_prepare().

For more information, see Executing Prepared SQL Statements.