Fetching Data
When mi_get_result() returns MI_ROWS, the database server is returning row data on the specified connection. The application must take the following steps to fetch the returned row:
1. Get a row descriptor for the row.
2. Get the number of columns from the row descriptor.
3. Fetch rows, one row at a time.
4. For every row fetched, get the value of every column.
Getting Row Descriptors
A row descriptor is an MI_ROW_DESC structure that describes the type of data in each column of the row. The two DataBlade API functions for getting a row descriptor are as follows:
Getting Column Information
The mi_column_count() function returns the number of columns in a row descriptor. A column that contains a row is counted as a single column.
The following DataBlade API function, given a row descriptor and a number representing the position of a column in the row descriptor, return information about the column:
Getting Rows
The function that actually fetches the rows is mi_next_row(). This function returns a handle to the current row as a pointer to an MI_ROW structure. It is normally called in a loop that terminates when mi_next_row() returns null, indicating that no more rows remain to be fetched.
As long as rows remain to be fetched, the DataBlade API cannot process the next statement that mi_exec() sends. The application must either continue to call mi_next_row() until it returns null or call mi_query_finish() if the loop is prematurely exited.
Getting Values
The mi_value() function extracts the individual column values from a row. This function is normally called in a loop that terminates when a value has been retrieved for every column in the row.
Important: The DataBlade API follows C numbering conventions, so column numbers are zero-based.
Example: get_data()
The user-defined function get_data() fetches data from a query. The following example assumes that all the rows are of the same type and therefore share the same row descriptor.
The get_data() function calls mi_get_row_desc_without_row() to get the row descriptor and mi_column_count() to get the number of columns. It then calls mi_column_name() in a FOR loop to get and print the names of the columns in the row descriptor.
In an outer loop, mi_next_row() gets every row. In an inner loop, mi_value() gets every value in the row. The pointer returned in the retbuf parameter of mi_value() is not valid after the next call to mi_value(). If the data were needed for later use, the data to which retbuf points would have to be copied into a previously defined variable.
Getting Row Values
In the get_data() example (page 7-8), the application assumes that all the returning values are simple, in which case mi_value() returns MI_NORMAL_VALUE. In some cases, however, a column value might be a row type, in which case mi_value() returns MI_ROW_VALUE.
A value is a row value if its column is a row value type (a named or unnamed type) or if the item being selected is a correlation variable that represents an entire row.
Important: A set, list, or multiset is a collection type, not a row type. The mi_value() function returns MI_COLLECTION_VALUE for a set-valued column.
|
