The mi_get_result() function returns
a status of MI_DML to indicate that the current statement is a data
manipulation (DML) statement that has successfully executed.
SQL contains the DML statements that the following table lists.
Table 1. SQL statements with an MI_DML
status
DML statement
Purpose
Statement-status constant
DELETE
Remove a row from a database table
MI_DML
INSERT
Add a new row to a database table
MI_DML
UPDATE
Modify values in an existing row of a database
table
MI_DML
SELECT
Fetch a row or group of rows from the database
MI_ROWS, MI_DML
EXECUTE FUNCTION
Execute a user-defined function
MI_ROWS, MI_DML
Tip: The mi_get_result() function
returns the MI_DML status when the current statement is the EXECUTE
FUNCTION statement. This SQL statement can return rows of data and
therefore is handled in the same way as the SELECT statement. However,
execution of the EXECUTE PROCEDURE statement causes a statement status
of MI_DDL because this SQL statement never returns rows.
When you receive the MI_DML statement status, you can use the DataBlade®
API functions
in the following table to obtain information about the results of
the current statement.
Result information
DataBlade
API function
Additional information
The name of the DML statement that executed as
the current statement
mi_result_command_name()
This function might be useful in an interactive
application in which the statement sent is not determined until runtime.
Use this routine only when mi_get_result() reports
that a DML or DDL statement has completed.
The number of rows that the current statement affected
mi_result_row_count()
This function is applicable only when mi_get_result() reports
that a DML statement completed.
Important: If you want a count of the numbers
of rows that satisfy a given query, but you do not want the data in
the rows, you can run a query that uses the COUNT aggregate more efficiently
than you can run a query that returns the actual rows. For example,
the following query counts the number of rows in mytable:
SELECT COUNT(*) FROM mytable;
The following code fragment shows a sample function, named handle_dml(),
that handles the MI_DML statement status that mi_get_result() returns. Figure 1: Sample function
to handle MI_DML statement status
mi_integer handle_dml(conn)
MI_CONNECTION *conn;
{
char *cmd;
mi_integer count;
/* What kind of statement was it? */
cmd = mi_result_command_name(conn);
DPRINTF("trc_class", 11,
("Statement executed was %s", cmd));
/* Get # rows affected by statement */
if ( (count = mi_result_row_count(conn)) == MI_ERROR )
{
DPRINTF("trc_class", 11,
("Cannot get row count\n"));
return( -1 );
}
else if ( count = 0 )
{
DPRINTF("trc_class", 11,
("No rows returned from query\n"));
}
else
DPRINTF("trc_class", 11,
("Rows Returned\n"));
return ( count );
}
The handle_dml() function in the preceding code
fragment uses the mi_result_command_name() and mi_result_row_count() functions
to obtain additional information about the DML statement. The function
returns the number of rows affected (from mi_result_row_count())
to the calling routine.
Server only: The handle_dml() function
in Sample function
to handle MI_DML statement status assumes it is
called from within a C UDR because it uses the DPRINTF statement.
The DPRINTF statement is part of the DataBlade
API tracing
feature and available only to C UDRs. The first DPRINTF statement
in Sample function
to handle MI_DML statement status sends the name
of the current statement to a trace file when the current trace level
is 11 or higher. For more information about tracing, see Tracing.
Client only: For the handle_dml() function
to execute in a client LIBMI application, it would need to replace
the DPRINTF statements with a client-side output function such as printf() or fprintf().
The following line shows the use of the printf() function
to display the name of the current statement:
For a successful UPDATE, INSERT, and DELETE statement, the mi_get_result() loop
returns the following states of the database server:
An MI_DML status indicates that the DML statement has successfully
completed.
In the next iteration of the mi_get_result() loop, mi_get_result() returns
MI_NO_MORE_RESULTS.
For a successful SELECT (or EXECUTE FUNCTION) statement, the mi_get_result() loop
returns the following states of the database server:
An MI_ROWS statement status indicates that the current statement
is a query that has executed successfully and whose cursor is ready
for processing of query rows.
After all query rows are retrieved, the next iteration of the mi_get_result() loop
returns an MI_DML statement status to indicate that the SELECT (or
EXECUTE FUNCTION) has successfully completed.
The next iteration of the mi_get_result() loop
returns the MI_NO_MORE_RESULTS status to indicate that statement processing
is complete.