The mi_collection_update() function

The mi_collection_update() function updates a collection.

Syntax

mi_integer mi_collection_update(conn, coll_desc, upd_datum, action, jump)
   MI_CONNECTION *conn;
   MI_COLL_DESC *coll_desc;
   MI_DATUM upd_datum;
   MI_CURSOR_ACTION action;
   mi_integer jump;
conn
A pointer to a connection descriptor established by a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect().
coll_desc
A pointer to the collection descriptor.
upd_datum
A value or the address of data to insert into the collection. You can pass int2, int4, float for SQLSMFLOAT, and fixed-length user-defined types by value and all other types by reference.
action
determines the orientation of the update. 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
Updates the next element after the current cursor position.
MI_CURSOR_PRIOR
Updates the element before the current cursor position.
MI_CURSOR_FIRST
Updates the first element.
MI_CURSOR_LAST
Updates the last element.
MI_CURSOR_ABSOLUTE
Moves jump elements from the beginning of the cursor and updates the element at the new cursor position.
MI_CURSOR_RELATIVE
Moves jump elements from the current position and updates the element at this new cursor position.
MI_CURSOR_CURRENT
Updates the element at the current cursor position.
jump
The absolute or relative offset in the collection 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

Usage

The mi_collection_update() function updates the element that the action argument indicates in the open collection that coll_desc references. The function updates the element with the MI_DATUM value that upd_datum references. The function updates the specified element from the collection cursor associated with coll_desc.

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

Return values

MI_OK
The function was successful.
MI_NULL_VALUE
This value is returned when jump is not zero and the collection is not a list.
MI_ERROR
The function was not successful.