The mi_next_row() function

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

Syntax

MI_ROW *mi_next_row(conn, error)
   MI_CONNECTION *conn;
   mi_integer *error;
conn
A pointer to a connection descriptor established by a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect().
error
A pointer to the return code that mi_next_row() generates.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_next_row() function returns a pointer to a row structure that 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 contents of this row structure are valid until the next call to mi_next_row(). The row structure itself is valid until one of the following conditions occurs:
  • The query finishes.
  • The mi_close() function is called on the connection.
Restriction: Do not use the mi_row_free() function to free the row structure that mi_next_row() uses. Use the mi_row_free() function only for row structures that you allocate with the mi_row_create() function.

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() or mi_value_by_name() 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 the no more rows condition, the function takes the following steps:
  • Returns the NULL-valued pointer
  • Sets 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.

Return values

An MI_ROW pointer
A pointer to the current row.
NULL
The function was not successful, no more rows remain to be retrieved from the cursor, or the cursor is empty.

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