Integer Binary Representations

The DataBlade API provides the following data types to support the binary representations of integer values.

One-Byte Integers

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

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

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

Two-Byte Integers

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

Use these integer data types to hold values for the SQL SMALLINT data type, which stores two-byte integer numbers that range from -32,767 to 32,767. For a description of the SQL SMALLINT data type, see the IBM 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 two-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.

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

DataBlade API Function

Description

mi_get_smallint( )

Copies an aligned two-byte integer, converting any difference in alignment or byte order on the client computer to that of the server computer

mi_put_smallint( )

Copies an aligned two-byte integer, converting any difference in alignment or byte order on the server computer to that of the client computer

mi_fix_smallint( )

Converts the specified two-byte integer to or from the type alignment and byte order of the client computer

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 two-byte integer (SMALLINT) values remain consistent when transferred to and from client applications. For more information, see Conversion of Opaque-Type Data with Computer-Specific Data Types.

Four-Byte Integers

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

Use these integer data types to hold values for the following SQL four-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 four-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 IBM 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 computer architectures. Use these integer data types instead of the native C types (such as int or long int). If you access four-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.

Eight-Byte Integers

The DataBlade API supports the following data types for eight-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 eight-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 eight-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 IBM 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 int8.h Header File

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.

Internal INT8 Format

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

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

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 Eight-Byte Integers (Server)

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

DataBlade API Function

Description

mi_get_int8( )

Copies an aligned eight-byte integer, converting any difference in alignment or byte order on the client computer to that of the server computer

mi_put_int8( )

Copies an aligned eight-byte integer, converting any difference in alignment or byte order on the server computer to that of the client computer

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 eight-byte integer (INT8) values remain aligned when transferred to and from client applications. For more information, see Conversion of Opaque-Type Data with Computer-Specific Data Types.

Converting INT8 Values

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.

Function Name

Description

ifx_int8cvasc( )

Converts a C char type value to an mi_int8 type value

ifx_int8cvdbl( )

Converts a C double (mi_double_precision) type value to an mi_int8 type value

ifx_int8cvdec( )

Converts a C mi_decimal type value to an mi_int8 type value

ifx_int8cvflt( )

Converts a C float (mi_real) type value to an mi_int8 type value

ifx_int8cvint( )

Converts a C two-byte integer value to an mi_int8 type value

ifx_int8cvlong( )

Converts a C four-byte integer value to an mi_int8 type value

ifx_int8toasc( )

Converts an mi_int8 type value to a text string

ifx_int8todbl( )

Converts an mi_int8 type value to a C double (mi_double_precision) type value

ifx_int8todec( )

Converts an mi_int8 type value to a mi_decimal type value

ifx_int8toflt( )

Converts an mi_int8 type value to a C float (mi_real) type value

ifx_int8toint( )

Converts an mi_int8 type value to a C two-byte integer value

ifx_int8tolong( )

Converts an mi_int8 type value to a C four-byte integer value

Performing Operations on Eight-Byte Values

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

Function Name

Description

ifx_int8add( )

Adds two mi_int8 numbers

ifx_int8cmp( )

Compares two mi_int8 numbers

ifx_int8copy( )

Copies an mi_int8 number

ifx_int8div( )

Divides two mi_int8 numbers

ifx_int8mul( )

Multiplies two mi_int8 numbers

ifx_int8sub( )

Subtracts two mi_int8 numbers

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