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.