Move through a cursor

The mi_collection_fetch() function obtains the element specified by its action argument from the collection cursor. For a list of valid cursor-action flags, see Table 1. You can move the cursor position back to the beginning of the cursor with the mi_collection_fetch() function, as the following example shows:

mi_collection_fetch(conn, coll_desc, MI_CURSOR_FIRST, 0,
   coll_element, element_len);

if ( ((mi_integer)coll_element != 1) || 
      (element_len != sizeof(mi_integer)) )
    /* raise an error */

This function moves the cursor position backward with respect to its position after a call to mi_collection_insert() (Figure 1). The mi_collection_fetch() function is valid only for the following cursors:

Sequential collection cursors, if the cursor position does not move backward
Scroll collection cursors
Only scroll cursors provide the ability to move the cursor position forward and backward.

The following figure shows the cursor position and coll_element value after the preceding call to mi_collection_fetch().

Figure 1. Collection cursor after fetch first

begin figure description - This figure is described in the surrounding text. - end figure description

The following figure shows the cursor position and value of coll_element after the following mi_collection_fetch() call:

mi_collection_fetch(conn, coll_desc, MI_CURSOR_NEXT, 0,
   coll_element, element_len);

Figure 2. Collection cursor after fetch next

The following figure shows the cursor position and value of coll_element after the following mi_collection_fetch() call:

mi_collection_fetch(conn, coll_desc, MI_CURSOR_RELATIVE, 3,
   coll_element, element_len);

Figure 3. Collection Cursor After Fetch Relative 3

The preceding mi_collection_fetch() call is valid only if the collection is a LIST. Only LIST collections are ordered. Therefore relative fetches, which specify the number of elements to move forward or backward, can only be used on LIST collections. If you try to perform a relative fetch on a SET or MULTISET, mi_collection_fetch() generates an error.

The following figure shows the cursor position and value of coll_element after the following mi_collection_fetch() call:

mi_collection_fetch(conn, coll_desc, MI_CURSOR_RELATIVE, -2,
   coll_element, element_len);

Figure 4. Collection cursor after fetch relative -2

Because the preceding mi_collection_fetch() call moves the cursor position backward, the call is valid only if the collection cursor is a scroll cursor. When you open a collection with mi_collection_open(), you get a read/write scroll collection cursor. However, if you open the collection with mi_collection_open_with_options() and the MI_COLL_NOSCROLL option, mi_collection_fetch() generates an error.

The following figure shows the cursor position and value of coll_element after the following mi_collection_fetch() call:

mi_collection_fetch(conn, coll_desc, MI_CURSOR_ABSOLUTE, 6,
   coll_element, element_len);

Figure 5. Collection cursor after fetch absolute 6

The preceding mi_collection_fetch() call is valid only if the collection is a LIST. Because absolute fetches specify a position within the collection by number, they can only be used on an ordered collection (a LIST). If you try to perform an absolute fetch on a SET or MULTISET, mi_collection_fetch() generates an error.

Because only six elements are in this collection, the absolute fetch of 6 positions the cursor on the last element in the collection. This result is the same as if you had issued the following mi_collection_fetch():

mi_collection_fetch(conn, coll_desc, MI_CURSOR_LAST, 0,
   coll_element, element_len);

The fetch last is useful when you do not know the number of elements in a collection and want to obtain the last one.