Data type descriptors and column type descriptors

A type descriptor for a data type and a type descriptor for a column use the same accessor functions and share the same underlying data type structures. These descriptors differ, however, in the handling of parameterized data types (such as DATETIME, INTERVAL, DECIMAL, and money), as follows:
  • A data type descriptor holds unparameterized information, which is general information about the data type.
  • A column type descriptor holds parameterized information, which is the information for the data type of a particular column.

Data type information in a type descriptor lists the DataBlade® API accessor functions that obtain information from a type descriptor. When you use type-descriptor accessor functions on parameterized data types, the results depend on which kind of type descriptor you pass into the accessor function.

For example, the following code fragment shows a named row type with fields that have parameterized data types.
Figure 1. Sample named row type with parameterized fields
CREATE ROW TYPE row_type 
   (time_fld DATETIME YEAR TO SECOND, 
    dec_fld DECIMAL(6,3));
The following code fragment obtains a data type descriptor and a column type descriptor for the first field (time_fld) from the row descriptor (row_desc) for the row_type row type.
Figure 2. Type descriptor and column type descriptor for DATETIME field
type_id = mi_column_type_id(row_desc, 0);
type_desc = mi_type_typedesc(conn, type_id);
col_type_desc = mi_column_type_desc(row_desc, 0);
For the DATETIME data type of the time_fld column, the type-descriptor accessor functions obtain different qualifier information for each kind of type descriptor, as follows:
  • The data type descriptor, type_desc, stores the unparameterized type information for the DATETIME data type.
    The following code fragment calls the mi_type_typename() and mi_type_qualifier() accessor functions on the type_desc type descriptor (which Type descriptor and column type descriptor for DATETIME field defines):
    type_string = mi_type_typename(type_desc);
    type_scale = mi_type_qualifier(type_desc);

    The call to mi_type_typename() returns the string datetime as the unparameterized name of the data type. The call to mi_type_qualifier() returns zero as the type qualifier.

  • The column type descriptor, col_type_desc, stores the parameterized type information for the DATETIME field of row_type.
    The following code fragment calls the mi_type_typename() and mi_type_qualifier() accessor functions on the col_type_desc type descriptor (which Type descriptor and column type descriptor for DATETIME field defines):
    type_string = mi_type_typename(col_type_desc);
    type_scale = mi_type_qualifier(col_type_desc);
    The call to mi_type_typename() returns the string datetime year to second as the parameterized name of the data type. The call to mi_type_qualifier()returns the actual DATETIME qualifier of 3594, which is the encoded qualifier value for:
    TU_DTENCODE(TU_YEAR, TU_SECOND)
Similarly, for DECIMAL and MONEY data types, the type-descriptor accessor functions can obtain scale and precision information from a column type descriptor but not a data type descriptor. The following figure shows a code fragment that obtains a data type descriptor and a column type descriptor for the second field (dec_fld) from the row descriptor (row_desc) for the row_type row type.
Figure 3. Type descriptor and column type descriptor for DECIMAL field
type_id2 = mi_column_type_id( row_desc, 1 );
type_desc2 = mi_type_typedesc( conn, type_id2 );
col_type_desc2 = mi_column_type_desc( row_desc, 1 );
For the DECIMAL data type of the dec_fld column, the results from the type-descriptor accessor functions depend on which type descriptor you pass into the accessor function, as follows:
  • The data type descriptor, type_desc2, stores the unparameterized type information for DECIMAL.
    The following code fragment calls the mi_type_precision() and mi_type_scale() accessor functions on the type_desc2 type descriptor (which Type descriptor and column type descriptor for DECIMAL field defines):
    type_prec = mi_type_precision(type_desc2);
    type_scale = mi_type_scale(type_desc2);

    Both the mi_type_precision() and mi_type_scale() functions return zero for the precision and scale.

  • The column type descriptor, col_type_desc, stores the parameterized type information for the DECIMAL field of row_type.
    The following code fragment calls the mi_type_precision() and mi_type_scale() accessor functions on the col_type_desc2 type descriptor (which Type descriptor and column type descriptor for DECIMAL field defines):
    type_prec = mi_type_precision(col_type_desc2);
    type_scale = mi_type_scale(col_type_desc2);

    The mi_type_precision() function returns the actual precision of the DECIMAL column, 6. The mi_type_scale() function returns the actual precision scale of the DECIMAL column, 3.