The mi_row_create() function

The mi_row_create() function creates a row, based on a row descriptor and column data.

Syntax

MI_ROW *mi_row_create(conn, row_desc, col_values, col_nulls)
   MI_CONNECTION  *conn;
   MI_ROW_DESC *row_desc;
   MI_DATUM col_values[];
   mi_boolean col_nulls[];
conn
A pointer to a connection descriptor established by a previous call to mi_open(), mi_server_connect(), or mi_server_reconnect().
row_desc
A pointer to the row descriptor that describes the columns of the row.
col_values
An array of MI_DATUM structures that contain the values of the columns in the row (or fields in a row type).
col_nulls
An array that indicates whether a column holds an SQL NULL value. Each array element is set to one of the following values:
1 (MI_TRUE)
The value of the associated column is an SQL NULL value.
0 (MI_FALSE)
The value of the associated column is not an SQL NULL value.
Valid in client LIBMI application? Valid in user-defined routine?
Yes Yes

Usage

The mi_row_create() function takes the column data that the col_values and col_nulls arrays hold and creates a row structure that holds this data, based on the column information in the row descriptor that row_desc references. The function returns a pointer to the new row structure (MI_ROW) that it creates. The mi_row_create() function is the constructor function for the row structure.

The col_values array holds the values for each column of the row. This array sends the column values as MI_DATUM values. The mi_row_create() function expects the col_values value for a CHAR(n) or NCHAR(n) column in its binary representation (in an mi_lvarchar variable-length structure). The mi_row_create() function does perform a deep copy of the array values; that is, it copies both the pointer and its associated memory into the new row structure.

Server only: The mi_row_create() function allocates a new row structure with the PER_COMMAND memory duration. Values in the col_values array can be passed by reference or by value, depending on the data type of the value.

In a C UDR, the row structure and row descriptor are part of the same data structure. To create a row structure, the mi_row_create() function just adds a data buffer, which holds copies of the values in the col_values and col_nulls arrays, to the row descriptor that row_desc references. The address of this row structure is the address of the data buffer within the row descriptor. There is a one-to-one correspondence between a row descriptor and its row structure.

When you call mi_row_create() twice with the same row descriptor, the second call overwrites the column values of the first call, as follows:
  • In the first call, the mi_row_create() function just adds a data buffer to the specified row descriptor and copies the column values for the row into this data buffer.
  • If you call mi_row_create() a second time with the same row descriptor, this second call copies the new column values into the row structure associated with this row descriptor.

This behavior can be beneficial in that it saves a call to mi_row_free() for the first data buffer. However, it does overwrite the column values from the first mi_row_create() call with the new column values.

Client only: Values in the col_values array must be pass by reference for all data types.

In a client LIBMI application, the row structure and row descriptor are separate data structures. There is a one-to-many correspondence between a row descriptor and its associated row structures. When you call mi_row_create() a second time on the same row descriptor, you obtain a second row structure that points to the same row descriptor.

Return values

An MI_ROW pointer
A pointer to the newly created row.
NULL
The function was not successful.