Insert an element

You insert an element into an open collection with the mi_collection_insert() function. You can perform an insert operation only on a read/write cursor. An insert is not valid on a read-only cursor.

The mi_collection_insert() function uses an MI_DATUM value to represent an element that it inserts into a collection. The contents of the MI_DATUM structure depend on the passing mechanism that the function used, as follows:

In a C user-defined routine (UDR), when mi_collection_insert() inserts an element value, it can pass the value by reference or by value, depending on the data type of the column value. If the function passes the element value by value, the MI_DATUM structure contains the value. If the function passes the element value by reference, the MI_DATUM structure contains a pointer to the value.
In a client LIBMI application, when mi_collection_insert() inserts an element value, it always passes the value in an MI_DATUM structure by reference. Even for values that you can pass by value in a C UDR (such as an INTEGER values), this function passes the element value by reference. The MI_DATUM structure contains a pointer to the value.

The mi_collection_insert() function inserts the new element at the location in the collection cursor that its action argument specifies. For a list of valid cursor-action flags, see Valid cursor-action constants.

Server only: The following call to mi_collection_insert() can pass in an actual value because it inserts an INTEGER element into a LIST collection and integer values are passed by value in a C UDR:

MI_CONNECTION *conn;
MI_DATUM datum;
MI_COLL_DESC *colldesc;

datum=6;
mi_collection_insert(conn, colldesc, datum, 
   MI_CURSOR_ABSOLUTE, 1);

datum=3;
mi_collection_insert(conn, colldesc, datum, 
   MI_CURSOR_ABSOLUTE, 2);

datum=15;
mi_collection_insert(conn, colldesc, datum, 
   MI_CURSOR_ABSOLUTE, 3);

datum=1;
mi_collection_insert(conn, colldesc, datum, 
   MI_CURSOR_ABSOLUTE, 4);

datum=4;
mi_collection_insert(conn, colldesc, datum, 
   MI_CURSOR_ABSOLUTE, 5);

datum=8;
mi_collection_insert(conn, colldesc, datum, 
   MI_CURSOR_ABSOLUTE, 6);

The following figure shows the cursor position after the preceding calls to mi_collection_insert() complete.

begin figure description - This figure is described in the surrounding text. - end figure description — Figure 1: Collection cursor after inserts complete

These mi_collection_insert() calls specify absolute addressing (MI_CURSOR_ABSOLUTE) for the collection because the collection is defined as a LIST. Only LIST collections have ordered position assigned to their elements. SET and MULTISET collections do not have ordered position of elements.