The mi_value() function

The mi_value() function retrieves a column value from a row, given the column identifier.

Syntax

mi_integer mi_value(row, column_id, value_buf, value_len)
   MI_ROW *row;
   mi_integer column_id;
   MI_DATUM *value_buf;
   mi_integer *value_len;
row
The row from which values are being extracted.
column_id
The column identifier of the column, which specifies the position of the column in the specified row. Column numbering follows C programming conventions: the first column in the row is at position zero.
value_buf
A pointer to an MI_DATUM structure that contains the column value. This function allocates the MI_DATUM structure. You do not need to supply the buffer to contain the returned value.
value_len
The length of the returned column value.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_value() function returns the value for the column that the column_id column identifier specifies. It retrieves this column value from the row structure that row references. This function is typically called in a loop that terminates when mi_value() has retrieved values for all the columns in the row.
Important: The value_buf parameter points to the representation of the value that corresponds to the control mode of the query: a character string for text representation and the internal format for binary representation.

The way to interpret the data returned in the value_buf depends on the mi_value() return value, as follows.

Return value from mi_value()
Contents of value_buf
MI_NORMAL_VALUE
A pointer to an MI_DATUM structure that holds the value for the column

The format of this value depends on whether the control mode for the retrieved data is text or binary representation. In binary mode, the format also depends on whether the MI_DATUM value is passed by reference or by value.

MI_ROW_VALUE
A pointer to a row structure (MI_ROW)
MI_COLLECTION_VALUE
A pointer to a collection structure (MI_COLLECTION)
MI_NULL_VALUE
A pointer to a value that indicates the SQL NULL value for the column

The pointer returned in value_buf is valid until a new mi_exec() function is run or until the statement is dropped with the mi_drop_prepared_statement() function. However, the DataBlade® API can overwrite the data when the mi_next_row() function is called on the same connection.

However, the DataBlade® API can overwrite the data in any of the following cases:
  • The mi_next_row() function is called on the same connection.
  • A call to the mi_row_create() function uses the row descriptor.
  • The mi_row_free() function is called on the row.
  • The mi_row_desc_free() function is called on the row descriptor.

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 column is a character column, 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. You can use a save set to save an entire row.

For more information about how to retrieve values, see the Informix® DataBlade® API Programmer's Guide.

Return values

MI_NORMAL_VALUE
The retbuf value is not a row type or a collection.
MI_COLLECTION_VALUE
The retbuf value is a pointer to a collection structure (MI_COLLECTION).
MI_ROW_VALUE
The retbuf value is a pointer to a row structure (MI_ROW).
MI_NULL_VALUE
The retbuf value is an SQL NULL value.
MI_ERROR
The function was not successful.