Obtain the element value

The mi_collection_fetch() function uses an MI_DATUM value to represent an element that it fetches from a collection. You must pass in a pointer to the value buffer in which mi_collection_fetch() puts the element value. However, you do not have to allocate memory for this buffer. The mi_collection_fetch() function handles memory allocation for the MI_DATUM value that it passes back.

The contents of the MI_DATUM structure that holds the retrieved element depends on the passing mechanism that the function used, as follows:

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

Important: The difference in behavior of mi_collection_fetch() between C UDRs and client LIBMI applications means that collection-retrieval code is not completely portable between these two types of DataBlade API modules. When you move your DataBlade API code from one of these uses to another, you must change the collection-retrieval code to use the appropriate passing mechanism for element values that mi_collection_fetch() returns.

You declare a value buffer for the fetched element and pass in the address of this buffer to mi_collection_fetch(). You can declare the buffer in either of the following ways:

If you know the data type of the field value, declare the value buffer of this data type.
Declare the value buffer as a pointer to the field data type, regardless of whether the data type is passed by reference or by value.
If you do not know the data type of the field value, declare the value buffer to have the MI_DATUM data type.
Your code can dynamically determine the field type with the mi_column_type_id() or mi_column_typedesc() function. You can then convert (or cast) the MI_DATUM value to a data type that you need.

Figure 1 through Figure 5 fetch elements from a LIST collection of INTEGER values. To fetch elements from this LIST, you can declare the value buffer as follows:

mi_integer *coll_element;

Server only:

Because you can pass INTEGER values by value in a C UDR, you access the MI_DATUM structure that these calls to mi_collection_fetch() pass back as the actual value, as follows:

int_element = (mi_integer)coll_element;

If the element type is a data type that must be passed by reference, the contents of the MI_DATUM structure that mi_collection_fetch() passes back is a pointer to the actual value. The following call to mi_collection_fetch() also passes in the value buffer as a pointer. However, it passes back an MI_DATUM value that contains a pointer to a FLOAT (mi_double_precision) value:

mi_double_precision *coll_element, flt_element;
...
/* Fetch a FLOAT value in a C UDR */
mi_collection_fetch(conn, coll_desc, action, jump,
   &coll_element, &retlen);
flt_element = *coll_element;

Client only:

For the fetches in Figure 1 through Figure 5, a client LIBMI application declares the value buffer in the same way as a C UDR. However, because all data types are passed back by reference, the MI_DATUM structure that mi_collection_fetch() passes back contains a pointer to the INTEGER value, not the actual value itself:

mi_integer *coll_element, int_element;
...
/* Fetch an INTEGER value in a client LIBMI application */
mi_collection_fetch(conn, coll_desc, action, jump,
   &coll_element, &retlen);
int_element = *coll_element;