The mi_prepare() function

The mi_prepare() function sends an SQL statement to the database server to be prepared and returns a statement descriptor for the prepared statement.

Syntax

MI_STATEMENT *mi_prepare(conn, stmt_strng, name)
   MI_CONNECTION *conn;
   mi_string *stmt_strng;
   mi_string *name;
conn
A pointer to a connection descriptor established by a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect().
stmt_strng
A pointer to the statement string, which contains the text of the SQL statement to prepare.
name
An optional name to assign to the cursor associated with the prepared statement on the server computer or to the prepared statement on the client computer.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_prepare() function sends the SQL statement in the stmt_strng statement string to the database server. The database server parses and optimizes the statement string and builds the necessary internal structures for a prepared statement. This function is the constructor for the statement descriptor (MI_STATEMENT).

The stmt_strng statement string can contain input parameters to indicate where column or expression values will be provided at runtime. Specify input parameters within the statement string with the question-mark symbol (?).

Server only: The mi_prepare() function does not allocate a new statement descriptor from memory-duration pools. For information about the scope of a statement descriptor, see the HCL OneDB™ DataBlade® API Programmer's Guide.

If your prepared statement will fetch rows, you can use the name argument to specify the name of the cursor that holds the fetched rows. This name must be unique within the client session. When you specify a non-NULL cursor name to mi_prepare(), make sure that you specify a NULL-valued pointer as the cursor_name argument of the mi_open_prepared_statement() function. If you want to postpone specification of the cursor name to the mi_open_prepared_statement() call, use a NULL-valued pointer as the name value in mi_prepare(). If you specify a cursor name in both mi_prepare() and mi_open_prepared_statement(), the DataBlade API uses the cursor name that mi_open_prepared_statement() provides. For more information, see the HCL OneDB DataBlade API Programmer's Guide.

Client only: The name argument specifies the statement name for the prepared statement. This name must be unique within the client session. To use an internally generated unique name for the statement, specify a NULL-valued pointer for the name argument of mi_prepare(). The cursor_name argument of mi_open_prepared_statement() specifies the cursor name for the prepared statement.
After you have a statement descriptor, you can obtain the following information about the prepared statement.
Prepared-statement information DataBlade API functions
Input parameters Input-parameter accessor functions (which begin with mi_parameter_)
Columns (from the row descriptor) Column accessor functions (which begin with mi_column_)

For more information about information in a statement descriptor, see the HCL OneDB DataBlade API Programmer's Guide.

Return values

An MI_STATEMENT pointer
A pointer to a statement descriptor for the SQL statement in stmt_strng.
NULL
The function was not successful.