Informix DataBlade API Programmer's Manual Accessing SQL Data Types

The DataBlade API provides the following support for text and character data:

• Data types to hold character data
• Functions to process character data

The DataBlade API supports the following data types that can hold character data in a DataBlade API module.

Tip: The database server also supports the TEXT data type for character data. It stores TEXT character data as a simple large object. However, the DataBlade API does not directly support simple large objects. For more information, see Simple Large Objects.

mi_char1 and mi_unsigned_char1 Data Types

The mi_char1 and mi_unsigned_char1 data types hold a single-byte character. These data types can also hold an integer quantity within C code so you can also use mi_unsigned_char1 to hold unsigned one-byte integer values.

Important: To make your DataBlade API module portable, Informix recommends that you use the DataBlade API data type mi_char1 for single-character values instead of the native C-language counterpart, char. The mi_char1 data type ensures a consistent size across machine architectures.

The mi_char1 and mi_unsigned_char1 data types assume that one character uses one byte of storage. Therefore, do not use these data types to hold multibyte characters (which can require up to 4 bytes of storage). Instead, use the mi_char, mi_string, or mi_lvarchar data type. For more information on multibyte characters, see the Informix Guide to GLS Functionality.

The mi_char1 and mi_unsigned_char1 data types are guaranteed to be one byte on all computer architectures. Therefore, they can fit into an MI_DATUM and can be passed by value in C user-defined routines.

All data types, including mi_char1 and mi_unsigned_char1, must be passed by reference in client LIBMI applications.

The mi_char and mi_string data types are the DataBlade API equivalents of the char C-language data type. These two data types are exactly the same in both storage and functionality. Use them to declare characters strings in your DataBlade API module.

You can use the mi_char and mi_string data types to hold CHAR and VARCHAR data, as long as this data is not the argument or return values of a C UDR. For more information, see Character Data in C UDRs.

You can use the mi_char and mi_string data types to store multibyte characters (NCHAR and NVARCHAR columns). However, your code must track how many bytes each character contains. You can use the Informix GLS interface to assist with this process. For more information on multibyte characters, see the Informix Guide to GLS Functionality. For more information, see the Informix GLS Programmer's Manual.

The mi_char and mi_string 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_char and mi_string, must be passed by reference within client LIBMI applications.

The mi_lvarchar data type has the following uses:

• Holds data of an LVARCHAR column
• Holds data for character arguments and return values of C UDRs
• Holds the external format of an opaque data type

The following sections summarize each of these uses of an mi_lvarchar. For information about the structure of the mi_lvarchar data type, see Varying-Length Data Structures.

The SQL LVARCHAR data type stores variable-length character data that is potentially larger than 255 bytes. The LVARCHAR data type is a predefined opaque type (an opaque data type that Informix defines). The DataBlade API supports the LVARCHAR data type with the mi_lvarchar data type, which is implemented in the DataBlade API as a varying-length structure.

Tip: The SQL data type LVARCHAR and the DataBlade API data type mi_lvarchar are not exactly the same. Although you use mi_lvarchar to hold LVARCHAR data, mi_lvarchar is also used for other purposes.

For an LVARCHAR column, the maximum size for data is 2 kilobytes. The limitation is not inherent to the LVARCHAR data type. However, the maximum row size in a database table is limited to 32 kilobytes. Therefore, if an LVARCHAR column were to take the full supported size of 32 kilobytes, the table could contain only one column: a single LVARCHAR column.

If you attempt to insert more than 2 kilobytes into an LVARCHAR column, the result depends on the data type of the data:

• If the data comes from a built-in data type (such as CHAR or VARCHAR), the database server truncates the data to 2 kilobytes.
• If the data comes from an mi_lvarchar structure, the database server does not truncate the data. However, the database server does return an error.

Tip: If you need to store more than 2 kilobytes of text data, use the CLOB data type. The CLOB data type allows you to store the text data outside the database table, in an sbspace. For more information, see Chapter 6, Using Smart Large Objects.

Character Data in C UDRs

You must use the mi_lvarchar data type if your user-defined routine expects any of the SQL character data types as an argument or a return value. Within an MI_DATUM structure, the routine manager passes character data to and from a C UDR as a pointer to an mi_lvarchar varying-length structure. Therefore, a C UDR must handle text data as mi_lvarchar values when it receives arguments or returns data of an SQL character data type, as the following table describes.

External Format of an Opaque Data Type

The database server stores the external (text) format of an opaque data type as an mi_lvarchar varying-length structure. Therefore, the input and output support functions of an opaque type must handle the external format as an mi_lvarchar. For more information, see Input and Output Support Functions.

You can use a smart large object to store very large amounts of character data. The MI_LO_HANDLE data type holds a structure, called an LO handle, that identifies the location of smart-large-object data in a separate database partition, called an sbspace. For smart-large-object data that is character data, use the SQL CLOB data type. The CLOB data type allows you to store varying-length character data that is potentially larger than 32 kilobytes. The CLOB data type is a predefined opaque type (an opaque data type that Informix defines). For more information, see Chapter 6, Using Smart Large Objects.

The DataBlade API library provides the following functions to process character data:

• Transfer functions
• Conversion functions
• Operation functions

You can use these character-processing functions on NCHAR and NVARCHAR data. You can also use the character processing that the Informix GLS interface provides to handle multibyte characters. For more information, see the INFORMIX-GLS Programmer's Manual.

To transfer character data between different machine architectures, the DataBlade API provides the following functions that handle type alignment.

The mi_get_string() and mi_put_string() functions are useful in the send and receive support function of an opaque data type that contains character data (such as mi_string or mi_char). They ensure that character data remains 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 the binary and text representation of values.

Many DataBlade API functions expect to manipulate character data as an mi_lvarchar value. In addition, all SQL character data types are passed into a C UDR as an mi_lvarchar value. The DataBlade API provides the following functions to allow for conversion between a text (null-terminated string) representation of character data and its binary (internal) equivalent. The binary representation of character data is a varying-length structure (mi_lvarchar) equivalent.

The mi_lvarchar_to_string() and mi_string_to_lvarchar() functions are useful for converting between null-terminated strings and varying-length structures (whose data is not null-terminated).

The mi_lvarchar_to_string() and mi_string_to_lvarchar() functions are also useful in the input and output support functions of an opaque data type that contains mi_lvarchar values. They allow you to convert a string between its external format (text) and its internal format (mi_lvarchar) when transferred to and from client applications. For more information, see Converting Opaque-Type Data Between Text and Binary Representations.

For more information on the structure on an mi_lvarchar value, see Varying-Length Data Structures.

In addition, the DataBlade API library provides the following functions to convert text representation of values to their binary representations.

The ESQL/C function library provides the following functions that facilitate conversion of values in character data types (such as mi_string or mi_char) to and from some C-language data types.

In addition, the ESQL/C library provides the following functions to convert text representation of values to their binary representation.

The ESQL/C function library provides the following functions to perform operations on null-terminated strings.

The DataBlade API provides functions to obtain the following information about a character (CHAR and VARCHAR) data type:

• The data type: either its type name (string), type descriptor, or type identifier
• The precision: the maximum number of characters in the data type

The DataBlade API provides the following functions to obtain the type and precision of a character data type.