A row descriptor

A row descriptor, MI_ROW_DESC, is a DataBlade® API structure that describes the type of data in each field of a row type.

The following table summarizes the memory operations for a row descriptor.


Memory duration	Memory operation	Function name
Current® memory duration	Constructor	mi_row_desc_create()
Current memory duration	Destructor	mi_row_desc_free()

Tip: A row descriptor can describe a row type or a row in a table. Therefore, you use the same DataBlade API functions to handle memory operations for a row descriptor when it describes a row type or a table row.

Server only:

In a C UDR, the row structure and row descriptor are part of the same data type structure. The row structure is just a data buffer in the row descriptor that holds the column values of a row. A one-to-one correspondence exists between the row descriptor (which mi_row_desc_create() allocates) and its row structure (which mi_row_create() allocates). Therefore:

When the mi_row_desc_create() function creates a row descriptor, it assigns a NULL-valued pointer to the data buffer.
The mi_row_desc_free() function frees both the row descriptor and its associated row structure.

Client only: In a client LIBMI application, a row structure and a row descriptor are separate data type structures. A one-to-many correspondence can exist between a row descriptor and its associated row structures. When you call mi_row_desc_free(), you free only the specified row descriptor.

The following table lists the DataBlade API accessor functions that obtain information about fields of a row type (or columns of a row) from the row descriptor.

Table 1. Field and column information in the row descriptor
Column information	DataBlade API accessor functions
The number of columns and/or fields in the row descriptor	mi_column_count()
The name of the column or field, given its position in the row	mi_column_name()
The column identifier, which is the position of the column or field within the row, given its name	mi_column_id()
The precision (total number of digits) of a column or field data type	mi_column_precision()
The scale of a column or field data type	mi_column_scale()
Whether a column or field in the row descriptor has the NOT NULL constraint	mi_column_nullable()
The type identifier of the column or field data type	mi_column_type_id()
The type descriptor of the column or field data type	mi_column_typedesc()
Default value of the column, if the column is defined with a default value	mi_column_default()
Default value of the column in text format	mi_column_default_string()

Restriction: To DataBlade API modules, the row descriptor (MI_row_DESC) is an opaque C data structure. Do not access its internal fields directly. The internal structure of MI_ROW_DESC might change in future releases. Therefore, to create portable code, always use the accessor functions for this structure to obtain column information.

The row descriptor stores column information in several parallel arrays.


Column array	Contents
Column-type ID array	Each element is a pointer to a type identifier (MI_TYPEID) that indicates the data type of the column.
Column-type-descriptor array	Each element is a pointer to a type descriptor (MI_TYPE_DESC) that describes the data type of the column.
Column-scale array	Each element is the scale of the column data type.
Column-precision array	Each element is the precision of the column data type.
Column-nullable array	Each element has either of the following values: MI_TRUE: The column can contain SQL NULL values. MI_FALSE: The column cannot contain SQL NULL values.

All of the column arrays in the row descriptor have zero-based indexes. Within the row descriptor, each column has a column identifier, which is a zero-based position of the column (or field) in the column arrays. When you need information about a column (or field), specify its column identifier to one of the row-descriptor accessor functions in Field and column information in the row descriptor.

Tip: The system catalog tables refer to the unique number that identifies a column definition as its column identifier. However, the DataBlade API refers to this number as a column number and the position of a column within the row structure as a column identifier. These two terms do not refer to the same value.

The following figure shows how the information at index position 1 of these arrays holds the column information for the second column in a row descriptor.

begin figure description - This figure is described in the surrounding text. - end figure description — Figure 1: Column arrays in the row descriptor

To access information for the nth column, provide an index value of n-1 to the appropriate accessor function in Field and column information in the row descriptor. The following calls to the mi_column_type_id() and mi_column_nullable() functions obtain from a row descriptor that row_desc identifies the type identifier (col_type) and whether the column is nullable (col_nullable) for the second column:

MI_ROW_DESC *row_desc;
MI_TYPEID *col_type;
mi_integer col_nullable;
...
col_type = mi_column_type_id(row_desc, 1);
col_nullable = mi_column_nullable(row_desc, 1);

To obtain the number of columns in the row descriptor (which is also the number of elements in the column arrays), use the mi_column_count() function.