A row descriptor, MI_ROW_DESC, is a 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 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 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
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 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 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. 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:
