Position the cursor

When you open a collection cursor with mi_collection_open(), the cursor position points to the first element of the collection.

The cursor position identifies the current element in the collection cursor. The DataBlade API functions that access a collection must specify where in the collection to perform the operation. To specify location, these functions all have an action argument of type MI_CURSOR_ACTION, which supports the cursor-action constants in the following table.

Table 1. Valid cursor-action constants
Cursor position	Action argument	Sequential cursor type	Scroll cursor type
Move the cursor position one element forward within the cursor	MI_CURSOR_NEXT	Yes	Yes
Move the cursor position one element backward within the cursor	MI_CURSOR_PRIOR	No	Yes
Move the cursor position to the beginning of the cursor, at the first element	MI_CURSOR_FIRST	Only if the cursor position does not move backward	Yes
Move the cursor position to the end of the cursor, at the last element	MI_CURSOR_LAST	Yes	Yes
Move the cursor to the absolute position within the cursor, where the first element in the cursor is at position 1.	MI_CURSOR_ABSOLUTE	Yes if the collection is a LIST because only LISTs have ordered elements	Yes if the collection is a LIST because only LISTs have ordered elements
Move the cursor forward or back a specified number of elements from the current position.	MI_CURSOR_RELATIVE	Only if relative position is a positive value and the collection is a LIST because only LISTs have ordered elements	Yes if the collection is a LIST because only LISTs have ordered elements Relative position can be a negative or positive value
Leave the cursor position at its current location.	MI_CURSOR_CURRENT	Yes	Yes

The following code fragment uses the mi_collection_fetch() function to fetch a VARCHAR element from a collection:

/*
 * Fetch next VARCHAR() element from a collection.
 */

   MI_CONNECTION *conn;
   MI_COLL_DESC *colldesc;
   MI_ROW_DESC  *rowdesc;
   MI_COLLECTION *nest_collp;
   MI_DATUM value;
   mi_integer ret_code, ret_len;
   char *buf;

   /* Fetch a VARCHAR() type */
   ret_code = mi_collection_fetch(conn, colldesc,
      MI_CURSOR_NEXT, 0, &value, &ret_len);

   switch ( ret_code )
   {
   case MI_NORMAL_VALUE:
      buf = mi_get_vardata((mi_lvarchar *)value);
      DPRINTF("trace_class", 15, ("Value: %s", buf));
      break;

   case MI_NULL_VALUE:
      DPRINTF("trace_class", 15, ("NULL"));
      break;

   case MI_ROW_VALUE:
      rowdesc = (MI_ROW_DESC *)value;
      break;

   case MI_COLLECTION_VALUE:
      nested_collp = (MI_COLLECTION *)value;
      break;

   case MI_END_OF_DATA:
      DPRINTF("trace_class", 15, 
         ("End of collection reached"));
      return (100);
   }