The mi_exec_prepared_statement() function

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

Syntax

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

A pointer to the statement descriptor for the prepared statement to execute. The mi_prepare() function generates this statement descriptor.

control

The value is a bit mask of flags that controls the behavior of mi_exec_prepared_statement(). The valid control flags are:

MI_BINARY: Returns results in binary representation.
0: Returns results in text representation.

params_are_binary

This value 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

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

An array of MI_DATUM structures that contain the values of the input parameters in the prepared statement.

lengths

An array of the lengths (in bytes) of the input-parameter values.

nulls

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

This value is either an array of pointers to the names of the data types for the input parameters or a NULL-valued pointer.

retlen

The length of the rettypes array. Valid retlen values are:

>0: The number of columns that the query returns.
0: No result values exist.

rettypes

is either an array of pointers to the names of the data types to which the return columns are cast or, if result values do not need to be cast, a NULL-valued pointer.


Valid in client LIBMI application?	Valid in user-defined routine?
Yes	Yes

Usage

The mi_exec_prepared_statement() function performs the following tasks:

Binds any input-parameter values to the input-parameter placeholders in the prepared SQL statement that stmt_desc references
For any input parameter 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 representations that correspond with the params_are_binary flag.
For information about how to bind input-parameter values, see the Informix® DataBlade® API Programmer's Guide.
Sends the prepared statement to the database server for execution
If the prepared statement is a query (that is, it returns rows), opens 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 through a loop with mi_get_result(). However, the control argument of mi_exec_prepared_statement() does determine the control mode for the statement results.

The mi_exec_prepared_statement() function allocates a type descriptor for each of the data types of the input parameters in the types array. If the calls to mi_exec_prepared_statement() are in a loop in which these data types do not vary between loop iterations, mi_exec_prepared_statement() can reuse the type descriptors. On the first call to mi_exec_prepared_statement(), specify in the types array the correct data type names for the input parameters. On subsequent calls to mi_exec_prepared_statement(), replace the array of data type names with a NULL-valued pointer.

If the prepared statement is a SELECT statement, you can set the data types of the selected columns by setting a pointer to a 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 fields of a row type.

Return values

MI_OK: The function was successful.
MI_ERROR: The function was not successful.

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 the mi_get_result() function to determine the success of the SQL statement.