The mi_value_by_name() function
The mi_value_by_name() function retrieves a column value from a row, given the column name.
Syntax
mi_integer mi_value_by_name(row, column_name, retbuf, retlen)
MI_ROW *row;
char *column_name;
MI_DATUM *retbuf;
mi_integer *retlen;- row
- The row from which values are being extracted.
- column_name
- Name of the column for which the value is to be returned.
- retbuf
- A pointer to a location in the user space that is set to the address of a buffer that contains the returned value. This function allocates the buffer. You do not need to supply the buffer to contain the returned value.
- retlen
- The length of the returned column value.
| Valid in client LIBMI application? | Valid in user-defined routine? |
|---|---|
| Yes | Yes |
Usage
The mi_value_by_name() function returns the value for the column that the column_name column name specifies. It retrieves this column value from the row structure that row references. The only difference between the mi_value_by_name() and mi_value() function is that the former accesses a column by its name while the latter accesses it by column identifier. Like mi_value(), the mi_value_by_name() function is typically called in a loop that terminates when mi_value_by_name() has retrieved values for all the columns in the 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. The mi_value_by_name() function places the value in retbuf.
- MI_COLLECTION_VALUE
- The retbuf value A pointer to a collection structure (MI_COLLECTION).
- MI_ROW_VALUE
- The retbuf value A pointer to a row structure (MI_ROW).
- MI_NULL_VALUE
- The retbuf value A NULL value.
- MI_ERROR
- The function was not successful.