INFORMIX
DataBlade API Programmer's Manual
Chapter 12: DataBlade API Function Descriptions
Home Contents Index Master Index New Book

mi_value()

 The mi_value() function retrieves individual values from a row.

Syntax

Important: The "retbuf" parameter points to a character string representation of the value unless the query returning the value is a binary query (MI_QUERY_BINARY), in which case it points to binary data. See the discussion of the "control" parameter in the description of the mi_exec() function.

Usage

This function is typically called in a loop that terminates when mi_value() has retrieved values for all the columns in the row specified by row.

For the mi_value() function, the data returned in *retbuf is one of the following values:

    This is the case when mi_value() returns MI_NORMAL_VALUE and the mi_type_byvalue() function returns true, such as for integer columns. In this case, the application should cast retbuf to mi_integer, mi_smallint, or another data type before using the data.

    This is the case when mi_value() returns MI_NORMAL_VALUE, the mi_type_byvalue() function returns false, and the mi_type_length() function returns a positive value (most fixed-length data too long to fit in an MI_DATUM structure, such as DATETIME or double precision data). In this case, the application should cast retbuf to mi_double_precision *, mi_datetime *, or another data type before using the data.

    This is the case when mi_value() returns MI_NORMAL_VALUE, he mi_type_byvalue() function returns false, and the mi_type_length() function returns zero or less (variable length or character). In this case, the application should cast retbuf to mi_lvarchar * or mi_bitvarying *.

    This is the case when mi_value() returns MI_ROW_VALUE.

    This is the case when mi_value() returns MI_COLLECTION_VALUE.

The pointer returned in retbuf is valid until a new mi_exec() function is run or until the statement is dropped via mi_drop_prepared_statement(). However, the DataBlade API can overwrite the data in any of the following cases:

For example, if the column is a character column, the data in retbuf is a pointer to an mi_lvarchar structure. To save the data in the mi_lvarchar structure, you must copy it with the mi_var_copy() function. You can use a save set to save an entire row.

Return Values

MI_NORMAL_VALUE

The retbuf value is not a named row or a collection.

MI_COLLECTION_VALUE

The retbuf value is a pointer to a collection. In this case, mi_value() places a pointer to an MI_COLLECTION structure in retbuf that points to the collection. Use mi_collection_fetch() to retrieve collection values.

MI_ROW_VALUE

The retbuf value is a pointer to a named row. In this case, mi_value() places a pointer to an MI_ROW structure in retbuf that points to the named row. To extract the individual values from the named row, invoke mi_value() with the returned MI_ROW pointer.

MI_NULL_VALUE

The retbuf value is NULL.

MI_ERROR

The function was not successful.

Related Topics

 For additional information, see the descriptions of the following functions: mi_collection_fetch(), mi_next_row(), mi_save_set_insert(), and mi_value_by_name().

For more information about retrieving values, see "Getting Values".



DataBlade API Programmer's Manual, version 9.1
Copyright © 1998, Informix Software, Inc. All rights reserved.