mi_integer mi_collection_insert(conn, coll_desc, insrt_datum, action, jump)
   MI_CONNECTION *conn;
   MI_COLL_DESC *coll_desc;
   MI_DATUM insrt_datum;
   MI_CURSOR_ACTION action;
   mi_integer jump;

conn

is a pointer to a connection descriptor established by a previous call to mi_open( ), mi_server_connect( ), or mi_server_reconnect( ).

coll_desc

is a pointer to the collection descriptor.

insrt_datum

is the MI_DATUM value to contain the collection element that mi_collection_insert( ) inserts.

action

determines the orientation of the insertion. When a collection opens, elements are available in a cursor. The current cursor position is before the first element. Possible action values follow:

MI_CURSOR_NEXT

Inserts an element after the current cursor position.

MI_CURSOR_PRIOR

Moves back one element and inserts an element before this new cursor location.

MI_CURSOR_FIRST

Inserts an element before the first element.

MI_CURSOR_LAST

Inserts an element after the last element.

MI_CURSOR_ABSOLUTE

Moves jump elements from the beginning of the cursor and inserts an element before the new cursor position.

MI_CURSOR_RELATIVE

Moves jump elements from the current position and inserts an element before this new cursor position.

MI_CURSOR_CURRENT

Inserts an element before the current cursor position.

jump

is the absolute or relative offset of the insertion for LIST collections only. If action is not MI_CURSOR_ABSOLUTE or MI_CURSOR_RELATIVE when jump is specified, the function raises an exception and returns MI_NULL_VALUE.

For absolute positioning, a jump value of 1 is the first element.

Valid in Client LIBMI Application?	Valid in User-Defined Routine?
Yes	Yes

The mi_collection_insert( ) function inserts the element that insrt_datum references into the open collection that coll_desc references. The action argument determines where the new element value is inserted. This function inserts the specified element into the collection cursor associated with coll_desc and obtains the element to insert from an MI_DATUM value that insrt_datum references.

MI_OK

indicates that the function was successful.

MI_NULL_VALUE

is returned when jump is not zero and the collection is not a list.

MI_ERROR

indicates that the function was not successful.

See also the descriptions of mi_collection_close( ), mi_collection_copy( ), mi_collection_create( ), mi_collection_delete( ), mi_collection_fetch( ), mi_collection_free( ), mi_collection_open( ), mi_collection_update( ), mi_open( ), mi_server_connect( ), and mi_server_reconnect( ).

For descriptions of collections and of MI_DATUM values, see the IBM Informix: DataBlade API Programmer's Guide.