The mi_collection_fetch() function

The mi_collection_fetch() function fetches a single element from a collection.

Syntax

mi_integer mi_collection_fetch(conn, coll_desc, action, jump, value_buf,
   value_len)
   MI_CONNECTION *conn;
   MI_COLL_DESC *coll_desc;
   MI_CURSOR_ACTION action;
   mi_integer jump;
   MI_DATUM *value_buf;
   mi_integer *value_len;
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 for the collection from which to fetch.
action
This value determines the orientation of the fetch. 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
Fetches the next element after the current cursor position.
MI_CURSOR_PRIOR
Fetches the element before the current cursor position.
MI_CURSOR_FIRST
Fetches the first element.
MI_CURSOR_LAST
Fetches the last element.
MI_CURSOR_ABSOLUTE
Moves jump elements from the beginning of the cursor and fetches the element at the new cursor position.
MI_CURSOR_RELATIVE
Moves jump elements from the current position and fetches the element at this new cursor position.
MI_CURSOR_CURRENT
Fetches the element at the current cursor position.
jump
is the absolute or relative offset of the fetch 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.

value_buf
A pointer to the MI_DATUM structure that contains the collection element. The mi_collection_fetch() function allocates the MI_DATUM structure. You do not need to supply the buffer to hold the returned value.
value_len
A pointer to the length of the fetched collection element in the value_buf argument.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_collection_fetch() function fetches the element that action specifies from the open collection that coll_desc references. This function retrieves the specified element from the collection cursor associated with coll_desc and puts this element into the MI_DATUM structure that value_buf references.

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

If you need to save the data for later use, you must create your own copy of the data that value_buf references. For example, if the collection element is a character string, the data in value_buf is a pointer to an mi_lvarchar structure. To save the data in the mi_lvarchar structure, you can copy it with the mi_var_copy() function.

Return values

MI_NULL_VALUE
The returned data is NULL.
MI_END_OF_DATA
No more data remains to be fetched or the jump position is past the last element.
MI_ERROR
The connection handle is invalid.
MI_ROW_VALUE
The fetched element is a row.
MI_COLLECTION_VALUE
The fetched element is a collection.
MI_NORMAL_VALUE
Execution of the function was successful.

The mi_collection_fetch() function raises an exception for a bad argument, such as a null connection.