Return a statement descriptor

The mi_prepare() function sends the contents of an SQL statement string to the database server, which parses the statement and returns it in an optimized executable format.

The function returns a pointer to an explicit statement descriptor (usually called just a statement descriptor). A statement descriptor, MI_STATEMENT, is a DataBlade® API structure that contains the information about a prepared SQL statement, including the executable format of the SQL statement.

The following table summarizes the memory operations for a statement descriptor.


Memory duration	Memory operation	Function name
Not allocated from memory-duration pools	Constructor	mi_prepare()
Not allocated from memory-duration pools	Destructor	mi_drop_prepared_statement(), mi_close_statement()

A statement descriptor can be identified in either of the following ways:

As a pointer to an MI_STATEMENT structure, which mi_prepare() returns
The mi_prepare() function is a constructor function for a statement descriptor.
As an integer statement identifier, which the mi_get_id() function returns when passed MI_STATEMENT_ID as its second argument

The following table lists the DataBlade® API accessor functions for an explicit statement descriptor.

Table 1. Accessor functions for an explicit statement descriptor
Statement-descriptor information	DataBlade® API accessor function
The name of the SQL statement that was prepared	mi_statement_command_name()
Information about any input parameters in the prepared statement	The input-parameter accessor functions (Input-parameter information in the statement descriptor)
A row descriptor for the columns in the prepared statement	mi_get_statement_row_desc() From the row descriptor, you can use the row-descriptor accessor functions to obtain information about a particular column (see Field and column information in the row descriptor).

Important: To DataBlade® API modules, the statement descriptor (MI_STATEMENT) is an opaque C structure. Do not access the internal fields of this structure directly. The internal structure of the MI_STATEMENT might change in future releases. Therefore, to create portable code, always use these accessor functions to obtain prepared-statement information.

You pass a statement descriptor to the other DataBlade® API functions that handle prepared statements, including mi_exec_prepared_statement(), mi_open_prepared_statement(), mi_fetch_statement(), mi_close_statement(), and mi_drop_prepared_statement().