Creating a Row Type

To create a row type, you create a row structure (MI_ROW) that holds the row type. The mi_row_create( ) function is the constructor function for the row structure (MI_ROW). To create a row type with mi_row_create( ), you must provide the following information to the function:

• A row descriptor that describes the fields of the row type (or columns of a row)
• The values of the row-type fields (or row columns)

Creating the Row Descriptor

You create a new row descriptor for a row type with the mi_row_desc_create( ) function. The mi_row_desc_create( ) is the constructor function for a row descriptor. You provide this function with the type identifier of the row type for which you want the row descriptor. If you do not know the type identifier for your row type, use the mi_type_typename( ) function or mi_typestring_to_id( ) to create a type identifier based on the type name. The type name for a row type is its text representation. For more information, see Row-Type Text Representation.

Assigning the Field Values

To provide values for the columns (or fields) of a row structure, you pass information for the columns in several parallel arrays:

• Column-value array
• Column-value null array

These column-value arrays are similar to the column arrays in the row descriptor (see Figure 23). They have an element for each column in the row descriptor. The column-value arrays are different from the column arrays in the row descriptor, in the following ways:

• The column-value arrays describe the actual value for a column.

  Column arrays describe the column data type.

• You must allocate and manage the column-value arrays.

  The DataBlade API does not provide accessor functions for these column-value arrays. For each column, your DataBlade API module must declare, allocate, and assign values to these arrays.

All of the column-value arrays have zero-based indexes. Figure 24 shows how the information at index position 1 of these arrays holds the column-value information for the second column of a row.

Figure 24. Arrays for Initialization of Column

The following sections provide additional information about each of the column-value arrays.

Column-Value Array

The column-value array, col_values, is the third argument of the mi_row_create( ) function. Each element of the column-value array is a pointer to an MI_DATUM structure that holds the value for each column. The format of this value depends on whether the MI_DATUM value is passed by reference or by value:

• For C UDRs, the data type of the value determines the passing mechanism. If the function passes the value by value, the MI_DATUM structure contains the value. If the function passes value by reference, the MI_DATUM structure contains a pointer to the value.
• For client LIBMI applications, pass all values (regardless of data type) by reference. The MI_DATUM structure contains a pointer to the value.

For more information on the passing mechanism for an MI_DATUM value, see Contents of an MI_DATUM Structure.

Column-Value Null Array

The column-value null array, col_nulls, is the fourth argument of the mi_row_create( ) function. Each element of the column-value null array is either:

• MI_FALSE

  The column value is not an SQL NULL value.

• MI_TRUE

  The column value is an SQL NULL value.

Example: Creating a Row Type

Suppose you have the row type that the following SQL statement creates:

CREATE ROW TYPE rowtype_t
(
 id INTEGER,
 name CHAR(20)
);

/*
 * Create a row structure for the 'rowtype_t' row type
 */

   MI_CONNECTION *conn;
   MI_ROW_DESC *rowdesc;
   MI_ROW *row;
   MI_DATUM *values;
   mi_boolean *nulls;
   mi_integer num_cols;

/* Allocate a row descriptor for the 'rowtype_t' row type */
rowdesc = mi_row_desc_create(
         mi_typestring_to_id(conn, "rowtype_t"));

/* Assume number of columns is known */
num_cols = 2;

/* Allocate the 'col_values' and 'col_nulls' arrays */
values = mi_alloc(num_cols *sizeof(MI_DATUM));
nulls = mi_alloc(num_cols *sizeof(mi_boolean));

/* Populate the 'col_values' and 'col_nulls' arrays */

   /* Initialize value for field 1: 'id' */
   values[0] = 1;
   nulls[0] = MI_FALSE;
   
   /* Initialize value for field 2: 'name' */
   values[1] = mi_string_to_lvarchar("Dexter");
   nulls[1] = MI_FALSE;

/* Create row structure for 'name_t' */
row = mi_row_create(conn, rowdesc, values, nulls);

mi_integer col_val;
...
/* Initialize value for field 1: 'id' */
col_val = 1;
values[0] = &col_val;
nulls[0] = MI_FALSE;