Informix DataBlade API Programmer's Manual Using Numeric Data Types

Integer data is a value with no digits to the right of the decimal point. The DataBlade API provides support for integer values in both their text and binary representations.

The DataBlade API supports an integer value in text representation as a quoted string that contains the following characters.

An integer value in its text representation is often called an integer string. For example, the following integer string contains the value for 1,345:

"1,345"

In an integer string, the thousands separator is optional.

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 integer 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 integer values.

Tip: The internal format of the integer data types is often referred to as their binary representation.

One-Byte Integers

The DataBlade API supports the following data types for 1-byte integer values.

To hold unsigned 1-byte integers, you can also use the mi_unsigned_char1 data type.

Tip: The 1-byte integer data types have names that are not consistent with those of other integer data types. The mi_int1 data type is for an unsigned 1-byte integer while the mi_smallint, mi_integer, and mi_int8 data types are for the signed version of the 2-, 4-, and 8-byte integers, respectively. Use the mi_sint1 data type to hold a signed 1-byte integer value.

The DataBlade API ensures that these integer data types are 1 byte on all computer architectures. There is no corresponding SQL data type for one-byte integers.

The mi_int1 and mi_sint1 data types can fit into an MI_DATUM. Therefore, they can be passed by value within C user-defined routines.

All data types, including mi_int1 and mi_sint1, must be passed by reference within client LIBMI applications.

The DataBlade API supports the following data types for 2-byte integer values.

Use these integer data types to hold values for the SQL SMALLINT data type, which stores 2-byte integer numbers, which range from -32,767 to 32,767. For a description of the SQL SMALLINT data type, see the Informix Guide to SQL: Reference.

The mi_smallint and mi_unsigned_smallint data types hold the internal (binary) format of a SMALLINT value. The DataBlade API ensures that the mi_smallint and mi_unsigned_smallint data types are two bytes on all computer architectures. Use these integer data types instead of the native C types (such as short int). If you access 2-byte values stored in a SMALLINT in the database, but use the C short int type, conversion errors might arise if the two types are not the same size.

Important: To make your DataBlade API module portable across different architectures, Informix recommends use of the DataBlade API data type mi_smallint for 2-byte integer values instead of the native C-language counterpart. The mi_smallint data type handles the different sizes of integer values across computer architectures.

The mi_smallint and mi_unsigned_smallint data types can fit into an MI_DATUM. Therefore, they can be passed by value within C user-defined routines.

All data types, including mi_smallint and mi_unsigned_smallint, must be passed by reference within client LIBMI applications.

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

These DataBlade API functions are useful in the send and receive support functions of an opaque data type that contains mi_smallint values. They ensure that 2-byte integer (SMALLINT) values remain consistent when transferred to and from client applications. For more information, see Converting Opaque-Type Data With Machine-Specific Data Types.

The DataBlade API supports the following data types for 4-byte integer values.

Use these integer data types to hold values for the following SQL 4-byte integer data types:

• The SQL INTEGER data type can hold integer values in the range from -2,147,483,647 to 2,147,483,647.
• The SQL SERIAL data type holds 4-byte integer values that the database server automatically assigns when a value is inserted in the column.

For a description of the SQL INTEGER and SERIAL data types, see the Informix Guide to SQL: Reference.

The mi_integer and mi_unsigned_integer data types hold the internal (binary) format of an INTEGER or SERIAL value. The DataBlade API ensures that the mi_integer and mi_unsigned_integer data types are four bytes on all machine architectures. Use these integer data types instead of the native C types (such as int or long int). If you access 4-byte values stored in a INTEGER in the database, but use the C int type, conversion errors might arise if the two types are not the same size.

Important: To make your DataBlade API module portable across different architectures, Informix recommends use of the DataBlade API data type mi_integer for 4-byte integer values instead of the native C-language counterpart. The mi_integer data type handles the different sizes of integer values across computer architectures.

The mi_integer and mi_unsigned_integer data types can fit into an MI_DATUM. Therefore, they can be passed by value within a C user-defined routine.

All data types, including mi_integer and mi_unsigned_integer, must be passed by reference within client LIBMI applications.

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

The mi_get_integer() and mi_put_integer() functions are useful in the send and receive support functions of an opaque data type that contains mi_integer values. They ensure that 4-byte integer (INTEGER) values remain consistent when transferred to and from client applications. For more information, see Converting Opaque-Type Data With Machine-Specific Data Types.

The DataBlade API supports the following data types for 8-byte integer values.

The DataBlade API ensures that these integer data types are eight bytes on all computer architectures. Use these integer data types to hold values for the following SQL 8-byte integer data types:

• The SQL INT8 data type can hold integer values in the range from
  -9,223,372,036,854,775,807 to 9,223,372,036,854,775,807
  [or -(2⁶³-1) to 2⁶³-1].
• The SQL SERIAL8 data type holds 8-byte integer values that the database server automatically assigns when a value is inserted in the column.

For a description of the SQL INT8 and SERIAL8 data types, see the Informix Guide to SQL: Reference.

The mi_int8 and mi_unsigned_int8 data types hold the internal (binary) format of an INT8 or SERIAL8 value.

The mi_int8 and mi_unsigned_int8 data types cannot fit into an MI_DATUM. Therefore, they must be passed by reference within C user-defined routines.

All data types, including mi_int8 and mi_unsigned_int8, must be passed by reference within client LIBMI applications.

The int8.h header file contains the following declarations for use with the INT8 data type:

• The ifx_int8_t structure
• The INT8-type functions of the ESQL/C library

The mitypes.h header file automatically includes int8.h. In turn, the milib.h header file automatically includes mitypes.h, and mi.h automatically includes milib.h. Therefore, you automatically have access to the ifx_int8_t structure, the mi_int8 data type, or any of the ESQL/C INT8-type functions when you include mi.h in your DataBlade API module.

The INT8 data type stores 8-byte integers in an Informix-proprietary internal format: the ifx_int8_t structure. This structure allows the database to store 8-byte integers in a machine-independent format.

Tip: The internal format of the INT8 data type is often referred to as its binary representation.

The mi_int8 data type uses the ifx_int8_t structure to hold the binary representation of an INT8 value.

Important: The ifx_int8_t structure is an opaque C data structure to DataBlade API modules. Do not access its internal fields directly. Informix does not guarantee that the internal structure of ifx_int8_t will not change in future releases. ESQL/C INT8-Type Functions

Because the binary representation of an INT8 (and mi_int8) value is an Informix-proprietary format, you cannot use standard system functions to perform integer calculations on mi_int8 values. Instead, the DataBlade API provides support for the following categories of ESQL/C functions on the INT8 data type.

Any other operations, modifications, or analyses can produce unpredictable results.

Transferring 8-Byte Integers

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

The mi_get_int8() and mi_put_int8() functions are useful in the send and receive support function of an opaque data type that contains mi_int8 values. They ensure that 8-byte integer (INT8) values remain aligned when transferred to and from client applications. For more information, see Converting Opaque-Type Data With Machine-Specific Data Types.

The ESQL/C library provides the following functions that facilitate conversion of the binary representation of INT8 (mi_int8) values to and from some C-language data types.

Use the following ESQL/C library functions to perform arithmetic operations on INT8 (mi_int8) type values.

Any other operations, modifications, or analyses can produce unpredictable results.