The mi_collection_delete() function

Syntax

mi_integer mi_collection_delete(conn, coll_desc, action, jump)
   MI_CONNECTION *conn;
   MI_COLL_DESC *coll_desc;
   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.

action

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

MI_CURSOR_NEXT

Deletes the next element after the current cursor position.

MI_CURSOR_PRIOR

Deletes the element before the current cursor position.

MI_CURSOR_FIRST

Deletes the first element.

MI_CURSOR_LAST

Deletes the last element.

MI_CURSOR_ABSOLUTE

Moves jump elements from the beginning of the cursor and deletes the element at the new cursor position.

MI_CURSOR_RELATIVE

Moves jump elements from the current position and deletes the element at this new cursor position.

MI_CURSOR_CURRENT

Deletes the element at the current cursor position.

jump

The absolute or relative offset of the deletion 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.

Usage

The mi_collection_delete() function deletes the element that the action argument indicates from the open collection that coll_desc references. The function deletes the specified element from the collection cursor that is associated with the coll_desc collection descriptor. After the deletion of an element, the cursor position remains on the deleted element.

For a description of collections, see the Informix® DataBlade® API Programmer's Guide.

Return values

MI_OK

The function was successful.

MI_NULL_VALUE

The function call specifies jump and action is not MI_CURSOR_ABSOLUTE or MI_CURSOR_RELATIVE.

MI_ERROR

The function was not successful, including an attempt to delete a nonexistent element.