Informix DataBlade API Programmer's Manual DataBlade API Function Descriptions

The mi_next_row() function retrieves the next row from the cursor of a query.

MI_ROW *mi_next_row(conn, error)

MI_CONNECTION *conn;

mi_integer *error;

conn	is a pointer to the connection descriptor that a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect() has established.
error	is a pointer to the return code that mi_next_row() generates.

Valid in Client LIBMI Application?	Valid in User-Defined Routine?
Yes	Yes

The mi_next_row() function returns a pointer to a row structure, which contains the row just fetched (the current row) from the cursor associated with the current statement. The current statement is associated with the connection that conn references. Only one cursor per connection is current and within this cursor, only one row at a time is current.

The row structure is valid until one of the following conditions occurs:

• The query finishes.
• The mi_next_row() function is called again.
• The mi_close() function is called on the connection.

Use the mi_next_row() function when mi_get_result() returns MI_ROWS to indicate that the cursor is ready to be accessed. Upon successful completion, the mi_next_row() function advances the cursor pointer to the next row to be fetched from the cursor. After mi_next_row() successfully fetches a row, you can extract column values with the mi_value() function.

The mi_next_row() function is typically executed in a loop that terminates when no more rows remain to be fetched from the cursor. To indicate "no more rows" condition, the function takes the following steps:

• Return the NULL-valued pointer.
• Set the *error argument to MI_NO_MORE_RESULTS.

An error value of MI_NO_MORE_RESULTS indicates that you are at the end of the cursor or that the cursor is empty.

Upon failure, mi_next_row() returns NULL and sets *error to MI_ERROR.

See the descriptions of the following functions: mi_get_result() and mi_value().

For more information, see Retrieving Rows.