The mi_save_set_get_previous() function
The mi_save_set_get_previous() function traverses a save set in the backward direction.
Syntax
MI_ROW *mi_save_set_get_previous(save_set, error)
MI_SAVE_SET *save_set;
mi_integer *error;- save_set
- A pointer to an MI_SAVE_SET structure.
- error
- A pointer to a return code.
| Valid in client LIBMI application? | Valid in user-defined routine? |
|---|---|
| Yes | Yes |
Usage
The mi_save_set_get_previous() function obtains the previous row from the save set that save_set references. Because the DataBlade® API maintains a save set as an FIFO (first-in, first-out) queue, the previous row is the row added to the save set after the current row. This save set must have been previously created with the mi_save_set_create() function.
When
the mi_save_set_get_previous() function is successful,
it returns a pointer to the row structure for the previous row. It
also moves the cursor position to point to this new current row of
the save set. The mi_save_set_get_previous() function
is typically executed in a loop that terminates when no more rows
remain to be fetched from the save-set 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 beginning or the end of the save-set cursor or that the save set is empty.
Return values
- An MI_ROW pointer
- A pointer to the previous row backward in the specified save set.
- NULL
- The function was not successful, that no more rows remain to be retrieved from the save-set cursor, or that the save set is empty.
Upon failure, mi_save_set_get_previous() returns NULL and sets error to MI_ERROR.