Informix DataBlade API Programmer's Manual Accessing SQL Data Types

Figure 1-1 on page 1-11 lists the correspondences between SQL and DataBlade API data types. To declare a variable for an SQL data type, use the appropriate DataBlade API predefined data type or structure for the variable. The mi.h header file includes the header files for the definitions of all DataBlade API data types. Include mi.h in all DataBlade API modules that use DataBlade API data types.

The DataBlade API represents the SQL data type of a column value with the following data structures:

• A short name, called the type identifier, that identifies only the data type.
• A long name, called the type descriptor, that provides the data type and information about this type.

A type identifier, MI_TYPEID, is a DataBlade API structure that identifies a data type uniquely. For extended data types, the type identifier is database-dependent; that is, the same type identifier might identify different data types for different databases. You can determine the data type that a type identifier represents with the following DataBlade API functions.

Important: To a DataBlade API module, the type identifier (MI_TYPEID) is an opaque C data structure. Do not access its internal fields directly. Informix does not guarantee that the internal structure of a type identifier will not change in future releases. Therefore, to create portable code, always use the accessor functions for this structure to determine data type.

The DataBlade API uses type identifiers in the following situations.

A type descriptor, MI_TYPE_DESC, is a DataBlade API structure that contains information about an SQL data type. For built-in data types, this information comes from the syscolumns table. For extended data types, it contains the information in the sysxtdtypes table. Figure 2-1 lists the DataBlade API accessor functions that obtain information from a type descriptor.

Important: To a DataBlade API module, the type descriptor (MI_TYPE_DESC) is an opaque C structure. Do not access its internal fields directly. Informix does not guarantee that the internal structure of MI_TYPE_DESC will not change in future releases. Therefore, to create portable code, always use the accessor functions in Figure 2-1 to obtain values from this structure.

The DataBlade API uses type descriptors in the following situations.

You can use the following DataBlade API functions to obtain a type descriptor or type identifier.

A type descriptor for a data type and one for a column use the same accessor functions and share the same underlying data structures. However, these descriptors differ 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.

When you use type-descriptor accessor functions (see Figure 2-1 on page 2-6) on parameterized data types, the results depend on which kind of type descriptor you pass into the accessor function.

For example, Figure 2-2 shows a named row type with fields that have parameterized data types.

Figure 2-2 Sample Named Row Type With Parameterized Fields

Figure 2-3 shows a code fragment that 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-3 Type Descriptor and Column Type Descriptor for DATETIME field

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 DATETIME.

The following code fragment calls the mi_type_typename() and mi_type_qualifier() accessor functions on the type_desc type descriptor (which Figure 2-3 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 (0) 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 Figure 2-3 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. Figure 2-4 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 2-4 Type Descriptor and Column Type Descriptor for DECIMAL field

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 Figure 2-4 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 (0) 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 Figure 2-4 defines):

type_prec = mi_type_precision(col_type_desc2);

type_scale = mi_type_scale(col_type_desc2);

The mi_type_precision() and mi_type_scale() functions return the actual precision and scale of the DECIMAL column, 6 and 3, respectively.