Informix DataBlade API Programmer's Manual Using Numeric Data Types

A floating-point value is a large decimal value that is stored in a fixed field width. Because the field width is fixed, a floating-point number that is larger than the field width only retains its most significant digits. That is, digits that do not fit into the fixed width are dropped (rounded or truncated).

The DataBlade API provides support for the following kinds of floating-point data (which correspond to existing SQL data types).

These floating-point values have both text and binary representations.

The DataBlade API supports a floating-point value in text representation as a quoted string that contains the following characters.

For example, the following integer string contains the value for 1,345.77431:

"1,345.77431"

In a floating-point string, the thousands separator is optional.

Important: Because floating-point numbers retain only their most significant digits, the number that you enter in this type of column and the number the database server displays can differ slightly.

A locale defines the end-user format for numeric values. The end-user format is the format in which data appears in a client application when the data is a literal string or character variable. The preceding floating-point string is the end-user format for the default locale, U.S. English. A nondefault locale can define an end-user format that is particular to a country or culture outside the U.S. For more information, see the Informix Guide to GLS Functionality.

The DataBlade API provides the following data types to support the binary representations of floating-point values.

When you define a column with the DECIMAL(p) data type, the syntax of this definition specifies a floating-point value for the column. This value has a total of p (<= 32) significant digits (its precision). DECIMAL(p) has an absolute value range between 10-130 and 1012⁴.

Tip: The DECIMAL data type can also declare a fixed-point value with the syntax DECIMAL(p,s). For more information, see DECIMAL Data Type: Fixed-Point Data. For a complete description of the DECIMAL data type, see the "Informix Guide to SQL: Reference."

The mi_decimal data type stores floating-point DECIMAL values as well as fixed-point values. Therefore, information about mi_decimal in Fixed-Point Data also applies to mi_decimal when it contains a floating-point value. In particular, the following statements are true.

The mi_decimal data type cannot fit into an MI_DATUM. Therefore, it must be passed by reference within C user-defined routines.

All data types, including mi_decimal, must be passed by reference within client LIBMI applications.

The SQL SMALLFLOAT data type can hold single-precision floating-point values. The DataBlade API supports the SMALLFLOAT data type with the mi_real data type. The mi_real data type stores internal SMALLFLOAT values, as 32-bit floating-point values.

Although an mi_real value can fit into an MI_DATUM, this data type is always passed by reference. Unlike other 4-byte values, mi_real values cannot be passed by value. All values greater than 4 bytes are passed by reference.

Therefore, if a user-defined routine is called from an SQL statement, the database server passed a pointer to any mi_real arguments; it does not pass the actual value. Similarly, if a user-defined function returns an mi_real value to an SQL statement, you must allocate space for the value, fill this space, and return a pointer to this space.

DataBlade API modules that are not invoked from SQL statements may pass mi_real values by value. However, for consistency, you might want to pass them by reference.

All data types, including mi_real, must be passed by reference within client LIBMI applications.

Important: To make your DataBlade API module portable across different architectures, Informix recommends that you use the DataBlade API data type, mi_real, instead of the native C-language counterpart, float. The mi_real data type handles the different sizes of small floating-point values across computer architectures.

The FLOAT Data Type

The SQL FLOAT data type can hold double-precision floating-point values. The DataBlade API supports the FLOAT data type with the mi_double_precision data type. The mi_double_precision data type stores internal FLOAT values, as 64-bit floating-point values.

The mi_double_precision data type cannot fit into an MI_DATUM. Therefore, it must be passed by reference within C user-defined routines.

All data types, including mi_double_precision, must be passed by reference within client LIBMI applications.

Important: To make your DataBlade API module portable across different architectures, Informix recommends that you use the DataBlade API data type, mi_double_precision, instead of the native C-language counterpart, double. The mi_double_precision data type handles the different sizes of large floating-point values across computer architectures.

Transferring Floating-Point Data

To transfer floating-point data between different computer architectures, the DataBlade API provides the following functions that handle type alignment and byte order.

The mi_get_decimal(), mi_get_double_precision(), mi_get_real(), mi_put_decimal(), mi_put_double_precision(), and mi_put_real() functions are useful in the send and receive support function of an opaque data type that contains mi_decimal, mi_double_precision, or mi_real values. They ensure that floating-point (DECIMAL, FLOAT, or SMALLFLOAT) values remain aligned when transferred to and from client applications. For more information, see Converting Opaque-Type Data With Machine-Specific Data Types.

Both the DataBlade API library and the ESQL/C library provide functions that convert between floating-point decimal strings and internal DECIMAL formats. For more information, see Converting Decimal Data.

The DataBlade API provides the following functions to obtain the precision of a floating-point DECIMAL (DECIMAL(p)).

Tip: The FLOAT and SMALLFLOAT data types do not have precision and scale values.