Informix DataBlade API Programmer's Manual DataBlade API Function Descriptions

The mi_open_prepared_statement() function sends a prepared statement that is a query to the database server for execution and opens a cursor for the retrieved rows of the query.

mi_integer mi_open_prepared_statement(stmt_desc, control, params_are_binary,

n_params, values, lengths, nulls, types, cursor_name, 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_string *cursor_name;

mi_integer retlen;

mi_string *rettypes[]);

stmt_desc	is a pointer to a statement descriptor for the prepared statement to open. The mi_prepare() function generates this statement descriptor.
control	is a bit-mask flag that controls the following characteristics:
	Whether the returned rows are returned in their binary (internal) or text (external) representation
	The type of cursor to create and open
params_are_binary is set to one of the following values:
	1 (MI_TRUE)	The input-parameter values (in the values array) are passed in their internal (binary) representation.
	0 (MI_FALSE)	The input-parameter values (in the values array) are passed in their external (text) representation.
n_params	is the number of entries in the nulls, lengths, and values arrays.
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 data type names for the input parameters. This array can be a NULL-valued pointer.
cursor_name	is a name of the cursor that holds the fetched rows. This name must be unique. To use an internally-generated unique name for the cursor, specify NULL-valued pointer.
retlen	is the length of the rettypes array. Currently 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 data type names to which the result values are cast. This array 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_open_prepared_statement() 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 use the types array to supply the data types of the input parameters. 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.
• Open an explicit cursor whose characteristics are specified by a bit mask in the control argument.

  Cursor Type	Control-Flag Value
  Update sequential cursor	None (default)
  Read-only sequential cursor	MI_SEND_READ
  Update scroll cursor	MI_SEND_SCROLL
  Read-only scroll cursor	MI_SEND_READ & MI_SEND_SCROLL
  Update sequential cursor with hold	MI_SEND_HOLD
  Read-only sequential cursor with hold	MI_SEND_READ & MI_SEND_HOLD
  Update scroll cursor with hold	MI_SEND_SCROLL & MI_SEND_HOLD
  Read-only scroll cursor with hold	MI_SEND_READ & MI_SEND_SCROLL & MI_SEND_HOLD

The cursor is stored as part of the statement descriptor. Only one cursor per statement descriptor is current.

The control argument also determines the representation of any returned values.

Data Representation	Control-Flag Value
External (text) representation	None (default)
Internal (binary) representation	MI_BINARY

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_open_prepared_statement() call. You cannot set the return types of subcolumns of columns of a complex type.

Once opened, you can set up rows in the cursor for fetching with the mi_fetch_statement() function.

A successful return indicates only that the connection is valid and a cursor was successfully opened. 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_close_statement(), mi_exec_prepared_statement(), mi_fetch_statement(), and mi_prepare().

For more information, see Executing Prepared SQL Statements.