The mi_query_finish( ) function completes execution of the current statement. The function performs the following steps:
The mi_query_finish( ) function does not affect prepared statements or calls to DataBlade API file-access functions. To determine whether the current statement has completed execution, use the mi_command_is_finished( ) function.
The mi_exec( ) function opens an implicit cursor to hold the resulting rows of a query. For such queries, the mi_query_finish( ) function ensures that the database server processes the results of a statement. The mi_query_finish( ) function processes all the remaining rows in the cursor of the current statement and throws them away.
If the current statement failed, mi_query_finish( ) returns MI_ERROR. In this case, mi_query_finish( ) guarantees that the database server is ready for the next statement (unless the database server has dropped the connection). All callbacks are properly invoked during mi_query_finish( ) processing.
The mi_query_finish( ) function releases implicitly allocated resources associated with the current statement. The following table summarizes the implicitly allocated resources for different query executions.
| DataBlade API Function That Allocated Statement Resource | Resources That mi_query_finish( ) Releases |
|---|---|
| mi_exec( ) | |
| mi_exec_prepared_statement( ), mi_open_prepared_statement( ) | None
Use mi_close_statement( ) and mi_drop_prepared_statement( ). For more information, see Releasing Prepared-Statement Resources. |
| mi_next_row( ) | Release the row structure for the current row. |
| mi_get_row_desc_without_row( ) | Release the row descriptor for the current row. |
The mi_exec( ) function creates an implicit statement descriptor and opens an implicit cursor for the SQL statement it executes. These structures have as their scope from the time they are allocated with mi_exec( ) until whichever of the following events occurs first:
To conserve resources, use the mi_query_finish( ) function to explicitly close the implicit cursor and free the implicit statement descriptor once your DataBlade API module no longer needs access to the current statement. The mi_query_finish( ) function is the destructor function for the implicit cursor and its associated implicit statement descriptor.
The mi_query_finish( ) and mi_query_interrupt( ) functions also free the implicit row structure and row descriptor that hold each row as it is fetched from a cursor. A general rule of DataBlade API programming is that you do not explicitly free a data type structure that you have not explicitly allocated. This rule applies to the row structure and row descriptor of the current statement, in particular:
These data type structures are freed when the connection closes. For more information, see Closing a Connection.
Home | [ Top of Page | Previous Page | Next Page | Contents | Index ]