Retrieving Rows

After a query executes, a cursor holds the query rows. The mi_next_row( ) function takes the following actions to obtain the rows from a cursor:

• Obtains access to the current row
• Executes the mi_next_row( ) function in a loop that iterates for each query row

For a sample function that shows one way to use mi_next_row( ) to retrieve query rows, see Example: The get_data( ) Function.

Accessing the Current Row

The mi_next_row( ) function accesses rows in the cursor that is associated with the current statement. Because a current statement is associated with a connection, you must pass a connection descriptor into mi_next_row( ) to identify the cursor to access. From this cursor, mi_next_row( ) obtains the current row. The current row is the row in the cursor that the cursor position identifies. Each time mi_next_row( ) retrieves a row, this cursor position moves by one. One cursor per connection is current and within this cursor, only one row at a time is current.

The mi_next_row( ) function returns the current row in an implicit row structure (MI_ROW structure). The row structure stores the column values of a single query row. The contents of this row structure are valid until mi_next_row( ) returns the next row. You can obtain column values from the row structure with the mi_value( ) or mi_value_by_name( ) function. For more information, see Obtaining Column Values.

This implicit row structure is freed when the query is completed, which can occur in any of the following ways:

• When mi_next_row( ) returns the NULL-valued pointer to indicate no more rows exist in the cursor
• When the mi_query_finish( ) function executes
• When the connection is closed

Executing the mi_next_row( ) Loop

The mi_next_row( ) function is usually the middle loop of row-retrieval code. In the mi_next_row( ) loop, each call to mi_next_row( ) returns one query row from the cursor that is associated with the current statement. This query row is the current row only until the next iteration of the loop, when mi_next_row( ) retrieves another row from the cursor. This loop terminates when mi_next_row( ) returns a NULL-valued pointer and its error argument is zero (0). These conditions indicate either that no more rows exist in the cursor or that the cursor is empty. Think of the mi_next_row( ) loop as an iteration over the matching rows of the query.

The contents of a row structure become invalid as soon as you fetch a new row into it with mi_next_row( ). If you want to save the row values that you obtain with mi_value( ) or mi_value_by_name( ), copy the values that these functions pass back before the next call to mi_next_row( ).

The mi_next_row( ) function allocates memory for the row structure that it returns. To free this row structure, you must complete the query. For more information, see Completing Execution.

As long as rows remain to be retrieved from the cursor, the mi_get_result( ) function returns a statement status of MI_ROWS. Therefore, you cannot exit the mi_get_result( ) loop until one of the following actions occurs:

• The mi_next_row( ) loop continues until no more rows exist in the cursor. That is, mi_next_row( ) returns a NULL-valued pointer.
• You terminate the mi_get_result( ) loop prematurely with a call to mi_query_finish( ) or mi_query_interrupt( ).